perlapi

СОДЕРЖАНИЕ

НАЗВАНИЕ
ОПИСАНИЕ
Функции работы с массивами
Функции обратного вызова
Изменение регистра символов
Классификация символов
Клонирование интерпретатора
Схемы обвязки области видимости во время компиляции
Хэши подсказок COP
Чтение подсказок COP
Пользовательские операторы
Функции работы с CV
Переменные xsubpp и внутренние функции
Утилиты отладки
Функции отображения и вывода
Функции встраивания
Макросы обработки исключений (простые)
Функции из файла pp_sort.c
Функции из файла scope.c
Функции из файла vutil.c
Значения "Gimme"
Глобальные переменные
Функции GV
Полезные значения
Функции работы с хешем
Управление хуками
Интерфейс лексического анализатора
Функции и макросы, связанные с локалью
Магические функции
Управление памятью
Разные функции
Функции MRO
Функции multicall
Числовые функции
Устаревшие функции обратной совместимости
Построение Optree
Функции работы с Optree
Упаковка и распаковка
Структуры данных Pad
Переменные на уровне интерпретатора
Функции REGEXP
Макросы управления стеком
Флаги SV
Функции работы с SV
Поддержка Unicode
Переменные, созданные xsubpp и внутренними функциями xsubpp
Предупреждения и завершение работы
Недокументированные функции
АВТОРЫ
СМОТРИТЕ ТАКЖЕ

НАЗВАНИЕ

perlapi - автоматически сгенерированная документация для публичного API Perl

ОПИСАНИЕ

Этот файл содержит документацию для публичного API Perl, сгенерированную embed.pl. В частности, он содержит список функций, макросов, флагов и переменных, которые могут быть использованы разработчиками расширений. В конце находится список функций, которые еще не задокументированы. Интерфейс этих функций может быть изменен без предварительного уведомления. Все, что не указано здесь, не является частью публичного API и не должно использоваться разработчиками расширений. По этим причинам следует избегать слепого использования функций, перечисленных в proto.h, при написании расширений.

В Perl, в отличие от C, строка символов может обычно содержать встроенные NUL символы. Иногда в документации строка Perl называется "буфером", чтобы отличить её от строки C, но иногда они обе называются просто строками.

Обратите внимание, что все глобальные переменные API Perl должны быть обработаны с префиксом PL_. Опять же, те, что не перечислены здесь, не должны использоваться разработчиками расширений и могут быть изменены или удалены без предварительного уведомления; то же относится и к макросам. Некоторые макросы предоставляются для совместимости со старыми, необработанными именами, но эта поддержка может быть отключена в будущих выпусках.

Perl изначально был написан для обработки только US-ASCII (это символы, у которых порядковые номера находятся в диапазоне 0-127). И документация, и комментарии могут по-прежнему использовать термин ASCII, когда на самом деле подразумевается весь диапазон от 0 до 255.

Символы с кодами, не являющимися ASCII, ниже 256, могут иметь различные значения в зависимости от различных факторов. (См., прежде всего, perllocale). Но обычно весь диапазон может быть обозначен как ISO-8859-1. Часто термин "Latin-1" (или "Latin1") используется как эквивалент ISO-8859-1. Но некоторые люди рассматривают "Latin1" как относящийся только к символам в диапазоне от 128 до 255 или иногда от 160 до 255. В этой документации "Latin1" и "Latin-1" используются для обозначения всех 256 символов.

Обратите внимание, что Perl можно скомпилировать и запустить как под ASCII, так и под EBCDIC (См. perlebcdic). Большая часть документации (и даже комментарии в коде) игнорирует возможность EBCDIC. Для почти всех целей эти различия прозрачны. Например, под EBCDIC вместо UTF-8 используется UTF-EBCDIC для кодирования строк Unicode, и поэтому всякий раз, когда в этой документации упоминается utf8 (и варианты этого имени, включая в именах функций), это также (практически прозрачно) означает UTF-EBCDIC. Но порядковые номера символов отличаются между ASCII, EBCDIC и UTF-кодировками, и строка, закодированная в UTF-EBCDIC, может занимать другое количество байтов, чем в UTF-8.

Список ниже упорядочен по алфавиту, регистронезависимо.

Функции работы с массивами

av_clear

Освобождает все элементы массива, оставляя его пустым. Эквивалент XS для @array = (). См. также "av_undef".

Обратите внимание, что действия деструктора, вызываемого напрямую или косвенно при освобождении элемента массива, могут привести к уменьшению счётчика ссылок самого массива (например, путём удаления записи в таблице символов). Поэтому существует вероятность, что массив AV может быть освобождён (или даже перевыделен) по возвращении из вызова, если вы не держите ссылку на него.

void    av_clear(AV *av)

av_create_and_push

ПРИМЕЧАНИЕ: эта функция экспериментальная и может быть изменена или удалена без предварительного уведомления.

Добавляет SV в конец массива, создавая массив при необходимости. Вспомогательная функция для сокращения часто повторяющихся шаблонов кода.

void    av_create_and_push(AV **const avp,
                           SV *const val)

av_create_and_unshift_one

Вставляет SV в начало массива, создавая массив при необходимости. Вспомогательная функция для сокращения часто повторяющихся шаблонов кода.

SV**    av_create_and_unshift_one(AV **const avp,
                                  SV *const val)

av_delete

Удаляет элемент с индексом key из массива, делает элемент смертельным и возвращает его. Если flags равно G_DISCARD, элемент освобождается, и возвращается NULL. NULL также возвращается, если key находится за пределами диапазона.

Эквивалент Perl: splice(@myarray, $key, 1, undef) (с splice в контексте void, если G_DISCARD присутствует).

SV*     av_delete(AV *av, SSize_t key, I32 flags)

av_exists

Возвращает true, если элемент с индексом key был инициализирован.

Это основано на том, что неинициализированные элементы массива устанавливаются в NULL.

Эквивалент Perl: exists($myarray[$key]).

bool    av_exists(AV *av, SSize_t key)

av_extend

Предварительное расширение массива. key — индекс, до которого должен быть расширен массив.

void    av_extend(AV *av, SSize_t key)

av_fetch

Возвращает SV по указанному индексу в массиве. key — индекс. Если lval истинно, вы гарантированно получите реальный SV (в случае, если он не был реальным ранее), который затем можно изменить. Проверьте, что возвращаемое значение не равно null, прежде чем использовать его для получения SV*.

См. "Понимание магии связанных хэшей и массивов" в perlguts для получения дополнительной информации о том, как использовать эту функцию для связанных массивов.

Примерный эквивалент Perl: $myarray[$key].

SV**    av_fetch(AV *av, SSize_t key, I32 lval)

AvFILL

То же, что и av_top_index() или av_tindex().

int     AvFILL(AV* av)

av_fill

Устанавливает максимальный индекс в массиве заданным числом, эквивалентно Perl's $#array = $fill;.

Количество элементов в массиве будет fill + 1 после того, как av_fill() вернётся. Если массив был короче, то добавленные элементы устанавливаются в NULL. Если массив был длиннее, то избыточные элементы освобождаются. av_fill(av, -1) то же самое, что и av_clear(av).

void    av_fill(AV *av, SSize_t fill)

av_len

То же, что и "av_top_index". Обратите внимание, что, вопреки названию, она возвращает максимальный индекс в массиве, поэтому для получения размера массива вам нужно использовать av_len(av) + 1. Это отличается от "sv_len", которая возвращает ожидаемое значение.

SSize_t av_len(AV *av)

av_make

Создаёт новый массив AV и заполняет его списком SV. SV копируются в массив, поэтому их можно освободить после вызова av_make. Новый AV будет иметь счётчик ссылок 1.

Эквивалент Perl: my @new_array = ($scalar1, $scalar2, $scalar3...);

AV*     av_make(SSize_t size, SV **strp)

av_pop

Удаляет один SV из конца массива, уменьшая его размер на единицу и возвращая SV (передавая контроль над одной ссылкой) вызывающей стороне. Возвращает &PL_sv_undef если массив пуст.

Эквивалент Perl: pop(@myarray);

SV*     av_pop(AV *av)

av_push

Добавляет SV (передавая контроль над одной ссылкой) в конец массива. Массив автоматически увеличится, чтобы вместить добавление.

Эквивалент Perl: push @myarray, $val;.

void    av_push(AV *av, SV *val)

av_shift

Удаляет один SV из начала массива, уменьшая его размер на единицу и возвращая SV (передавая контроль над одной ссылкой) вызывающей стороне. Возвращает &PL_sv_undef если массив пуст.

Эквивалент Perl: shift(@myarray);

SV*     av_shift(AV *av)

av_store

Сохраняет SV в массиве. Индекс массива указан как key. Возвращаемое значение будет NULL в случае неудачи операции или если значение не нужно было фактически хранить в массиве (как в случае связанных массивов). В противном случае, можно обратиться к SV* , которое было сохранено там (= val).

Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счётчика ссылок val перед вызовом и уменьшение его, если функция вернула NULL.

Приблизительный эквивалент Perl: splice(@myarray, $key, 1, $val).

SV**    av_store(AV *av, SSize_t key, SV *val)

av_tindex

То же, что и av_top_index().

int     av_tindex(AV* av)

av_top_index

Возвращает максимальный индекс в массиве. Количество элементов в массиве составляет av_top_index(av) + 1. Возвращает -1, если массив пуст.

Эквивалент Perl для этого: $#myarray.

(Несколько более короткая форма: av_tindex.)

SSize_t av_top_index(AV *av)

av_undef

Дезактивирует массив. Эквивалент XS для undef(@array).

Помимо освобождения всех элементов массива (как и av_clear()), также освобождается память, используемая av для хранения списка скаляров.

См. "av_clear" для примечания о том, что массив может быть недействительным по возвращении.

void    av_undef(AV *av)

av_unshift

Вставляет указанное количество undef значений в начало массива. Массив автоматически увеличится, чтобы вместить добавление.

Эквивалент Perl: unshift @myarray, ((undef) x $num);

void    av_unshift(AV *av, SSize_t num)

get_av

Возвращает AV указанного Perl-глобального или пакетного массива с заданным именем (не работает с лексическими переменными). flags передаются в gv_fetchpv. Если GV_ADD установлено и Perl-переменная не существует, она будет создана. Если flags равно нулю и переменная не существует, возвращается NULL.

Эквивалент Perl: @{"$name"}.

ПРИМЕЧАНИЕ: форма perl_ этой функции устарела.

AV*     get_av(const char *name, I32 flags)

newAV

Создаёт новый AV. Счётчик ссылок установлен в 1.

Эквивалент Perl: my @array;.

AV*     newAV()

sortsv

Сортирует массив указателей SV на месте с использованием заданной функции сравнения.

В настоящее время всегда используется сортировка слиянием. См. "sortsv_flags" для более гибкой функции.

void    sortsv(SV** array, size_t num_elts,
               SVCOMPARE_t cmp)

Функции обратного вызова

call_argv

Выполняет обратный вызов указанной Perl-подпрограмме с именем и объявленной в пакете с argv (массивом строк, завершаемым NULL) в качестве аргументов. См. perlcall.

Приблизительный Perl-эквивалент: &{"$sub_name"}(@$argv).

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_argv(const char* sub_name, I32 flags,
                  char** argv)

call_method

Выполняет обратный вызов указанному Perl-методу. Освящённый объект должен находиться в стеке. См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_method(const char* methname, I32 flags)

call_pv

Выполняет обратный вызов указанной Perl-подпрограмме. См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_pv(const char* sub_name, I32 flags)

call_sv

Выполняет обратный вызов Perl-подпрограмме, указанной в SV.

Если ни флаг G_METHOD, ни флаг G_METHOD_NAMED не заданы, SV может быть любой из CV, GV, ссылкой на CV, ссылкой на GV или SvPV(sv) будет использовано в качестве имени вызываемой подпрограммы.

Если задан флаг G_METHOD, SV может быть ссылкой на CV или SvPV(sv) будет использовано в качестве имени вызываемого метода.

Если задан флаг G_METHOD_NAMED, SvPV(sv) будет использовано в качестве имени вызываемого метода.

Некоторые другие значения обрабатываются специально для внутреннего использования и не должны использоваться.

См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_sv(SV* sv, volatile I32 flags)

ENTER

Открывающая скобка обратного вызова. См. "LEAVE" и perlcall.

ENTER;

ENTER_with_name(name)

То же, что и "ENTER", но при включенном отладке также связывает переданную строку с новым областью.

ENTER_with_name(name);

eval_pv

Указывает Perl на eval указанную строку в контексте скаляра и возвращает результат SV*.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

SV*     eval_pv(const char* p, I32 croak_on_error)

eval_sv

Указывает Perl на eval строку в SV. Поддерживает те же флаги, что и call_sv, за исключением очевидного исключения G_EVAL. См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     eval_sv(SV* sv, I32 flags)

FREETMPS

Закрывающая скобка для временных переменных в обратном вызове. См. "SAVETMPS" и perlcall.

FREETMPS;

LEAVE

Закрывающая скобка в обратном вызове. См. "ENTER" и perlcall.

LEAVE;

LEAVE_with_name(name)

То же, что и "LEAVE", но при включённой отладке сначала проверяет, что область имеет заданное имя. name должно быть литеральной строкой.

LEAVE_with_name(name);

SAVETMPS

Открывающая скобка для временных переменных в обратном вызове. См. "FREETMPS" и perlcall.

SAVETMPS;

Изменение регистра символов

Perl использует полные Unicode-преобразования регистра. Это означает, что преобразование одного символа в другой регистр может привести к последовательности из более чем одного символа. Например, заглавная буква ß (маленькая латинская буква с острым S) представляет собой последовательность из двух символов SS. Это создаёт некоторые сложности. Строчные буквы всех символов в диапазоне 0..255 — это одиночные символы, и поэтому "toLOWER_L1" предоставлен. Но toUPPER_L1 не может существовать, так как не смог бы возвращать корректный результат для всех допустимых входных данных. Вместо этого "toUPPER_uvchr" имеет API, которое позволяет возвращать все возможные корректные результаты.) Точно так же не реализована и никакая другая функция, которая бы не смогла дать корректные результаты для всего диапазона возможных входных данных.

toFOLD

Преобразует указанный символ в регистр ссылок. Если входное значение не является заглавной буквой ASCII, то возвращается сам входной символ. Вариант toFOLD_A эквивалентен. (Нет эквивалента to_FOLD_L1 для всего диапазона Latin1, так как там нужна полная общность "toFOLD_uvchr".)

U8      toFOLD(U8 ch)

toFOLD_utf8

Это похоже на "toFOLD_utf8_safe", но не имеет параметра e. Поэтому функция не может проверить, не выходит ли она за пределы строки. Начиная с Perl v5.30, она будет принимать параметр e, став синонимом для toFOLD_utf8_safe. В это время каждый использующий её программист должен будет изменить программу для успешной компиляции. Тем временем, первый вызов во время выполнения toFOLD_utf8 из каждой точки вызова в программе будет выводить предупреждение об устаревании, включенное по умолчанию. Вы можете сейчас преобразовать свою программу для использования toFOLD_utf8_safe, чтобы избежать предупреждений и получить дополнительную защиту, или же можете подождать до v5.30, когда вам будет необходимо добавить параметр e.

UV      toFOLD_utf8(U8* p, U8* s, STRLEN* lenp)

toFOLD_utf8_safe

Преобразует первый символ UTF-8 в последовательности, начиная с p и не выходя за пределы e - 1, в его форму ссылок и сохраняет это значение в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байтов, так как форма ссылок может быть длиннее исходного символа.

Возвращается первый код символа преобразованной формы (но обратите внимание, как объясняется в начале этого раздела здесь, что может быть больше).

Суффикс _safe в имени функции указывает, что она не будет пытаться читать за пределы e - 1, при условии, что ограничение s < e истинно (это утверждается в сборках -DDEBUGGING). Если UTF-8 для входного символа каким-либо образом имеет неверный формат, программа может выдавать ошибку или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и может измениться в будущих выпусках.

UV      toFOLD_utf8_safe(U8* p, U8* e, U8* s,
                         STRLEN* lenp)

toFOLD_uvchr

Преобразует код символа cp в его форму ссылок и сохраняет это значение в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как родной, если он меньше 256; в противном случае как Юникод. Обратите внимание, что буфер, на который указывает s, должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байтов, так как форма ссылок может быть длиннее исходного символа.

UV      toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)

toLOWER

Преобразует указанный символ в нижний регистр. Если входное значение не является строчной буквой ASCII, то возвращается сам входной символ. Вариант toLOWER_A эквивалентен.

U8      toLOWER(U8 ch)

toLOWER_L1

Преобразует указанный символ Latin1 в нижний регистр. Результаты не определены, если входное значение не помещается в один байт.

U8      toLOWER_L1(U8 ch)

toLOWER_LC

Преобразует указанный символ в нижний регистр, используя правила текущей локали, если это возможно; в противном случае возвращается сам входной символ.

U8      toLOWER_LC(U8 ch)

toLOWER_utf8

Это похоже на "toLOWER_utf8_safe", но не имеет параметра e. Поэтому функция не может проверить, не выходит ли она за пределы строки. Начиная с Perl v5.30, она будет принимать параметр e, став синонимом для toLOWER_utf8_safe. В это время каждый использующий её программист должен будет изменить программу для успешной компиляции. Тем временем, первый вызов во время выполнения toLOWER_utf8 из каждой точки вызова в программе будет выводить предупреждение об устаревании, включенное по умолчанию. Вы можете сейчас преобразовать свою программу для использования toLOWER_utf8_safe, чтобы избежать предупреждений и получить дополнительную защиту, или же можете подождать до v5.30, когда вам будет необходимо добавить параметр e.

UV      toLOWER_utf8(U8* p, U8* s, STRLEN* lenp)

toLOWER_utf8_safe

Преобразует первый символ UTF-8 в последовательности, начиная с p и не выходя за пределы e - 1, в его форму нижнего регистра и сохраняет это значение в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байтов, так как форма нижнего регистра может быть длиннее исходного символа.

UV      toLOWER_utf8_safe(U8* p, U8* e, U8* s,
                          STRLEN* lenp)

toLOWER_uvchr

Преобразует код символа cp в его форму нижнего регистра и сохраняет это значение в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как родной, если он меньше 256; в противном случае как Юникод. Обратите внимание, что буфер, на который указывает s, должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байтов, так как форма нижнего регистра может быть длиннее исходного символа.

UV      toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)

toTITLE

Преобразует указанный символ в заглавный регистр. Если входное значение не является строчной буквой ASCII, то возвращается сам входной символ. Вариант toTITLE_A эквивалентен. (Нет toTITLE_L1 для всего диапазона Latin1, так как нужна полная общность "toTITLE_uvchr". Заглавный регистр не является концепцией, используемой в обработке локали, поэтому нет функциональности для этого.)

U8      toTITLE(U8 ch)

toTITLE_utf8

Это похоже на "toLOWER_utf8_safe", но не имеет параметра e. Поэтому функция не может проверить, не выходит ли она за пределы строки. Начиная с Perl v5.30, она будет принимать параметр e, став синонимом для toTITLE_utf8_safe. В это время каждый использующий её программист должен будет изменить программу для успешной компиляции. Тем временем, первый вызов во время выполнения toTITLE_utf8 из каждой точки вызова в программе будет выводить предупреждение об устаревании, включенное по умолчанию. Вы можете сейчас преобразовать свою программу для использования toTITLE_utf8_safe, чтобы избежать предупреждений и получить дополнительную защиту, или же можете подождать до v5.30, когда вам будет необходимо добавить параметр e.

UV      toTITLE_utf8(U8* p, U8* s, STRLEN* lenp)

toTITLE_utf8_safe

Преобразует первый символ UTF-8 в последовательности, начиная с p и не выходя за пределы e - 1, в его заглавный регистр и сохраняет это значение в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байтов, так как форма заглавного регистра может быть длиннее исходного символа.

UV      toTITLE_utf8_safe(U8* p, U8* e, U8* s,
                          STRLEN* lenp)

toTITLE_uvchr

Преобразует код символа cp в его форму заглавного регистра и сохраняет это значение в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как родной, если он меньше 256; в противном случае как Юникод. Обратите внимание, что буфер, на который указывает s, должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байтов, так как форма заглавного регистра может быть длиннее исходного символа.

UV      toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)

toUPPER

Преобразует указанный символ в верхний регистр. Если входное значение не является строчной буквой ASCII, то возвращается сам входной символ. Вариант toUPPER_A эквивалентен.

U8      toUPPER(U8 ch)

toUPPER_utf8

Это похоже на "toUPPER_utf8_safe", но не имеет параметра e. Поэтому функция не может проверить, не выходит ли она за пределы строки. Начиная с Perl v5.30, она будет принимать параметр e, став синонимом для toUPPER_utf8_safe. В это время каждый использующий её программист должен будет изменить программу для успешной компиляции. Тем временем, первый вызов во время выполнения toUPPER_utf8 из каждой точки вызова в программе будет выводить предупреждение об устаревании, включенное по умолчанию. Вы можете сейчас преобразовать свою программу для использования toUPPER_utf8_safe, чтобы избежать предупреждений и получить дополнительную защиту, или же можете подождать до v5.30, когда вам будет необходимо добавить параметр e.

UV      toUPPER_utf8(U8* p, U8* s, STRLEN* lenp)

toUPPER_utf8_safe

Преобразует первый символ, закодированный в UTF-8, в последовательности, начинающейся с p и не выходящей за пределы e - 1, в его верхний регистр и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s , должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байт, так как версия верхнего регистра может быть длиннее исходного символа.

Возвращается первый код символа преобразованной в верхний регистр версии (но обратите внимание, как объяснено в начале этого раздела, что может быть больше).

Суффикс _safe в имени функции указывает, что она не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это утверждается для -DDEBUGGING сборок). Если UTF-8 для входного символа каким-то образом некорректен, программа может завершиться с ошибкой, или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможностью изменения в будущих выпусках.

UV      toUPPER_utf8_safe(U8* p, U8* e, U8* s,
                          STRLEN* lenp)

toUPPER_uvchr

Преобразует код символа cp в его верхний регистр и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как собственный, если он меньше 256; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает s , должен быть по крайней мере UTF8_MAXBYTES_CASE+1 байт, так как версия верхнего регистра может быть длиннее исходного символа.

Возвращается первый код символа преобразованной в верхний регистр версии (но обратите внимание, как объяснено в начале этого раздела, что может быть больше.)

UV      toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)

Классификация символов

В этом разделе рассматриваются функции (на самом деле макросы), которые классифицируют символы по типам, таким как знаки препинания по отношению к буквенным и т. д. Большинство из них аналогичны классам символов регулярных выражений. (См. "POSIX Character Classes" в perlrecharclass.) Существует несколько вариантов для каждого класса. (Не все макросы имеют все варианты; каждый элемент ниже перечисляет допустимые для него.) Ни на один из них не влияет use bytes, и только те из них, в имени которых есть LC, зависят от текущего языка.

Базовая функция, например, isALPHA(), принимает октет (либо char, либо U8) в качестве входных данных и возвращает логическое значение о том, является ли символ, представленный этим октетом (или, на платформах, не использующих ASCII, соответствует ли он) ASCII-символом в указанном классе на основе платформы, Unicode и правил Perl. Если входные данные — число, не помещающееся в октет, возвращается FALSE.

Вариант isFOO_A (например, isALPHA_A()) идентичен базовой функции без суффикса "_A". Этот вариант используется для акцентирования в своем названии того, что только символы из диапазона ASCII могут вернуть TRUE.

Вариант isFOO_L1 накладывает на платформу наборы символов Latin-1 (или эквивалент EBCDIC). То есть, на символы ASCII не влияет, так как ASCII является подмножеством Latin-1. Но не-ASCII символы обрабатываются так, как если бы они были символами Latin-1. Например, isWORDCHAR_L1() вернёт true, если вызывать её с кодом символа 0xDF, который является символом слова как в ASCII, так и в EBCDIC (хотя он представляет разные символы в каждом).

Вариант isFOO_uvchr похож на вариант isFOO_L1, но принимает любой код UV-символа в качестве входных данных. Если код символа больше 255, используются правила Unicode для определения принадлежности к классу символов. Например, isWORDCHAR_uvchr(0x100) возвращает TRUE, так как 0x100 — это ЗАГЛАВНАЯ БУКВА A С ДИАРЕЗИСОМ в Unicode и является символом слова.

Вариант isFOO_utf8_safe похож на isFOO_uvchr, но используется для строк, закодированных в UTF-8. Каждый вызов классифицирует один символ, даже если строка содержит много. Этот вариант принимает два параметра. Первый, p, — указатель на первый байт классифицируемого символа. (Помните, что для представления символа в строках UTF-8 может потребоваться более одного байта.) Второй параметр, e, указывает на любое место в строке, находящееся за пределами первого символа, вплоть до одного байта после конца всей строки. Суффикс _safe в имени функции указывает, что она не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это утверждается для -DDEBUGGING сборок). Если UTF-8 для входного символа каким-то образом некорректен, программа может завершиться ошибкой, или функция может вернуть FALSE по усмотрению реализации и с возможностью изменения в будущих выпусках.

Вариант isFOO_utf8 похож на isFOO_utf8_safe, но принимает только один параметр, p, который имеет тот же смысл, что и соответствующий параметр в isFOO_utf8_safe. Таким образом, функция не может проверить, читает ли она за пределами конца строки. Начиная с Perl v5.30, она будет принимать второй параметр, став синонимом для isFOO_utf8_safe. В это время каждый использующий её программам придётся измениться, чтобы успешно компилироваться. Тем временем первый вызов во время выполнения isFOO_utf8 из каждой точки вызова в программе вызовет предупреждение о depreкации, включённое по умолчанию. Вы можете сейчас перевести свою программу на использование isFOO_utf8_safe, чтобы избежать предупреждений и получить дополнительную защиту, или вы можете подождать до v5.30, когда вы будете вынуждены добавить параметр e.

Вариант isFOO_LC похож на варианты isFOO_A и isFOO_L1, но результат основан на текущем языке, что и означает LC в названии. Если Perl может определить, что текущий язык — UTF-8, он использует опубликованные правила Unicode; в противном случае он использует функцию C-библиотеки, которая даёт указанную классификацию. Например, isDIGIT_LC(), когда не находится в языке UTF-8, возвращает результат вызова isdigit(). FALSE всегда возвращается, если входные данные не помещаются в октет. На некоторых платформах, где известно, что функция C-библиотеки имеет дефекты, Perl меняет свой результат, чтобы соответствовать правилам стандарта POSIX.

Вариант isFOO_LC_uvchr похож на isFOO_LC, но определяется для любого UV. Он возвращает то же, что и isFOO_LC для кодов символов меньше 256, и возвращает жёстко заданные, не зависящие от языка, результаты Unicode для больших.

Вариант isFOO_LC_utf8_safe похож на isFOO_LC_uvchr, но используется для строк, закодированных в UTF-8. Каждый вызов классифицирует один символ, даже если строка содержит много. Этот вариант принимает два параметра. Первый, p, — указатель на первый байт классифицируемого символа. (Помните, что для представления символа в строках UTF-8 может потребоваться более одного байта.) Второй параметр, e, указывает на любое место в строке, находящееся за пределами первого символа, вплоть до одного байта после конца всей строки. Суффикс _safe в имени функции указывает, что она не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это утверждается для -DDEBUGGING сборок). Если UTF-8 для входного символа каким-то образом некорректен, программа может завершиться с ошибкой, или функция может вернуть FALSE по усмотрению реализации и с возможностью изменения в будущих выпусках.

Вариант isFOO_LC_utf8 похож на isFOO_LC_utf8_safe, но принимает только один параметр, p, который имеет тот же смысл, что и соответствующий параметр в isFOO_LC_utf8_safe. Таким образом, функция не может проверить, читает ли она за пределами конца строки. Начиная с Perl v5.30, она будет принимать второй параметр, став синонимом для isFOO_LC_utf8_safe. В это время каждый использующий её программам придётся измениться, чтобы успешно компилироваться. Тем временем первый вызов во время выполнения isFOO_LC_utf8 из каждой точки вызова в программе вызовет предупреждение о depreкации, включённое по умолчанию. Вы можете сейчас перевести свою программу на использование isFOO_LC_utf8_safe, чтобы избежать предупреждений и получить дополнительную защиту, или вы можете подождать до v5.30, когда вы будете вынуждены добавить параметр e.

isALPHA

Возвращает логическое значение, указывающее, является ли указанный символ буквенным символом, аналогично m/[[:alpha:]]/. См. начало этого раздела для объяснения вариантов isALPHA_A, isALPHA_L1, isALPHA_uvchr, isALPHA_utf8_safe, isALPHA_LC, isALPHA_LC_uvchr, и isALPHA_LC_utf8_safe.

bool    isALPHA(char ch)

isALPHANUMERIC

Возвращает логическое значение, указывающее, является ли указанный символ буквенным символом или десятичной цифрой, аналогично m/[[:alnum:]]/. См. начало этого раздела для объяснения вариантов isALPHANUMERIC_A, isALPHANUMERIC_L1, isALPHANUMERIC_uvchr, isALPHANUMERIC_utf8_safe, isALPHANUMERIC_LC, isALPHANUMERIC_LC_uvchr, и isALPHANUMERIC_LC_utf8_safe.

bool    isALPHANUMERIC(char ch)

isASCII

Возвращает логическое значение, указывающее, является ли указанный символ одним из 128 символов набора символов ASCII, аналогично m/[[:ascii:]]/. В не-ASCII платформах, возвращает ИСТИНА, если этот символ соответствует ASCII символу. Варианты isASCII_A() и isASCII_L1() идентичны isASCII(). См. начало этого раздела для объяснения вариантов isASCII_uvchr, isASCII_utf8_safe, isASCII_LC, isASCII_LC_uvchr, и isASCII_LC_utf8_safe. Обратите внимание, однако, что некоторые платформы не имеют функцию C библиотеки isascii(). В этих случаях, варианты, имена которых содержат LC, эквивалентны соответствующим вариантам без него.

Также обратите внимание, что, так как все ASCII символы являются UTF-8 инвариантными (то есть они имеют то же самое представление (всегда один байт) независимо от того, закодированы ли они в UTF-8 или нет), isASCII даст правильные результаты при вызове с любым байтом в любой строке, закодированной или нет в UTF-8. И аналогично isASCII_utf8_safe будет работать корректно на любой строке, закодированной или нет в UTF-8.

bool    isASCII(char ch)

isBLANK

Возвращает логическое значение, указывающее, является ли указанный символ символом, считающимся пробелом, аналогично m/[[:blank:]]/. См. начало этого раздела для объяснения вариантов isBLANK_A, isBLANK_L1, isBLANK_uvchr, isBLANK_utf8_safe, isBLANK_LC, isBLANK_LC_uvchr, и isBLANK_LC_utf8_safe. Обратите внимание, однако, что некоторые платформы не имеют функцию C библиотеки isblank(). В этих случаях, варианты, имена которых содержат LC, эквивалентны соответствующим вариантам без него.

bool    isBLANK(char ch)

isCNTRL

Возвращает логическое значение, указывающее, является ли указанный символ управляющим символом, аналогично m/[[:cntrl:]]/. См. начало этого раздела для объяснения вариантов isCNTRL_A, isCNTRL_L1, isCNTRL_uvchr, isCNTRL_utf8_safe, isCNTRL_LC, isCNTRL_LC_uvchr, и isCNTRL_LC_utf8_safe. В платформах EBCDIC, почти всегда необходимо использовать вариант isCNTRL_L1.

bool    isCNTRL(char ch)

isDIGIT

Возвращает логическое значение, указывающее, является ли указанный символ цифрой, аналогично m/[[:digit:]]/. Варианты isDIGIT_A и isDIGIT_L1 идентичны isDIGIT. См. начало этого раздела для объяснения вариантов isDIGIT_uvchr, isDIGIT_utf8_safe, isDIGIT_LC, isDIGIT_LC_uvchr, и isDIGIT_LC_utf8_safe.

bool    isDIGIT(char ch)

isGRAPH

Возвращает логическое значение, указывающее, является ли указанный символ графическим символом, аналогично m/[[:graph:]]/. См. начало этого раздела для объяснения вариантов isGRAPH_A, isGRAPH_L1, isGRAPH_uvchr, isGRAPH_utf8_safe, isGRAPH_LC, isGRAPH_LC_uvchr, и isGRAPH_LC_utf8_safe.

bool    isGRAPH(char ch)

isIDCONT

Возвращает логическое значение, указывающее, может ли указанный символ быть вторым или последующим символом идентификатора. Это очень близко к, но не совсем то же самое, что официальное свойство Unicode XID_Continue. Разница в том, что это возвращает true только если входной символ также соответствует "isWORDCHAR". См. начало этого раздела для объяснения вариантов isIDCONT_A, isIDCONT_L1, isIDCONT_uvchr, isIDCONT_utf8_safe, isIDCONT_LC, isIDCONT_LC_uvchr, и isIDCONT_LC_utf8_safe.

bool    isIDCONT(char ch)

isIDFIRST

Возвращает логическое значение, указывающее, может ли указанный символ быть первым символом идентификатора. Это очень близко к, но не совсем то же самое, что официальное свойство Unicode XID_Start. Разница в том, что это возвращает true только если входной символ также соответствует "isWORDCHAR". См. начало этого раздела для объяснения вариантов isIDFIRST_A, isIDFIRST_L1, isIDFIRST_uvchr, isIDFIRST_utf8_safe, isIDFIRST_LC, isIDFIRST_LC_uvchr, и isIDFIRST_LC_utf8_safe.

bool    isIDFIRST(char ch)

isLOWER

Возвращает логическое значение, указывающее, является ли указанный символ строчной буквой, аналогично m/[[:lower:]]/. См. начало этого раздела для объяснения вариантов isLOWER_A, isLOWER_L1, isLOWER_uvchr, isLOWER_utf8_safe, isLOWER_LC, isLOWER_LC_uvchr, и isLOWER_LC_utf8_safe.

bool    isLOWER(char ch)

isOCTAL

Возвращает логическое значение, указывающее, является ли указанный символ восьмеричной цифрой [0-7]. Единственные два варианта isOCTAL_A и isOCTAL_L1; каждый идентичен isOCTAL.

bool    isOCTAL(char ch)

isPRINT

Возвращает логическое значение, указывающее, является ли указанный символ печатаемым символом, аналогично m/[[:print:]]/. См. начало этого раздела для объяснения вариантов isPRINT_A, isPRINT_L1, isPRINT_uvchr, isPRINT_utf8_safe, isPRINT_LC, isPRINT_LC_uvchr, и isPRINT_LC_utf8_safe.

bool    isPRINT(char ch)

isPSXSPC

(аббревиатура от Posix Space) Начиная с версии 5.18, этот вариант во всех своих формах идентичен соответствующим isSPACE() макросам. Варианты, учитывающие локаль, идентичны соответствующим isSPACE() вариантам во всех выпусках Perl. В выпусках до 5.18, не учитывающие локаль, варианты отличаются от isSPACE() вариантов только тем, что isSPACE() варианты не соответствуют вертикальной табуляции, а isPSXSPC() варианты соответствуют. В остальном они идентичны. Таким образом, этот макрос аналогичен тому, что m/[[:space:]]/ соответствует в регулярном выражении. См. начало этого раздела для объяснения вариантов isPSXSPC_A, isPSXSPC_L1, isPSXSPC_uvchr, isPSXSPC_utf8_safe, isPSXSPC_LC, isPSXSPC_LC_uvchr, и isPSXSPC_LC_utf8_safe.

bool    isPSXSPC(char ch)

isPUNCT

Возвращает логическое значение, указывающее, является ли указанный символ символом пунктуации, аналогично m/[[:punct:]]/. Обратите внимание, что определение пунктуации не такое прямое, как хотелось бы. См. "POSIX Character Classes" в perlrecharclass для подробностей. См. начало этого раздела для объяснения вариантов isPUNCT_A, isPUNCT_L1, isPUNCT_uvchr, isPUNCT_utf8_safe, isPUNCT_LC, isPUNCT_LC_uvchr, и isPUNCT_LC_utf8_safe.

bool    isPUNCT(char ch)

isSPACE

Возвращает логическое значение, указывающее, является ли указанный символ символом пробела. Это аналогично тому, что m/\s/ соответствует в регулярном выражении. Начиная с Perl 5.18, это также соответствует тому, что делает m/[[:space:]]/. До версии 5.18, только варианты этого макроса, учитывающие локаль (те, в которых есть LC в их именах), точно соответствовали тому, что делал m/[[:space:]]/. В этих выпусках единственное различие в вариантах, не учитывающих локаль, заключалось в том, что isSPACE() не соответствовал вертикальной табуляции. (См. "isPSXSPC" для макроса, соответствующего вертикальной табуляции во всех выпусках.) См. начало этого раздела для объяснения вариантов isSPACE_A, isSPACE_L1, isSPACE_uvchr, isSPACE_utf8_safe, isSPACE_LC, isSPACE_LC_uvchr, и isSPACE_LC_utf8_safe.

bool    isSPACE(char ch)

isUPPER

Возвращает логическое значение, указывающее, является ли указанный символ заглавной буквой, аналогично m/[[:upper:]]/. См. начало этого раздела для объяснения вариантов isUPPER_A, isUPPER_L1, isUPPER_uvchr, isUPPER_utf8_safe, isUPPER_LC, isUPPER_LC_uvchr, и isUPPER_LC_utf8_safe.

bool    isUPPER(char ch)

isWORDCHAR

Возвращает логическое значение, указывающее, является ли указанный символ символом слова, аналогично тому, как m/\w/ и m/[[:word:]]/ соответствуют в регулярном выражении. Символ слова – это буквенный символ, десятичная цифра, соединительный символ пунктуации (например, нижнее подчёркивание) или символ "метки", прикреплённый к одному из этих символов (например, некоторые типы акцентов). isALNUM() – синоним, предоставленный для обратной совместимости, хотя символ слова включает больше, чем стандартное значение символа слова в языке C в плане алфавитно-цифровых значений. См. начало этого раздела для объяснения вариантов isWORDCHAR_A, isWORDCHAR_L1, isWORDCHAR_uvchr, и isWORDCHAR_utf8_safe. isWORDCHAR_LC, isWORDCHAR_LC_uvchr, и isWORDCHAR_LC_utf8_safe также описаны там, но дополнительно включают системное нижнее подчёркивание платформы.

bool    isWORDCHAR(char ch)

isXDIGIT

Возвращает булево значение, указывающее, является ли указанный символ шестнадцатеричной цифрой. В диапазоне ASCII это [0-9A-Fa-f]. Варианты isXDIGIT_A() и isXDIGIT_L1() идентичны isXDIGIT(). См. начало этого раздела для объяснения вариантов isXDIGIT_uvchr, isXDIGIT_utf8_safe, isXDIGIT_LC, isXDIGIT_LC_uvchr, и isXDIGIT_LC_utf8_safe.

bool    isXDIGIT(char ch)

Клонирование интерпретатора

perl_clone

Создает и возвращает новый интерпретатор, клонируя текущий.

perl_clone принимает эти флаги в качестве параметров:

CLONEf_COPY_STACKS - используется для, ну, копирования стеков также, без него мы только клонируем данные и обнуляем стеки, с ним мы копируем стеки и новый интерпретатор Perl готов к выполнению в точной той же точке, что и предыдущий. Псевдо-код fork использует COPY_STACKS, в то время как threads->create нет.

CLONEf_KEEP_PTR_TABLE - perl_clone сохраняет ptr_table со значением указателя старой переменной в качестве ключа и новой переменной в качестве значения, это позволяет проверить, была ли что-то клонировано, и не клонировать это снова, а просто использовать значение и увеличить счётчик ссылок. Если KEEP_PTR_TABLE не установлен, то perl_clone удалит ptr_table, используя функцию ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;, причина сохранения этого - если вы хотите дублировать некоторые свои собственные переменные, которые находятся за пределами графа сканирования Perl, пример такого кода находится в threads.xs create.

CLONEf_CLONE_HOST - Это элемент win32, он игнорируется в unix, он сообщает коду win32host Perl (который на C++) клонировать себя, это необходимо в win32, если вы хотите запустить две нити одновременно, если вы хотите просто сделать что-то в отдельном интерпретаторе Perl, а затем выбросить его и вернуться к исходному, вам ничего не нужно делать.

PerlInterpreter* perl_clone(
                     PerlInterpreter *proto_perl,
                     UV flags
                 )

Временные метки области видимости во время компиляции

BhkDISABLE

ПРИМЕЧАНИЕ: эта функция является экспериментальной и может быть изменена или удалена без предварительного уведомления.

Временно отключает запись в этой структуре BHK, очистив соответствующий флаг. which - это препроцессорный токен, указывающий, какую запись отключить.

void    BhkDISABLE(BHK *hk, which)

BhkENABLE

Включает запись в этой структуре BHK, установив соответствующий флаг. which - это препроцессорный токен, указывающий, какую запись включить. Это будет подтверждаться (при -DDEBUGGING), если запись не содержит действительного указателя.

void    BhkENABLE(BHK *hk, which)

BhkENTRY_set

Устанавливает запись в структуре BHK и устанавливает флаги, чтобы указать, что она действительна. which - это препроцессорный токен, указывающий, какую запись установить. Тип ptr зависит от записи.

void    BhkENTRY_set(BHK *hk, which, void *ptr)

blockhook_register

Регистрирует набор временных меток, которые будут вызваны при изменении лексической области видимости Perl во время компиляции. См. "Временные метки области видимости во время компиляции" в perlguts.

ПРИМЕЧАНИЕ: эта функция должна быть явно вызвана как Perl_blockhook_register с параметром aTHX_.

void    Perl_blockhook_register(pTHX_ BHK *hk)

Хэши подсказок COP

cophh_2hv

Генерирует и возвращает стандартный хэш Perl, представляющий полный набор пар ключ/значение в хэше подсказок cop cophh. flags в настоящее время не используется и должен быть равен нулю.

HV *    cophh_2hv(const COPHH *cophh, U32 flags)

cophh_copy

Создаёт и возвращает полную копию хэша подсказок cop cophh.

COPHH * cophh_copy(COPHH *cophh)

cophh_delete_pv

Как "cophh_delete_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

COPHH * cophh_delete_pv(const COPHH *cophh,
                        const char *key, U32 hash,
                        U32 flags)

cophh_delete_pvn

Удаляет ключ и его связанное значение из хэша подсказок cop cophh, и возвращает измененный хэш. Возвращаемый указатель хэша, как правило, не совпадает с указателем хэша, который был передан. Входной хэш потребляется функцией, и указатель на него не должен использоваться впоследствии. Используйте "cophh_copy", если вам нужны оба хэша.

Ключ задаётся значениями keypv и keylen. Если flags имеет установленный бит COPHH_KEY_UTF8, байты ключа интерпретируются как UTF-8, в противном случае они интерпретируются как Latin-1. hash - предварительно вычисленный хэш строки ключа или ноль, если он не был предварительно вычислен.

COPHH * cophh_delete_pvn(COPHH *cophh,
                         const char *keypv,
                         STRLEN keylen, U32 hash,
                         U32 flags)

cophh_delete_pvs

Как "cophh_delete_pvn", но принимает строку-литерал вместо пары строка/длина и без предварительно вычисленного хэша.

COPHH * cophh_delete_pvs(const COPHH *cophh,
                         "literal string" key,
                         U32 flags)

cophh_delete_sv

Как "cophh_delete_pvn", но принимает скаляр Perl вместо пары строка/длина.

COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
                        U32 hash, U32 flags)

cophh_fetch_pv

Как "cophh_fetch_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

SV *    cophh_fetch_pv(const COPHH *cophh,
                       const char *key, U32 hash,
                       U32 flags)

cophh_fetch_pvn

Ищет запись в хэше подсказок cop cophh с ключом, заданным keypv и keylen. Если flags имеет установленный бит COPHH_KEY_UTF8, байты ключа интерпретируются как UTF-8, в противном случае они интерпретируются как Latin-1. hash - предварительно вычисленный хэш строки ключа или ноль, если он не был предварительно вычислен. Возвращает смертный скалярную копию значения, связанного с ключом, или &PL_sv_placeholder если значение, связанное с ключом, отсутствует.

SV *    cophh_fetch_pvn(const COPHH *cophh,
                        const char *keypv,
                        STRLEN keylen, U32 hash,
                        U32 flags)

cophh_fetch_pvs

Как "cophh_fetch_pvn", но принимает строку-литерал вместо пары строка/длина и без предварительно вычисленного хэша.

SV *    cophh_fetch_pvs(const COPHH *cophh,
                        "literal string" key, U32 flags)

cophh_fetch_sv

Как "cophh_fetch_pvn", но принимает скаляр Perl вместо пары строка/длина.

SV *    cophh_fetch_sv(const COPHH *cophh, SV *key,
                       U32 hash, U32 flags)

cophh_free

Отбрасывает хэш подсказок cop cophh, освобождая все ресурсы, связанные с ним.

void    cophh_free(COPHH *cophh)

cophh_new_empty

Генерирует и возвращает новый пустой хэш подсказок cop, не содержащий записей.

COPHH * cophh_new_empty()

cophh_store_pv

Как "cophh_store_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

COPHH * cophh_store_pv(const COPHH *cophh,
                       const char *key, U32 hash,
                       SV *value, U32 flags)

cophh_store_pvn

Сохраняет значение, связанное с ключом, в хэше подсказок cop cophh, и возвращает измененный хэш. Возвращаемый указатель хэша, как правило, не совпадает с указателем хэша, который был передан. Входной хэш потребляется функцией, и указатель на него не должен использоваться впоследствии. Используйте "cophh_copy", если вам нужны оба хэша.

value - скалярное значение для хранения по этому ключу. value копируется этой функцией, которая, следовательно, не берет на себя ответственность за любую ссылку на него, и последующие изменения скаляра не будут отражены в значении, видимом в хэше подсказок cop. Сложные типы скаляров не будут храниться с целостностью ссылок, а будут преобразованы в строки.

COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
                        STRLEN keylen, U32 hash,
                        SV *value, U32 flags)

cophh_store_pvs

Как "cophh_store_pvn", но принимает строку-литерал вместо пары строка/длина и без предварительно вычисленного хэша.

COPHH * cophh_store_pvs(const COPHH *cophh,
                        "literal string" key, SV *value,
                        U32 flags)

cophh_store_sv

Как "cophh_store_pvn", но принимает скаляр Perl вместо пары строка/длина.

COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
                       U32 hash, SV *value, U32 flags)

Чтение подсказок COP

cop_hints_2hv

Генерирует и возвращает стандартный Perl-хэш, представляющий полный набор записей подсказок в cop cop. flags в настоящее время не используется и должен быть равен нулю.

HV *    cop_hints_2hv(const COP *cop, U32 flags)

cop_hints_fetch_pv

Аналогично "cop_hints_fetch_pvn", но принимает строку с нулевым окончанием вместо пары "строка/длина".

SV *    cop_hints_fetch_pv(const COP *cop,
                           const char *key, U32 hash,
                           U32 flags)

cop_hints_fetch_pvn

Ищет запись подсказки в cop cop с ключом, заданным keypv и keylen. Если flags имеет установленный бит COPHH_KEY_UTF8, байты ключа интерпретируются как UTF-8, в противном случае как Latin-1. hash — предварительно вычисленный хэш строки ключа или ноль, если он не был вычислен. Возвращает смертный скалярный копию значения, связанного с ключом, или &PL_sv_placeholder если нет значения, связанного с ключом.

SV *    cop_hints_fetch_pvn(const COP *cop,
                            const char *keypv,
                            STRLEN keylen, U32 hash,
                            U32 flags)

cop_hints_fetch_pvs

Аналогично "cop_hints_fetch_pvn", но принимает строку-литерал вместо пары "строка/длина" и без предварительно вычисленного хэша.

SV *    cop_hints_fetch_pvs(const COP *cop,
                            "literal string" key,
                            U32 flags)

cop_hints_fetch_sv

Аналогично "cop_hints_fetch_pvn", но принимает Perl-скаляр вместо пары "строка/длина".

SV *    cop_hints_fetch_sv(const COP *cop, SV *key,
                           U32 hash, U32 flags)

Операторы пользовательского определения

custom_op_register

Регистрирует оператор пользовательского определения. См. "Операторы пользовательского определения" в perlguts.

ПРИМЕЧАНИЕ: эта функция должна вызываться явно как Perl_custom_op_register с параметром aTHX_.

void    Perl_custom_op_register(pTHX_ 
                                Perl_ppaddr_t ppaddr,
                                const XOP *xop)

custom_op_xop

Возвращает структуру XOP для данного оператора пользовательского определения. Этот макрос следует считать внутренним для OP_NAME и других макросов доступа: используйте их вместо него. Этот макрос вызывает функцию. До версии 5.19.6 это реализовывалось как функция.

ПРИМЕЧАНИЕ: эта функция должна вызываться явно как Perl_custom_op_xop с параметром aTHX_.

const XOP * Perl_custom_op_xop(pTHX_ const OP *o)

XopDISABLE

Временно отключает элемент XOP, очищая соответствующий флаг.

void    XopDISABLE(XOP *xop, which)

XopENABLE

Включает элемент XOP, который был отключен.

void    XopENABLE(XOP *xop, which)

XopENTRY

Возвращает элемент структуры XOP. which — cpp-токен, указывающий, какой элемент вернуть. Если элемент не установлен, возвращается значение по умолчанию. Тип возвращаемого значения зависит от which. Этот макрос оценивает свои аргументы более одного раза. Если вы используете Perl_custom_op_xop для получения XOP * из OP *, используйте более эффективный "XopENTRYCUSTOM" вместо него.

XopENTRY(XOP *xop, which)

XopENTRYCUSTOM

Точно так же, как XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which), но более эффективно. Параметр which идентичен "XopENTRY".

XopENTRYCUSTOM(const OP *o, which)

XopENTRY_set

Устанавливает элемент структуры XOP. which — cpp-токен, указывающий, какой элемент установить. См. "Операторы пользовательского определения" в perlguts для получения подробной информации о доступных элементах и о том, как они используются. Этот макрос оценивает свой аргумент более одного раза.

void    XopENTRY_set(XOP *xop, which, value)

XopFLAGS

Возвращает флаги XOP.

U32     XopFLAGS(XOP *xop)

Функции манипулирования CV

В этом разделе описываются функции для манипулирования CV (значениями кода или подпрограммами). Для получения дополнительной информации см. perlguts.

caller_cx

Аналог caller() для авторов XSUB. Возвращаемая структура PERL_CONTEXT позволяет получить всю информацию, возвращаемую Perl вызовом caller. Обратите внимание, что XSUB не имеют стековой рамки, поэтому caller_cx(0, NULL) вернет информацию для непосредственно окружающего Perl-кода.

Эта функция пропускает автоматические вызовы &DB::sub от имени отладчика. Если запрошенная стековая рамка была подпрограммой, вызываемой DB::sub, возвращаемое значение будет рамкой для вызова DB::sub, поскольку она содержит правильный номер строки и т. д. для места вызова. Если dbcxp не NULL, он будет установлен в указатель на рамку для вызова подпрограммы.

const PERL_CONTEXT * caller_cx(
                         I32 level,
                         const PERL_CONTEXT **dbcxp
                     )

CvSTASH

Возвращает хэш-таблицу (stash) CV. Stash — это хэш символьной таблицы, содержащий переменные, относящиеся к пакетам, в котором была определена подпрограмма. Для получения дополнительной информации см. perlguts.

Это также имеет специальное применение с XS AUTOLOAD подпрограммами. См. "Автозагрузка с XSUB" в perlguts.

HV*     CvSTASH(CV* cv)

find_runcv

Находит CV, соответствующую текущей выполняемой подпрограмме или eval. Если db_seqp не null, пропускаются CV из пакета DB и *db_seqp заполняется последовательностью cop в момент входа кода DB::. (Это позволяет отладчикам выполнять eval в области точки останова, а не в области самого отладчика.)

CV*     find_runcv(U32 *db_seqp)

get_cv

Использует strlen для получения длины name, затем вызывает get_cvn_flags.

ПРИМЕЧАНИЕ: perl_ версия этой функции устарела.

CV*     get_cv(const char* name, I32 flags)

get_cvn_flags

Возвращает CV указанной Perl-подпрограммы. flags передаются gv_fetchpvn_flags. Если GV_ADD установлено, и Perl-подпрограмма не существует, она будет объявлена (что эквивалентно sub name;). Если GV_ADD не установлено и подпрограмма не существует, возвращается NULL.

ПРИМЕЧАНИЕ: perl_ версия этой функции устарела.

CV*     get_cvn_flags(const char* name, STRLEN len,
                      I32 flags)

`xsubpp` переменные и внутренние функции

ax

Переменная, устанавливаемая xsubpp для указания смещения базового адреса стека, используемого макросами ST, XSprePUSH и XSRETURN. Макрос dMARK должен быть вызван перед установкой переменной MARK.

I32     ax

CLASS

Переменная, устанавливаемая xsubpp для указания имени класса для конструктора C++ XS. Это всегда char*. См. "THIS".

char*   CLASS

dAX

Устанавливает переменную ax. Обычно это обрабатывается автоматически xsubpp путем вызова dXSARGS.

dAX;

dAXMARK

Устанавливает переменную ax и переменную метки стека mark. Обычно это обрабатывается автоматически xsubpp путем вызова dXSARGS.

dAXMARK;

dITEMS

Устанавливает переменную items. Обычно это обрабатывается автоматически xsubpp путем вызова dXSARGS.

dITEMS;

dUNDERBAR

Устанавливает любые переменные, необходимые макросу UNDERBAR. Раньше использовался для определения padoff_du, но сейчас это пустая операция. Однако настоятельно рекомендуется использовать его для обеспечения совместимости в прошлом и будущем.

dUNDERBAR;

dXSARGS

Устанавливает указатели на стек и метки для XSUB, вызывая dSP и dMARK. Устанавливает переменные ax и items путем вызова dAX и dITEMS. Обычно это обрабатывается автоматически xsubpp.

dXSARGS;

dXSI32

Устанавливает переменную ix для XSUB с псевдонимами. Обычно это обрабатывается автоматически xsubpp.

dXSI32;

items

Переменная, устанавливаемая xsubpp для указания количества элементов в стеке. См. "Переменные списки параметров" в perlxs.

I32     items

ix

Переменная, устанавливаемая xsubpp для указания используемого псевдонима XSUB для вызова. См. "Ключевое слово ALIAS:" в perlxs.

I32     ix

RETVAL

Переменная, устанавливаемая xsubpp для хранения возвращаемого значения XSUB. Это всегда правильный тип для XSUB. См. "Переменная RETVAL" в perlxs.

(whatever)      RETVAL

ST

Используется для доступа к элементам стека XSUB.

SV*     ST(int ix)

THIS

Переменная, устанавливаемая xsubpp для обозначения объекта в C++ XSUB. Это всегда правильный тип для C++ объекта. См. "CLASS" и "Использование XS с C++" в perlxs.

(whatever)      THIS

UNDERBAR

SV*, соответствующий переменной $_. Работает даже если существует лексическая переменная $_ в области видимости.

XS

Макрос для объявления XSUB и его списка C-параметров. Обрабатывается xsubpp. Это то же самое, что использование более явного макроса XS_EXTERNAL.

XS_EXTERNAL

Макрос для явного объявления XSUB и его списка C-параметров, экспортируя символы.

XS_INTERNAL

Макрос для объявления XSUB и его списка C-параметров без экспорта символов. Обрабатывается xsubpp и, как правило, предпочтительнее, чем ненужное экспортирование символов XSUB.

Средства отладки

dump_all

Выводит весь optree текущей программы, начиная с PL_main_root и заканчивая STDERR. Также выводит optree для всех видимых подпрограмм в PL_defstash.

void    dump_all()

dump_packsubs

Выводит optree для всех видимых подпрограмм в stash.

void    dump_packsubs(const HV* stash)

op_class

Определяет тип структуры, к которому был выделен оператор. Возвращает один из перечислений OPclass, например, OPclass_LISTOP.

OPclass op_class(const OP *o)

op_dump

Выводит optree, начиная с оператора OP o и заканчивая STDERR.

void    op_dump(const OP *o)

sv_dump

Выводит содержимое SV в файл STDERR.

Пример вывода см. в Devel::Peek.

void    sv_dump(SV* sv)

Функции отображения и вывода

pv_display

Аналогично

pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);

за исключением того, что дополнительный символ "\0" будет добавлен к строке, когда len > cur и pv[cur] равно "\0".

Обратите внимание, что конечная строка может быть на 7 символов длиннее, чем pvlim.

char*   pv_display(SV *dsv, const char *pv, STRLEN cur,
                   STRLEN len, STRLEN pvlim)

pv_escape

Экранирует не более первых count символов pv и помещает результаты в dsv, так что размер экранированной строки не будет превышать max символов и не будет содержать неполных последовательностей экранирования. Количество экранированных байтов будет возвращено в параметре STRLEN *escaped , если он не равен null. Когда параметр dsv равен null, экранирования не происходит, но вычисляется количество байтов, которые были бы экранированы, если бы он не был null.

Если флаги содержат PERL_PV_ESCAPE_QUOTE, то любые двойные кавычки в строке также будут экранированы.

Обычно SV очищается перед подготовкой экранированной строки, но когда PERL_PV_ESCAPE_NOCLEAR установлен, это не произойдет.

Если PERL_PV_ESCAPE_UNI установлен, входная строка обрабатывается как UTF-8; если PERL_PV_ESCAPE_UNI_DETECT установлен, входная строка сканируется с помощью is_utf8_string() для определения, является ли она UTF-8.

Если PERL_PV_ESCAPE_ALL установлен, все символы входной строки будут выведены с использованием экранирования в стиле \x01F1; в противном случае, если PERL_PV_ESCAPE_NONASCII установлен, только символы, не являющиеся ASCII, будут экранированы в этом стиле; в противном случае только символы с кодами выше 255 будут так экранированы; другие непропечатываемые символы будут использовать восьмеричное или общее экранирование, как \n. В противном случае, если PERL_PV_ESCAPE_NOBACKSLASH установлен, все символы ниже 255 будут обрабатываться как печатные и будут выводиться как литералы.

Если PERL_PV_ESCAPE_FIRSTCHAR установлен, то будет экранирован только первый символ строки, независимо от max. Если выход должен быть в шестнадцатеричном формате, он будет возвращен как обычная шестнадцатеричная последовательность. Таким образом, выход будет либо одиночным символом, восьмеричной последовательностью экранирования, специальной последовательностью экранирования, как \n, или шестнадцатеричным значением.

Если PERL_PV_ESCAPE_RE установлен, символ экранирования будет "%", а не "\\". Это связано с тем, что выражения часто содержат последовательности с обратной косой чертой, тогда как "%" не является распространённым символом в шаблонах.

Возвращает указатель на экранированный текст, хранящийся в dsv.

char*   pv_escape(SV *dsv, char const * const str,
                  const STRLEN count, const STRLEN max,
                  STRLEN * const escaped,
                  const U32 flags)

pv_pretty

Преобразует строку в удобочитаемый формат, обрабатывая экранирование с помощью pv_escape() и поддерживая кавычки и многоточие.

Если флаг PERL_PV_PRETTY_QUOTE установлен, результат будет заключён в двойные кавычки, а любые двойные кавычки в строке будут экранированы. В противном случае, если флаг PERL_PV_PRETTY_LTGT установлен, результат будет заключён в угловые скобки.

Если флаг PERL_PV_PRETTY_ELLIPSES установлен и не все символы в строке были выведены, то к строке будет добавлен многоточие .... Обратите внимание, что это происходит ПОСЛЕ того, как строка была заключена в кавычки.

Если start_color не равен null, то он будет вставлен после открывающей кавычки (если она есть), но перед экранированным текстом. Если end_color не равен null, то он будет вставлен после экранированного текста, но перед кавычками или многоточием.

Возвращает указатель на отформатированный текст, хранящийся в dsv.

char*   pv_pretty(SV *dsv, char const * const str,
                  const STRLEN count, const STRLEN max,
                  char const * const start_color,
                  char const * const end_color,
                  const U32 flags)

Функции встраивания

cv_clone

Клонировать CV, создавая лексическое замыкание. proto предоставляет прототип функции: её код, структуру стека и другие атрибуты. Прототип комбинируется с захватом внешних лексических переменных, на которые ссылается код, взятых из текущего экземпляра непосредственно окружающего кода.

CV *    cv_clone(CV *proto)

cv_name

Возвращает SV, содержащий имя CV, в основном для использования в сообщениях об ошибках. CV может фактически быть GV, в этом случае возвращаемый SV содержит имя GV. Всё, что не GV или CV, рассматривается как строка, уже содержащая имя подпрограммы, но это может измениться в будущем.

В качестве второго аргумента может быть передан SV. В этом случае имя будет присвоено ему, и оно будет возвращено. В противном случае возвращаемый SV будет новым смертным.

Если flags имеет установленный бит CV_NAME_NOTQUAL, то имя пакета не будет включено. Если первый аргумент не является ни CV, ни GV, этот флаг игнорируется (может измениться).

SV *    cv_name(CV *cv, SV *sv, U32 flags)

cv_undef

Очистить все активные компоненты CV. Это может произойти либо в результате явного undef &foo, либо при обнулении счётчика ссылок. В первом случае мы сохраняем указатель CvOUTSIDE, чтобы любые анонимные дочерние элементы могли следовать всей цепочке лексического охвата.

void    cv_undef(CV* cv)

find_rundefsv

Возвращает глобальную переменную $_.

SV *    find_rundefsv()

find_rundefsvoffset

УСТЕРЕЖДЁН! Планируется удалить эту функцию из будущих релизов Perl. Не используйте её в новом коде; удалите её из существующего кода.

До тех пор, пока не было удалено лексическое $_-функциональность, эта функция находила положение лексической $_ в стеке текущей функции и возвращала смещение в текущем стеке или NOT_IN_PAD.

Теперь она всегда возвращает NOT_IN_PAD.

ПРИМЕЧАНИЕ: perl_ версия этой функции устарела.

PADOFFSET find_rundefsvoffset()

intro_my

«Представить» my переменные, сделав их видимыми. Это вызывается во время парсинга в конце каждого оператора, чтобы сделать лексические переменные видимыми последующим операторам.

U32     intro_my()

load_module

Загружает модуль, имя которого указано в строковой части name. Обратите внимание, что должно быть указано фактическое имя модуля, а не его имя файла. Например, «Foo::Bar» вместо «Foo/Bar.pm». ver, если указано и не NULL, предоставляет семантику версий, аналогичную use Foo::Bar VERSION. Дополнительные аргументы можно использовать для задания аргументов методу import() модуля, аналогично use Foo::Bar VERSION LIST; их точное обращение зависит от флагов. Аргумент flags — это битовая OR-группа любых из PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, или PERL_LOADMOD_IMPORT_OPS (или 0 для отсутствия флагов).

Если PERL_LOADMOD_NOIMPORT установлено, модуль загружается так, как если бы список импорта был пустым, как в use Foo::Bar (); это единственный случай, когда можно опустить дополнительные хвостовые аргументы. В противном случае, если PERL_LOADMOD_IMPORT_OPS установлено, хвостовые аргументы должны состоять ровно из одного OP*, содержащего дерево op, которое генерирует соответствующие аргументы импорта. В противном случае, хвостовые аргументы должны быть значениями SV*, которые будут использоваться как аргументы импорта; и список должен заканчиваться (SV*) NULL. Если ни PERL_LOADMOD_NOIMPORT, ни PERL_LOADMOD_IMPORT_OPS не установлены, указатель на хвостовые NULL необходим, даже если аргументы импорта не требуются. Счётчик ссылок для каждого указанного аргумента SV* уменьшается. Кроме того, аргумент name модифицируется.

Если PERL_LOADMOD_DENY установлено, модуль загружается так, как если бы был no, а не use.

void    load_module(U32 flags, SV* name, SV* ver, ...)

newPADNAMELIST

Создаёт новый список имён стека. max — это максимальный индекс, для которого выделяется память.

PADNAMELIST * newPADNAMELIST(size_t max)

newPADNAMEouter

Строит и возвращает новое имя стека. Используйте эту функцию только для имён, которые ссылаются на внешние лексические переменные. (См. также "newPADNAMEpvn".) outer — это имя внешнего стека, который этот стек дублирует. Возвращаемое имя стека имеет уже установленный флаг PADNAMEt_OUTER.

PADNAME * newPADNAMEouter(PADNAME *outer)

newPADNAMEpvn

Строит и возвращает новое имя стека. s должна быть строкой UTF-8. Не используйте эту функцию для имён стеков, которые указывают на внешние лексические переменные. См. "newPADNAMEouter".

PADNAME * newPADNAMEpvn(const char *s, STRLEN len)

nothreadhook

«Заглушка», которая предоставляет обработку потоков для perl_destruct, когда потоков нет.

int     nothreadhook()

pad_add_anon

Выделяет место в текущем стеке (через "pad_alloc") для анонимной функции, которая лексически вложена в текущую функцию. Функция func связывается со стеком, а её связь CvOUTSIDE с внешним охватом ослабляется, чтобы избежать цикла ссылок.

Одна ссылка отнимается, поэтому вам может потребоваться сделать SvREFCNT_inc(func).

optype должен быть кодом операции, указывающим на тип операции, которую должна поддерживать запись в стеке. Это не влияет на операционную семантику, но используется для отладки.

PADOFFSET pad_add_anon(CV *func, I32 optype)

pad_add_name_pv

Точно так же, как "pad_add_name_pvn", но принимает завершающую нулём строку вместо пары строка/длина.

PADOFFSET pad_add_name_pv(const char *name, U32 flags,
                          HV *typestash, HV *ourstash)

pad_add_name_pvn

Выделяет место в текущем стеке для именованной лексической переменной. Сохраняет имя и другие метаданные в части имени стека и готовится управлять лексическим охватом переменной. Возвращает смещение выделенного слота стека.

namepv/namelen определяют имя переменной, включая ведущий сигил. Если typestash не равно нулю, имя предназначено для типизированной лексической переменной, и это идентифицирует тип. Если ourstash не равно нулю, это лексическая ссылка на переменную пакета, и это идентифицирует пакет. Следующие флаги можно объединять побитовым OR:

padadd_OUR          redundantly specifies if it's a package var
padadd_STATE        variable will retain value persistently
padadd_NO_DUP_CHECK skip check for lexical shadowing

       PADOFFSET pad_add_name_pvn(const char *namepv,
                                  STRLEN namelen, U32 flags,
                                  HV *typestash, HV *ourstash)

pad_add_name_sv

Точно так же, как "pad_add_name_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

PADOFFSET pad_add_name_sv(SV *name, U32 flags,
                          HV *typestash, HV *ourstash)

pad_alloc

Выделяет место в текущем стеке, возвращая смещение выделенного слота стека. Имя слоту стека первоначально не присвоено. tmptype — это набор флагов, указывающих на тип записи в стеке, который будет установлен в значении SV для выделенного слота стека:

SVs_PADMY    named lexical variable ("my", "our", "state")
SVs_PADTMP   unnamed temporary store
SVf_READONLY constant shared between recursion levels

SVf_READONLY поддерживается здесь только начиная с perl 5.20. Чтобы работать и с более ранними версиями, используйте SVf_READONLY|SVs_PADTMP. SVf_READONLY не делает SV в слоте стека неизменяемым, а просто сообщает pad_alloc, что будет сделать его неизменяемым (вызывающий код), или по крайней мере следует обращаться с ним так.

PADOFFSET pad_alloc(I32 optype, U32 tmptype)

pad_findmy_pv

Точно так же, как "pad_findmy_pvn", но принимает завершающую нулём строку вместо пары строка/длина.

PADOFFSET pad_findmy_pv(const char *name, U32 flags)

pad_findmy_pvn

На основании имени лексической переменной найти её положение в текущем стеке. namepv/namelen определяют имя переменной, включая ведущий сигил. flags зарезервировано и должно быть равно нулю. Если переменной нет в текущем стеке, но она появляется в стеке любого лексически вложенного уровня, то для неё добавляется псевдозапись в текущий стек. Возвращает смещение в текущем стеке или NOT_IN_PAD, если такая лексическая переменная не входит в область видимости.

PADOFFSET pad_findmy_pvn(const char *namepv,
                         STRLEN namelen, U32 flags)

pad_findmy_sv

Точно так же, как "pad_findmy_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

PADOFFSET pad_findmy_sv(SV *name, U32 flags)

padnamelist_fetch

Извлекает имя стека по заданному индексу.

PADNAME * padnamelist_fetch(PADNAMELIST *pnl,
                            SSize_t key)

padnamelist_store

Сохраняет имя стека (которое может быть null) по заданному индексу, освобождая любое существующее имя стека в этом слоте.

PADNAME ** padnamelist_store(PADNAMELIST *pnl,
                             SSize_t key, PADNAME *val)

pad_setsv

Установить значение по смещению po в текущем (компилируемом или выполняемом) стеке. Используйте макрос PAD_SETSV() вместо прямого вызова этой функции.

void    pad_setsv(PADOFFSET po, SV *sv)

pad_sv

Получить значение по смещению po в текущем (компилируемом или выполняемом) стеке. Используйте макрос PAD_SV вместо прямого вызова этой функции.

SV *    pad_sv(PADOFFSET po)

pad_tidy

Привести в порядок стек в конце компиляции кода, к которому он принадлежит. Выполняемые здесь задачи: удалить большую часть содержимого из стеков анонимных подпрограмм; присвоить ему @_; отметить временные переменные как таковые. type указывает тип подпрограммы:

padtidy_SUB        ordinary subroutine
padtidy_SUBCLONE   prototype for lexical closure
padtidy_FORMAT     format

    void    pad_tidy(padtidy_type type)

perl_alloc

Выделяет новый интерпретатор Perl. См. perlembed.

PerlInterpreter* perl_alloc()

perl_construct

Инициализирует новый интерпретатор Perl. См. perlembed.

void    perl_construct(PerlInterpreter *my_perl)

perl_destruct

END_OF_DOCUMENT_MARKER

Закрывает интерпретатор Perl. См. perlembed для учебного пособия.

my_perl указывает на интерпретатор Perl. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct". Он может быть инициализирован с помощью "perl_parse" и может быть использован с помощью "perl_run" и другими средствами. Данная функция должна вызываться для любого интерпретатора Perl, созданного с помощью "perl_construct", даже если последующие операции над ним завершились неудачей, например, если "perl_parse" вернуло ненулевое значение.

Если PL_exit_flags интерпретатора имеет PERL_EXIT_DESTRUCT_END флаг установленным, то эта функция выполнит код в END блоках перед выполнением остальной части уничтожения. Если требуется использовать интерпретатор между "perl_parse" и "perl_destruct" помимо простого вызова "perl_run", то этот флаг следует установить на ранней стадии. Это важно, если "perl_run" не будет вызываться или если что-то ещё будет выполнено помимо вызова "perl_run".

Возвращает значение, подходящее для передачи в функцию C-библиотеки exit (или для возврата из main), которое служит кодом завершения, указывающим на характер завершения работы интерпретатора. Это учитывает любые ошибки "perl_parse" и любое преждевременное завершение "perl_run". Код завершения имеет тип, требуемый операционной системой хоста, поэтому из-за различных соглашений о кодах завершения он не является переносимым, если интерпретировать конкретные числовые значения как имеющие конкретный смысл.

int     perl_destruct(PerlInterpreter *my_perl)

perl_free

Освобождает интерпретатор Perl. См. perlembed.

void    perl_free(PerlInterpreter *my_perl)

perl_parse

Указывает интерпретатору Perl на разбор Perl-скрипта. Это выполняет большую часть начальной инициализации интерпретатора Perl. См. perlembed для учебного пособия.

my_perl указывает на интерпретатор Perl, который должен разобрать скрипт. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct". xsinit указывает на функцию обратного вызова, которая будет вызвана для настройки возможности загрузки XS-расширений этим интерпретатором Perl, или может быть нулевой, чтобы не выполнять такую настройку.

argc и main передают набор аргументов командной строки интерпретатору Perl, как обычно передаются в функцию main программы на C. argv[argc] должно быть нулевым. Эти аргументы указывают на скрипт для разбора, либо указанием имени файла скрипта, либо предоставлением скрипта в -e опции. Если $0 будет записано в интерпретатор Perl, то строки аргументов должны быть в памяти с возможностью записи, а не просто строковыми константами.

env указывает набор переменных окружения, которые будут использоваться этим интерпретатором Perl. Если не нулевой, он должен указывать на нуль-терминированный массив строк окружения. Если нулевой, интерпретатор Perl будет использовать окружение, предоставленное глобальной переменной environ.

Эта функция инициализирует интерпретатор, анализирует и компилирует скрипт, указанный в аргументах командной строки. Это включает выполнение кода в BEGIN, UNITCHECK, и CHECK блоках. Это не выполняет INIT блоки или основную программу.

Возвращает целое число, интерпретация которого немного сложна. Правильное использование возвращаемого значения — как логическое значение, указывающее, была ли ошибка при инициализации. Если возвращено ноль, это означает, что инициализация прошла успешно, и можно приступать к вызову "perl_run" и использовать его дальше. Если возвращено ненулевое значение, это указывает на какую-то проблему, из-за которой интерпретатор хочет завершиться. При такой ошибке интерпретатор не следует просто оставлять; вызывающая сторона должна корректно завершить работу интерпретатора с помощью "perl_destruct" и освободить его с помощью "perl_free".

По историческим причинам, ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию C-библиотеки exit (или для возврата из main), служащим кодом завершения, указывающим на характер завершения инициализации. Однако это не переносимо из-за различных соглашений о кодах завершения. Историческая ошибка сохраняется: если встроенная функция Perl exit вызывается во время выполнения этой функции с типом завершения, означающим нулевой код завершения согласно соглашениям операционной системы хоста, то эта функция возвращает ноль, а не ненулевое значение. Эта ошибка [perl #2754] приводит к вызову perl_run (и, следовательно, выполнению INIT блоков и основной программы) несмотря на вызов exit. Она сохранена, потому что популярный модуль-установщик зависит от неё и требует времени для исправления. Эта проблема [perl #132577], а исходная ошибка должна быть исправлена в Perl 5.30.

int     perl_parse(PerlInterpreter *my_perl,
                   XSINIT_t xsinit, int argc,
                   char **argv, char **env)

perl_run

Указывает интерпретатору Perl на выполнение его основной программы. См. perlembed для учебного пособия.

my_perl указывает на интерпретатор Perl. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct" и инициализирован с помощью "perl_parse". Эта функция не должна вызываться, если "perl_parse" вернула ненулевое значение, указывающее на ошибку инициализации или компиляции.

Эта функция выполняет код в INIT блоках, а затем выполняет основную программу. Выполняемый код устанавливается предыдущим вызовом "perl_parse". Если у интерпретатора PL_exit_flags слово не имеет PERL_EXIT_DESTRUCT_END флага, то эта функция также выполнит код в END блоках. Если необходимо продолжить использование интерпретатора после вызова этой функции, то END блоки следует отложить до времени "perl_destruct", установив этот флаг.

Возвращает целое число, интерпретация которого немного сложна. Правильное использование возвращаемого значения — как логическое значение, указывающее, завершилась ли программа нелокально. Если возвращено ноль, это означает, что программа выполнилась до конца, и можно продолжить использование интерпретатора (при условии, что PERL_EXIT_DESTRUCT_END флаг был установлен, как описано выше). Если возвращено ненулевое значение, это означает, что интерпретатор хочет завершиться раньше. Интерпретатор не следует просто оставлять из-за этого желания завершиться; вызывающая сторона должна корректно завершить работу интерпретатора с помощью "perl_destruct" и освободить его с помощью "perl_free".

По историческим причинам, ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию C-библиотеки exit (или для возврата из main), служащим кодом завершения, указывающим на характер завершения программы. Однако это не переносимо из-за различных соглашений о кодах завершения. Пытается вернуть код завершения, требуемый операционной системой хоста, но так как он ограничен ненулевым значением, не всегда возможно указать каждый тип завершения. Это надежно только в Unix, где нулевой код завершения можно дополнить установленным битом, который будет проигнорирован. В любом случае, эта функция не является правильным местом для получения кода завершения: его следует получить из "perl_destruct".

int     perl_run(PerlInterpreter *my_perl)

require_pv

Указывает Perl на require файл, имя которого указано в строковом аргументе. Аналогично Perl-коду eval "require '$file'". Даже реализовано таким образом; используйте load_module вместо этого.

ПРИМЕЧАНИЕ: Perl-форма этой функции устарела.

void    require_pv(const char* pv)

Обработка исключений (простые) Макросы

dXCPT

Настройка необходимых локальных переменных для обработки исключений. См. "Обработка исключений" в perlguts.

dXCPT;

XCPT_CATCH

Вводит блок catch. См. "Обработка исключений" в perlguts.

XCPT_RETHROW

Перебрасывает ранее перехваченное исключение. См. "Обработка исключений" в perlguts.

XCPT_RETHROW;

XCPT_TRY_END

Завершает блок try. См. "Обработка исключений" в perlguts.

XCPT_TRY_START

Начинает блок try. См. "Обработка исключений" в perlguts.

Функции в файле pp_sort.c

sortsv_flags

Сортировка массива указателей SV на месте с заданной функцией сравнения, с различными флагами SORTf_*.

void    sortsv_flags(SV** array, size_t num_elts,
                     SVCOMPARE_t cmp, U32 flags)

Функции в файле scope.c

save_gp

Сохраняет текущий GP gv в стеке сохранения для восстановления при выходе из области видимости.

Если empty истинно, замените GP новым GP.

Если empty ложно, пометьте gv с GVf_INTRO, чтобы следующее присваивание ссылки было локализовано, что используется в local *foo = $someref; .

void    save_gp(GV* gv, I32 empty)

Функции в файле vutil.c

new_version

Возвращает новый объект версии на основе переданного SV:

SV *sv = new_version(SV *ver);

Не изменяет переданный ver SV. См. "upg_version", если вы хотите обновить SV.

SV*     new_version(SV *ver)

prescan_version

Проверяет, может ли заданная строка быть обработана как объект версии, но фактически не выполняет обработку. Может использовать строгие или слабые правила проверки. По желанию может установить несколько переменных подсказок, чтобы сэкономить время коду обработки при разборе токенов.

const char* prescan_version(const char *s, bool strict,
                            const char** errstr,
                            bool *sqv,
                            int *ssaw_decimal,
                            int *swidth, bool *salpha)

scan_version

Возвращает указатель на следующий символ после обработанной строки версии, а также обновляет переданный SV до RV.

Функция должна вызываться с уже существующим SV, например

sv = newSV(0);
s = scan_version(s, SV *sv, bool qv);

Выполняет некоторую предварительную обработку строки, чтобы убедиться, что она обладает правильными характеристиками версии. Помечает объект, если он содержит символ подчёркивания (который указывает, что это альфа-версия). Логическая переменная qv указывает, что версия должна интерпретироваться как имеющая несколько десятичных знаков, даже если это не так.

const char* scan_version(const char *s, SV *rv, bool qv)

upg_version

Встроенное обновление предоставленного SV до объекта версии.

SV *sv = upg_version(SV *sv, bool qv);

Возвращает указатель на обновлённый SV. Установите логическую переменную qv, если вы хотите, чтобы этот SV интерпретировался как "расширенная" версия.

SV*     upg_version(SV *ver, bool qv)

vcmp

Функция cmp, учитывающая объекты версии. Оба операнда должны быть предварительно преобразованы в объекты версии.

int     vcmp(SV *lhv, SV *rhv)

vnormal

Принимает объект версии и возвращает нормализованное строковое представление. Вызов:

sv = vnormal(rv);

ПРИМЕЧАНИЕ: вы можете передать либо сам объект, либо SV, содержащийся в RV.

Возвращаемое SV имеет счетчик ссылок 1.

SV*     vnormal(SV *vs)

vnumify

Принимает объект версии и возвращает нормализованное представление с плавающей точкой. Вызов:

sv = vnumify(rv);

ПРИМЕЧАНИЕ: вы можете передать либо сам объект, либо SV, содержащийся в RV.

Возвращаемое SV имеет счетчик ссылок 1.

SV*     vnumify(SV *vs)

vstringify

Для сохранения максимальной совместимости с более ранними версиями Perl, эта функция вернёт либо представление с плавающей точкой, либо представление с несколькими точками, в зависимости от того, содержала ли исходная версия 1 или более точек соответственно.

Возвращаемое SV имеет счетчик ссылок 1.

SV*     vstringify(SV *vs)

vverify

Проверяет, содержит ли SV корректную внутреннюю структуру для объекта версии. Может быть передан либо сам объект версии (RV), либо сам хеш (HV). Если структура корректна, возвращает HV. Если структура некорректна, возвращает NULL.

SV *hv = vverify(sv);

Обратите внимание, что она проверяет только минимальную структуру (чтобы не запутаться с производными классами, которые могут содержать дополнительные записи хеша):

SV является HV или ссылкой на HV
Хеш содержит ключ "version"
Ключ "version" содержит ссылку на AV в качестве значения

SV*     vverify(SV *vs)

"Gimme" Значения

G_ARRAY

Используется для обозначения контекста списка. См. "GIMME_V", "GIMME" и perlcall.

G_DISCARD

Указывает, что аргументы, возвращаемые из обратного вызова, должны быть отброшены. См. perlcall.

G_EVAL

Используется для принудительного создания оболочки Perl eval вокруг обратного вызова. См. perlcall.

GIMME

Обратно совместимая версия GIMME_V, которая может возвращать только G_SCALAR или G_ARRAY; в контексте void она возвращает G_SCALAR. Устарело. Используйте GIMME_V вместо этого.

U32     GIMME

GIMME_V

Аналог Perl's wantarray для XSUB-разработчиков. Возвращает G_VOID, G_SCALAR или G_ARRAY для контекста void, скалярного или списка соответственно. См. perlcall для примера использования.

U32     GIMME_V

G_NOARGS

Указывает, что обратный вызов не получает аргументы. См. perlcall.

G_SCALAR

Используется для обозначения скалярного контекста. См. "GIMME_V", "GIMME", и perlcall.

G_VOID

Используется для обозначения контекста void. См. "GIMME_V" и perlcall.

Глобальные переменные

Эти переменные глобальны для всего процесса. Они доступны для всех интерпретаторов и потоков в процессе. Любые не документированные здесь переменные могут быть изменены или удалены без предварительного уведомления, поэтому не используйте их! Если вы чувствуете, что действительно нужно использовать недокументированную переменную, сначала отправьте письмо на perl5-porters@perl.org. Возможно, кто-то там подскажет способ достижения вашей цели без использования внутренней переменной. Но если нет, вам необходимо получить разрешение на документирование и затем использование переменной.

PL_check

Массив, индексированный по коду операции, функций, которые будут вызываться для фазы "проверки" построения optree во время компиляции кода Perl. Для большинства (но не всех) типов операторов, после того как оператор был первоначально построен и заполнен дочерними операторами, он будет отфильтрован через функцию проверки, ссылающуюся на соответствующий элемент этого массива. Новый оператор передаётся в качестве единственного аргумента функции проверки, а функция проверки возвращает завершённый оператор. Функция проверки может (как следует из названия) проверить оператор на валидность и сообщить об ошибках. Она также может инициализировать или изменить части операторов или провести более радикальную операцию, такую как добавление или удаление дочерних операторов, или даже отбросить оператор и вернуть другой оператор взамен.

Этот массив указателей на функции является удобным местом для подключения к процессу компиляции. Модуль XS может поместить свою собственную пользовательскую функцию проверки вместо любой из стандартных, чтобы повлиять на компиляцию определённого типа оператора. Однако пользовательская функция проверки никогда не должна полностью заменять стандартную функцию проверки (или даже пользовательскую функцию проверки из другого модуля). Модуль, изменяющий проверку, должен вместо этого **обернуть** существующую функцию проверки. Пользовательская функция проверки должна быть избирательной в отношении того, когда применять своё пользовательское поведение. В обычном случае, когда она решает не делать ничего особенного с оператором, она должна вызвать предопределённую функцию оператора.

Функции проверки связаны в цепочку, в которой базовая функция проверки ядра находится в конце.

Для обеспечения безопасности потоков модули не должны напрямую записывать в этот массив. Вместо этого используйте функцию "wrap_op_checker".

PL_keyword_plugin

Указатель на функцию, используемую для обработки расширенных ключевых слов. Функция должна быть объявлена как

int keyword_plugin_function(pTHX_
        char *keyword_ptr, STRLEN keyword_len,
        OP **op_ptr)

Функция вызывается из разборщика токенов всякий раз, когда обнаруживается возможный ключевой элемент. keyword_ptr указывает на слово в буфере ввода разборчика, а keyword_len задаёт его длину; оно не завершается нулём. От функции ожидается, что она проверит слово и, возможно, другое состояние, такое как %^H, чтобы определить, хочет ли она обрабатывать его как расширенное ключевое слово. Если нет, функция должна вернуть KEYWORD_PLUGIN_DECLINE, и нормальный процесс разборчика продолжится.

Если функция хочет обработать ключевой элемент, она сначала должна обработать всё, что следует за ключевым элементом, которое является частью синтаксиса, введённого ключевым элементом. См. "Интерфейс разборщика токенов" для получения подробностей.

Когда ключевой элемент обрабатывается, функция плагина должна построить дерево структур OP, представляющих код, который был разобран. Корень дерева должен быть сохранён в *op_ptr. Затем функция возвращает константу, указывающую синтаксическую роль конструкции, которую она обработала: KEYWORD_PLUGIN_STMT — если это полное утверждение, или KEYWORD_PLUGIN_EXPR — если это выражение. Обратите внимание, что конструкция оператора не может использоваться внутри выражения (за исключением do BLOCK и аналогичных), а выражение не является полным оператором (требуется хотя бы завершающая точка с запятой).

При обработке ключевого слова функция плагина может также иметь побочные эффекты (во время компиляции). Она может изменять %^H, определять функции и т. д. Обычно, если побочные эффекты являются основной целью обработчика, он не хочет генерировать какие-либо операторы для включения в обычную компиляцию. В этом случае он всё ещё должен предоставить дерево операторов, но достаточно сгенерировать одиночный нулевой оператор.

Вот как функция *PL_keyword_plugin должна вести себя в целом. Однако обычно не следует полностью заменять существующую функцию обработчика. Вместо этого возьмите копию PL_keyword_plugin перед назначением собственной функции-указателя. Ваша функция-обработчик должна искать ключевые элементы, которые её интересуют, и обрабатывать их. В тех случаях, когда она не заинтересована, она должна вызвать сохранённую функцию плагина, передав полученные аргументы. Таким образом, PL_keyword_plugin фактически указывает на цепочку функций-обработчиков, все из которых имеют возможность обрабатывать ключевые элементы, и только последняя функция в цепочке (встроенная в ядро Perl) обычно вернёт KEYWORD_PLUGIN_DECLINE.

Для обеспечения безопасности потоков модули не должны напрямую изменять эту переменную. Вместо этого используйте функцию "wrap_keyword_plugin".

Функции GV

GV — это структура, которая соответствует перловскому типуглобу, например *foo. Это структура, которая содержит указатель на скаляр, массив, хеш и т. д., соответствующие $foo, @foo, %foo.

GV обычно встречаются как значения в хранилищах (хешах таблиц символов), где Perl хранит свои глобальные переменные.

GvAV

Возвращает AV из GV.

AV*     GvAV(GV* gv)

gv_const_sv

Если gv является typeglob, запись подпрограммы которого является константной подпрограммой, подходящей для инлайнинга, или gv — это ссылка-заполнитель, которая была бы преобразована в такой typeglob, то возвращает значение, возвращаемое подпрограммой. В противном случае возвращает NULL.

SV*     gv_const_sv(GV* gv)

GvCV

Возвращает CV из GV.

CV*     GvCV(GV* gv)

gv_fetchmeth

Аналогично "gv_fetchmeth_pvn", но без параметра flags.

GV*     gv_fetchmeth(HV* stash, const char* name,
                     STRLEN len, I32 level)

gv_fetchmethod_autoload

Возвращает glob, содержащий подпрограмму для вызова метода на stash. На самом деле, при наличии автозагрузки, это может быть glob для "AUTOLOAD". В этом случае соответствующая переменная $AUTOLOAD уже настроена.

Третий параметр gv_fetchmethod_autoload определяет, будет ли выполняться поиск AUTOLOAD, если указанный метод отсутствует: ненулевое значение означает "да", искать AUTOLOAD; нулевое значение означает "нет", не искать AUTOLOAD. Вызов gv_fetchmethod эквивалентен вызову gv_fetchmethod_autoload с ненулевым параметром autoload.

Эти функции предоставляют "SUPER" в качестве префикса имени метода. Обратите внимание, что если вы хотите сохранить возвращённый glob надолго, вам нужно проверить, является ли он "AUTOLOAD", так как впоследствии вызов может загрузить другую подпрограмму из-за изменения значения $AUTOLOAD. Используйте созданный в качестве побочного эффекта glob для этого.

Эти функции имеют те же побочные эффекты, что и gv_fetchmeth с level==0. Предупреждение о передаче GV, возвращенного gv_fetchmeth в call_sv, также относится к этим функциям.

GV*     gv_fetchmethod_autoload(HV* stash,
                                const char* name,
                                I32 autoload)

gv_fetchmeth_autoload

Это старая форма "gv_fetchmeth_pvn_autoload", не имеющая параметра flags.

GV*     gv_fetchmeth_autoload(HV* stash,
                              const char* name,
                              STRLEN len, I32 level)

gv_fetchmeth_pv

Точно так же, как "gv_fetchmeth_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

GV*     gv_fetchmeth_pv(HV* stash, const char* name,
                        I32 level, U32 flags)

gv_fetchmeth_pvn

Возвращает glob с заданным name и определенной подпрограммой или NULL. Этот glob находится в заданном stash, или в хранилищах, доступных через @ISA и UNIVERSAL::.

Аргумент level должен быть либо 0, либо -1. Если level==0, в качестве побочного эффекта создает glob с заданным name в заданном stash, который в случае успеха содержит псевдоним подпрограммы, и настраивает информацию о кэшировании для этого glob.

Единственно значимые значения для flags — GV_SUPER и SVf_UTF8.

GV_SUPER указывает, что мы хотим найти метод в суперклассах stash.

GV, возвращенный из gv_fetchmeth, может быть записью кэша метода, не видимой для кода Perl. Поэтому при вызове call_sv, вы не должны использовать GV напрямую; вместо этого вы должны использовать CV метода, который можно получить из GV с помощью макроса GvCV.

GV*     gv_fetchmeth_pvn(HV* stash, const char* name,
                         STRLEN len, I32 level,
                         U32 flags)

gv_fetchmeth_pvn_autoload

То же, что gv_fetchmeth_pvn(), но также ищет подпрограммы с автозагрузкой. Возвращает glob для подпрограммы.

Для подпрограммы с автозагрузкой без GV, создаст GV даже если level < 0. Для подпрограммы с автозагрузкой без фрагмента, GvCV() результата может быть равно нулю.

В настоящее время единственное значимое значение для flags — SVf_UTF8.

GV*     gv_fetchmeth_pvn_autoload(HV* stash,
                                  const char* name,
                                  STRLEN len, I32 level,
                                  U32 flags)

gv_fetchmeth_pv_autoload

Точно так же, как "gv_fetchmeth_pvn_autoload", но принимает строку с нулевым завершением вместо пары строка/длина.

GV*     gv_fetchmeth_pv_autoload(HV* stash,
                                 const char* name,
                                 I32 level, U32 flags)

gv_fetchmeth_sv

Точно так же, как "gv_fetchmeth_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

GV*     gv_fetchmeth_sv(HV* stash, SV* namesv,
                        I32 level, U32 flags)

gv_fetchmeth_sv_autoload

Точно так же, как "gv_fetchmeth_pvn_autoload", но принимает строку имени в виде SV вместо пары строка/длина.

GV*     gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
                                 I32 level, U32 flags)

GvHV

Возвращает HV из GV.

HV*     GvHV(GV* gv)

gv_init

Старая форма gv_init_pvn(). Она не работает со строками UTF-8, так как не имеет параметра flags. Если параметр multi установлен, флаг GV_ADDMULTI будет передан в gv_init_pvn().

void    gv_init(GV* gv, HV* stash, const char* name,
                STRLEN len, int multi)

gv_init_pv

То же, что gv_init_pvn(), но принимает строку с нулевым завершением для имени вместо отдельных параметров char * и length.

void    gv_init_pv(GV* gv, HV* stash, const char* name,
                   U32 flags)

gv_init_pvn

Преобразует скаляр в typeglob. Это непереводимый typeglob; присваивание ссылки к нему присвоит значение одному из его слотов, вместо того чтобы перезаписать его, как это происходит с typeglob, созданными SvSetSV. Преобразование любого скаляра, который SvOK(), может привести к непредсказуемым результатам и предназначено для внутреннего использования Perl.

gv — скаляр, подлежащий преобразованию.

stash — родительский stash/пакет, если таковой имеется.

name и len — имя. Имя должно быть неквалифицированным; то есть оно не должно включать имя пакета. Если gv — элемент stash, ответственность за соответствие имени, переданного этой функции, имени элемента, возлагается на вызывающую сторону. Если они не совпадают, внутренняя книга учета Perl выйдет из строя.

flags может быть установлено в SVf_UTF8 если name — строка UTF-8, или результат SvUTF8(sv). Также может принимать флаг GV_ADDMULTI, что означает симулировать, что GV был виден ранее (т.е. подавить предупреждения "Использовано один раз").

void    gv_init_pvn(GV* gv, HV* stash, const char* name,
                    STRLEN len, U32 flags)

gv_init_sv

То же, что gv_init_pvn(), но принимает SV * для имени вместо отдельных параметров char * и length. flags в настоящее время не используется.

void    gv_init_sv(GV* gv, HV* stash, SV* namesv,
                   U32 flags)

gv_stashpv

Возвращает указатель на stash для указанного пакета. Использует strlen для определения длины name, затем вызывает gv_stashpvn().

HV*     gv_stashpv(const char* name, I32 flags)

gv_stashpvn

Возвращает указатель на stash для указанного пакета. Параметр namelen указывает длину name, в байтах. flags передается в gv_fetchpvn_flags(), поэтому, если установлено GV_ADD, пакет будет создан, если он еще не существует. Если пакет не существует, и flags равно 0 (или любое другое значение, не создающее пакеты), то возвращается NULL.

Флаги могут быть следующими:

GV_ADD
SVf_UTF8
GV_NOADD_NOINIT
GV_NOINIT
GV_NOEXPAND
GV_ADDMG

Наиболее важными из которых, вероятно, являются GV_ADD и SVf_UTF8.

Обратите внимание, использование gv_stashsv вместо gv_stashpvn по возможности, строго рекомендуется по соображениям производительности.

HV*     gv_stashpvn(const char* name, U32 namelen,
                    I32 flags)

gv_stashpvs

Как gv_stashpvn, но принимает литеральную строку вместо пары строка/длина.

HV*     gv_stashpvs("literal string" name, I32 create)

gv_stashsv

Возвращает указатель на stash для указанного пакета. См. "gv_stashpvn".

Обратите внимание, что этот интерфейс предпочтительнее gv_stashpvn по соображениям производительности.

HV*     gv_stashsv(SV* sv, I32 flags)

GvSV

Возвращает SV из GV.

SV*     GvSV(GV* gv)

setdefout

Устанавливает PL_defoutgv, стандартный дескриптор файла для вывода, в переданный typeglob. Так как PL_defoutgv "владеет" ссылкой на свой typeglob, счетчик ссылок переданного typeglob увеличивается на единицу, а счетчик ссылок typeglob, на который указывает PL_defoutgv, уменьшается на единицу.

void    setdefout(GV* gv)

Полезные значения

Nullav

Указатель Null AV.

(устарело - используйте (AV *)NULL вместо этого)

Nullch

Указатель на нулевой символ. (Больше недоступно, когда PERL_CORE определён).

Nullcv

Указатель Null CV.

(устарело - используйте (CV *)NULL вместо этого)

Nullhv

Указатель Null HV.

(устарело - используйте (HV *)NULL вместо этого)

Nullsv

Указатель Null SV. (Больше недоступно, когда PERL_CORE определён).

Функции манипуляции хэш-таблицами

Структура HV представляет собой хэш-таблицу Perl. Она состоит в основном из массива указателей, каждый из которых указывает на список элементов HE. Массив индексируется функцией хеширования ключа, поэтому каждый список представляет собой все элементы хеша с одинаковым значением хеширования. Каждый HE содержит указатель на фактическое значение плюс указатель на структуру HEK, которая содержит ключ и значение хеширования.

cop_fetch_label

Возвращает метку, присоединённую к cop. Указатель флагов может быть установлен на SVf_UTF8 или 0.

const char * cop_fetch_label(COP *const cop,
                             STRLEN *len, U32 *flags)

cop_store_label

Сохраняет метку в cop_hints_hash. Для метки UTF-8 необходимо установить флаги на SVf_UTF8.

void    cop_store_label(COP *const cop,
                        const char *label, STRLEN len,
                        U32 flags)

get_hv

Возвращает HV указанного Perl-хеша. flags передаются в gv_fetchpv. Если GV_ADD установлен, а Perl-переменная не существует, она будет создана. Если flags равно нулю, и переменная не существует, то возвращается NULL.

ПРИМЕЧАНИЕ: форма perl_ этой функции устарела.

HV*     get_hv(const char *name, I32 flags)

HEf_SVKEY

Этот флаг, используемый в слоте длины записей хеша и магических структур, указывает, что структура содержит указатель SV*, где ожидается указатель char*. (Для справки - не использовать).

HeHASH

Возвращает вычисленный хеш, хранящийся в записи хеша.

U32     HeHASH(HE* he)

HeKEY

Возвращает фактический указатель, хранящийся в слоте ключа записи хеша. Указатель может быть либо char*, либо SV*, в зависимости от значения HeKLEN(). Может быть присвоено значение. Макросы HePV() или HeSVKEY() обычно предпочтительнее для поиска значения ключа.

void*   HeKEY(HE* he)

HeKLEN

Если значение отрицательно, и это означает HEf_SVKEY, это указывает, что запись содержит SV* ключ. В противном случае хранит фактическую длину ключа. Может быть присвоено значение. Макрос HePV() обычно предпочтительнее для поиска длин ключей.

STRLEN  HeKLEN(HE* he)

HePV

Возвращает слот ключа записи хеша в виде значения char*, выполняя необходимые разыменования, возможно, SV* ключей. Длина строки помещается в len (это макрос, поэтому не используйте &len). Если вам не нужна длина ключа, вы можете использовать глобальную переменную PL_na, хотя это несколько менее эффективно, чем использование локальной переменной. Однако помните, что ключи хешей в Perl могут содержать вложенные нули, поэтому использование strlen() или аналогичного не является хорошим способом определения длины ключей хешей. Это очень похоже на макрос SvPV(), описанный в другом месте этого документа. См. также "HeUTF8".

Если вы используете HePV для получения значений, которые нужно передать в newSVpvn() для создания нового SV, следует рассмотреть использование newSVhek(HeKEY_hek(he)), так как это более эффективно.

char*   HePV(HE* he, STRLEN len)

HeSVKEY

Возвращает ключ как SV*, или NULL, если запись хеша не содержит SV* ключ.

SV*     HeSVKEY(HE* he)

HeSVKEY_force

Возвращает ключ как SV*. Создаст и вернёт временный смертный SV*, если запись хеша содержит только char* ключ.

SV*     HeSVKEY_force(HE* he)

HeSVKEY_set

Устанавливает ключ на заданное SV*, следя за тем, чтобы установить соответствующие флаги для обозначения наличия SV* ключа и возвращает тот же SV*.

SV*     HeSVKEY_set(HE* he, SV* sv)

HeUTF8

Возвращает, закодировано ли значение char *, возвращаемое HePV, в UTF-8, выполняя необходимые разыменования, возможно, SV* ключей. Возвращаемое значение будет 0 или ненулевым, необязательно 1 (или даже значением с установленными битами младшего разряда), поэтому не следует слепо присваивать это значение переменной bool, так как bool может быть типом данных для char.

U32     HeUTF8(HE* he)

HeVAL

Возвращает слот значения (тип SV*) хранящийся в записи хеша. Может быть присвоено значение.

SV *foo= HeVAL(hv);
HeVAL(hv)= sv;


      SV*     HeVAL(HE* he)

hv_assert

Проверяет, находится ли хеш в внутренне согласованном состоянии.

void    hv_assert(HV *hv)

hv_bucket_ratio

Если хеш привязан, то выполняет обращение к методу SCALAR, иначе, если хеш не содержит ключей, возвращает 0, иначе возвращает смертный sv, содержащий строку, указывающую количество используемых ведер, после которой следует косая черта и количество доступных ведер.

Эта функция дорогостоящая, она должна просканировать все ведра, чтобы определить, какие из них используются, и счётчик НЕ кэшируется. В большом хеше это может быть много ведер.

SV*     hv_bucket_ratio(HV *hv)

hv_clear

Освобождает все элементы хеша, оставляя его пустым. XS-эквивалент %hash = (). См. также "hv_undef".

См. "av_clear" для заметки о том, что хеш, возможно, недействителен по возвращении.

void    hv_clear(HV *hv)

hv_clear_placeholders

Очищает все плейсхолдеры из хеша. Если ограниченный хеш имеет какие-либо ключи, помеченные как только для чтения, и ключ впоследствии удалён, ключ фактически не удаляется, а помечается присвоением значения &PL_sv_placeholder. Это пометочка, чтобы он игнорировался будущими операциями, такими как итерация по хешу, но при этом позволит переназначить значение ключу в будущем. Эта функция очищает все такие ключи-заполнители из хеша. См. Hash::Util::lock_keys() для примера использования.

void    hv_clear_placeholders(HV *hv)

hv_copy_hints_hv

Специализированная версия "newHVhv" для копирования %^H. ohv должен быть указателем на хеш (который может иметь %^H магию, но должен быть в целом не магическим) или NULL (интерпретируется как пустой хеш). Содержимое ohv копируется в новый хеш, которому добавляется специфичная для %^H магия. Возвращается указатель на новый хеш.

HV *    hv_copy_hints_hv(HV *ohv)

hv_delete

Удаляет пару ключ/значение в хеше. SV значения удаляется из хеша, делается смертельным и возвращается вызывающей стороне. Абсолютное значение klen равно длине ключа. Если klen отрицательно, ключ предполагается закодированным в UTF-8. Значение flags обычно равно нулю; если установлено в G_DISCARD, то возвращается NULL. NULL также будет возвращено, если ключ не найден.

SV*     hv_delete(HV *hv, const char *key, I32 klen,
                  I32 flags)

hv_delete_ent

Удаляет пару ключ/значение в хеше. SV значения удаляется из хеша, делается смертельным и возвращается вызывающей стороне. Значение flags обычно равно нулю; если установлено в G_DISCARD, то возвращается NULL. NULL также будет возвращено, если ключ не найден. hash может быть допустимым предварительно вычисленным значением хеша или 0, чтобы запросить его вычисление.

SV*     hv_delete_ent(HV *hv, SV *keysv, I32 flags,
                      U32 hash)

HvENAME

Возвращает эффективное имя хранилища или NULL, если его нет. Эффективное имя представляет расположение в таблице символов, где находится это хранилище. Оно автоматически обновляется, когда пакеты алиасируются или удаляются. Хранилище, которое больше не находится в таблице символов, не имеет эффективного имени. Это имя предпочтительнее HvNAME для использования в линейных последовательностях MRO и кэшах isa.

char*   HvENAME(HV* stash)

HvENAMELEN

Возвращает длину эффективного имени хранилища.

STRLEN  HvENAMELEN(HV *stash)

HvENAMEUTF8

Возвращает true, если эффективное имя закодировано в UTF-8.

unsigned char HvENAMEUTF8(HV *stash)

hv_exists

Возвращает булевое значение, указывающее, существует ли указанный ключ хеша. Абсолютное значение klen равно длине ключа. Если klen отрицательно, ключ предполагается закодированным в UTF-8.

bool    hv_exists(HV *hv, const char *key, I32 klen)

hv_exists_ent

Возвращает булевое значение, указывающее, существует ли указанный ключ хеша. hash может быть допустимым предварительно вычисленным значением хеша или 0, чтобы запросить его вычисление.

bool    hv_exists_ent(HV *hv, SV *keysv, U32 hash)

hv_fetch

Возвращает SV, соответствующий указанному ключу в хеше. Абсолютное значение klen равно длине ключа. Если klen отрицательно, ключ предполагается закодированным в UTF-8. Если lval установлено, то извлечение будет частью операции сохранения. Это означает, что если в хеше нет значения, связанного с заданным ключом, то оно создаётся, и возвращается указатель на него. На SV* можно присвоить значение. Но всегда проверяйте, что возвращаемое значение не равно NULL, перед разыменованием его в SV*.

См. "Understanding the Magic of Tied Hashes and Arrays" в perlguts для получения дополнительной информации о том, как использовать эту функцию с привязанными хешами.

SV**    hv_fetch(HV *hv, const char *key, I32 klen,
                 I32 lval)

hv_fetchs

Как hv_fetch, но принимает строку-литерал вместо пары строка/длина.

SV**    hv_fetchs(HV* tb, "literal string" key,
                  I32 lval)

hv_fetch_ent

Возвращает запись хеша, соответствующую заданному ключу в хеше. hash должен быть допустимым предварительно вычисленным номером хеша для данного key, или 0, если вы хотите, чтобы функция вычислила его. Если lval установлено, то извлечение будет частью сохранения. Убедитесь, что возвращаемое значение не равно NULL, прежде чем обращаться к нему. Значение возврата, когда hv - это привязанный хеш, - это указатель на статическое местоположение, поэтому обязательно скопируйте структуру, если вам нужно сохранить её где-то.

HE*     hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
                     U32 hash)

hv_fill

Возвращает количество используемых ведер хеша.

Эта функция обернута макросом HvFILL.

Начиная с perl 5.25 эта функция используется только для отладки, и количество используемых ведер хеша никак не кэшируется, поэтому эта функция может быть дорогостоящей, так как она должна итерировать по всем ведрам в хеше.

STRLEN  hv_fill(HV *const hv)

hv_iterinit

Подготавливает начальную точку для обхода хэш-таблицы. Возвращает количество ключей в хэше, включая заглушки (т.е. то же, что и HvTOTALKEYS(hv)). Возвращаемое значение в настоящее время имеет смысл только для хэшей без магии связывания.

ПРИМЕЧАНИЕ: До версии 5.004_65 hv_iterinit возвращало количество используемых хэш-корзин. Если вам все еще нужно это экзотическое значение, вы можете получить его через макрос HvFILL(hv).

I32     hv_iterinit(HV *hv)

hv_iterkey

Возвращает ключ из текущей позиции итератора хэша. См. "hv_iterinit".

char*   hv_iterkey(HE* entry, I32* retlen)

hv_iterkeysv

Возвращает ключ в виде SV* из текущей позиции итератора хэша. Возвращаемое значение всегда будет смертной копией ключа. Также см. "hv_iterinit".

SV*     hv_iterkeysv(HE* entry)

hv_iternext

Возвращает записи из итератора хэша. См. "hv_iterinit".

Вы можете вызвать hv_delete или hv_delete_ent для записи хэша, на которую в данный момент указывает итератор, без потери позиции или недействительности итератора. Обратите внимание, что в этом случае текущая запись удаляется из хэша, при этом ваш итератор удерживает последнюю ссылку на нее. Ваш итератор помечен для освобождения записи при следующем вызове hv_iternext, поэтому вы не должны сразу отбрасывать свой итератор, иначе запись будет утечка - вызовите hv_iternext для запуска освобождения ресурсов.

HE*     hv_iternext(HV *hv)

hv_iternextsv

Выполняет hv_iternext, hv_iterkey и hv_iterval в одной операции.

SV*     hv_iternextsv(HV *hv, char **key, I32 *retlen)

hv_iternext_flags

Возвращает записи из итератора хэша. См. "hv_iterinit" и "hv_iternext". Значение flags обычно равно нулю; если HV_ITERNEXT_WANTPLACEHOLDERS установлено, заглушки ключей (для ограниченных хэшей) возвращаются в дополнение к обычным ключам. По умолчанию заглушки автоматически пропускаются. В настоящее время заглушка реализована со значением &PL_sv_placeholder. Обратите внимание, что реализация заглушек и ограниченных хэшей может измениться, и текущая реализация недостаточно абстрактна для того, чтобы любые изменения были аккуратными.

HE*     hv_iternext_flags(HV *hv, I32 flags)

hv_iterval

Возвращает значение из текущей позиции итератора хэша. См. "hv_iterkey".

SV*     hv_iterval(HV *hv, HE *entry)

hv_magic

Добавляет магию к хэшу. См. "sv_magic".

void    hv_magic(HV *hv, GV *gv, int how)

HvNAME

Возвращает имя пакета хранилища или NULL , если stash не является хранилищем. См. "SvSTASH", "CvSTASH".

char*   HvNAME(HV* stash)

HvNAMELEN

Возвращает длину имени хранилища.

STRLEN  HvNAMELEN(HV *stash)

HvNAMEUTF8

Возвращает true, если имя закодировано в UTF-8.

unsigned char HvNAMEUTF8(HV *stash)

hv_scalar

Оценивает хэш в скалярном контексте и возвращает результат.

При связывании хэша перенаправляется в метод SCALAR, в противном случае возвращает смертный SV, содержащий количество ключей в хэше.

Обратите внимание, что до версии 5.25 эта функция возвращала то, что сейчас возвращает функция hv_bucket_ratio().

SV*     hv_scalar(HV *hv)

hv_store

Сохраняет SV в хэше. Ключ хэша задается как key, а абсолютное значение klen — длина ключа. Если klen отрицательно, ключ считается закодированным в Unicode в UTF-8. Параметр hash — предварительно вычисленное значение хэша; если оно равно нулю, Perl вычислит его.

Возвращаемое значение будет NULL, если операция завершилась неудачно или если значение не нужно было фактически хранить в хэше (например, в случае связанных хэшей). В противном случае можно получить доступ к исходному значению SV*. Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счетчика ссылок val перед вызовом и уменьшение его, если функция вернула NULL. В сущности, успешный hv_store берет на себя владение одной ссылкой на val. Это обычно то, что вам нужно; у недавно созданного SV счетчик ссылок равен единице, поэтому если весь ваш код создает SV и сохраняет их в хэше, hv_store будет владеть единственной ссылкой на новый SV, и вашему коду не нужно будет ничего дополнительно делать для очистки. hv_store не реализуется как вызов hv_store_ent, и не создает временный SV для ключа, поэтому если ваши данные ключа не находятся в форме SV, используйте hv_store вместо hv_store_ent.

См. "Understanding the Magic of Tied Hashes and Arrays" в perlguts для получения дополнительной информации о том, как использовать эту функцию для связанных хэшей.

SV**    hv_store(HV *hv, const char *key, I32 klen,
                 SV *val, U32 hash)

hv_stores

Как hv_store, но принимает строку в виде литерала вместо пары "строка/длина" и опускает параметр хэша.

SV**    hv_stores(HV* tb, "literal string" key, SV* val)

hv_store_ent

Сохраняет val в хэш. Ключ хэша задается как key. Параметр hash — предварительно вычисленное значение хэша; если оно равно нулю, Perl вычислит его. Возвращаемое значение — новая запись хэша, созданная таким образом. Это будет NULL, если операция завершилась неудачно или если значение не нужно было фактически хранить в хэше (как в случае с связанными хэшами). В противном случае содержимое возвращаемого значения можно получить с помощью макросов He? , описанных здесь. Обратите внимание, что вызывающая сторона отвечает за надлежащее увеличение счетчика ссылок val перед вызовом и уменьшение его, если функция вернула NULL. В сущности, успешный hv_store_ent берет на себя владение одной ссылкой на val. Это обычно то, что вам нужно; у недавно созданного SV счетчик ссылок равен единице, поэтому если весь ваш код создает SV и сохраняет их в хэше, hv_store будет владеть единственной ссылкой на новый SV, и вашему коду не нужно будет ничего дополнительно делать для очистки. Обратите внимание, что hv_store_ent только считывает key; в отличие от val, он не берет на себя владения им, поэтому поддержание правильного счетчика ссылок для key полностью возлагается на вызывающую сторону. Причина, по которой он не берет на себя владения, заключается в том, что key не используется после возвращения этой функции, и поэтому может быть освобожден немедленно. hv_store не реализуется как вызов hv_store_ent, и не создает временный SV для ключа, поэтому если ваши данные ключа не находятся в форме SV, используйте hv_store вместо hv_store_ent.

HE*     hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)

hv_undef

Удаляет хэш. Аналог undef(%hash) в XS.

Помимо освобождения всех элементов хэша (как hv_clear() ), это также освобождает все вспомогательные данные и хранилища, связанные с хэшем.

См. "av_clear" для примечания о том, что хэш может стать недействительным при возврате.

void    hv_undef(HV *hv)

newHV

Создает новый HV. Счетчик ссылок установлен в 1.

HV*     newHV()

Управление крючками

Эти функции обеспечивают удобный и потокобезопасный способ управления переменными крючков.

wrap_op_checker

Помещает C-функцию в цепочку функций проверки для указанного типа оператора. Это предпочтительный способ управления массивом "PL_check". opcode определяет тип оператора, который будет затронут. new_checker — указатель на C-функцию, которая должна быть добавлена в цепочку проверки этого кода операции, а old_checker_p указывает на место хранения указателя на следующую функцию в цепочке. Значение new_checker записывается в массив "PL_check", а значение, ранее хранившееся там, записывается в *old_checker_p.

"PL_check" является глобальной переменной для всего процесса, и модуль, желающий подключить проверку оператора, может быть вызван более одного раза на процесс, обычно в разных потоках. Для обработки этой ситуации эта функция идемпотентна. Место *old_checker_p изначально (один раз на процесс) должно содержать нулевой указатель. C-переменная статического срока действия (объявленная на уровне файла, обычно также помеченная static, чтобы дать ей внутреннюю связь) будет неявно инициализирована должным образом, если у нее нет явного инициализатора. Эта функция будет фактически изменять цепочку проверки только в том случае, если найдет *old_checker_p равным нулю. Эта функция также потокобезопасна в малом масштабе. Она использует соответствующие блокировки, чтобы избежать гонок при доступе к "PL_check".

Когда эта функция вызывается, функция, на которую ссылается new_checker , должна быть готова к вызову, за исключением того, что *old_checker_p не заполнен. В ситуации с потоками new_checker может быть вызвана немедленно, даже до возврата этой функции. *old_checker_p всегда будет должным образом установлено перед вызовом new_checker. Если new_checker решит не делать ничего особенного с полученным оператором (что является обычным случаем для большинства применений подключения проверки оператора), оно должно связать функцию проверки, на которую ссылается *old_checker_p.

В совокупности код XS для подключения проверки оператора обычно выглядит следующим образом:

static Perl_check_t nxck_frob;
static OP *myck_frob(pTHX_ OP *op) {
    ...
    op = nxck_frob(aTHX_ op);
    ...
    return op;
}
BOOT:
    wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);

Если вы хотите повлиять на компиляцию вызовов конкретной подпрограммы, используйте "cv_set_call_checker_flags" вместо подключения проверки всех entersub операторов.

void    wrap_op_checker(Optype opcode,
                        Perl_check_t new_checker,
                        Perl_check_t *old_checker_p)

Интерфейс лексического анализатора

Это нижний уровень Perl-парсера, управляющий символами и токенами.

lex_bufutf8

Указывает, должны ли байты в буфере лексера ("PL_parser->linestr") интерпретироваться как кодировка UTF-8 для символов Юникода. В противном случае они должны интерпретироваться как символы Latin-1. Это аналогично флагу SvUTF8 для скаляров.

В режиме UTF-8 нет гарантии, что буфер лексера фактически содержит допустимый UTF-8. Код лексирования должен быть устойчивым к некорректной кодировке.

Флаг SvUTF8 скаляра "PL_parser->linestr" фактически значим, но не является единственным фактором, определяющим кодировку входных символов. Обычно, при чтении файла скаляр содержит байты, и его флаг SvUTF8 выключен, но байты должны интерпретироваться как UTF-8, если в силе прагма use utf8. Однако во время выполнения строкового кода скаляр может иметь установленный флаг SvUTF8, и в этом случае его байты должны интерпретироваться как UTF-8, если не в силе прагма use bytes. Эта логика может измениться в будущем; используйте эту функцию вместо самостоятельной реализации логики.

bool    lex_bufutf8()

lex_discard_to

Отбрасывает часть буфера "PL_parser->linestr" до ptr. Остальное содержимое буфера будет перемещено, а все указатели в буфер будут обновлены соответствующим образом. ptr не должен находиться дальше в буфере, чем позиция "PL_parser->bufptr": отбрасывать текст, который ещё не был проанализирован, запрещено.

Обычно это не обязательно делать непосредственно, так как достаточно использовать неявное поведение отбрасывания "lex_next_chunk" и связанных с ним функций. Однако, если токен охватывает несколько строк, и код лексирования сохранил несколько строк текста в буфере для этой цели, то после завершения токена было бы разумно явно отбросить теперь ненужные предыдущие строки, чтобы избежать неограниченного роста буфера при обработке многострочных токенов.

void    lex_discard_to(char *ptr)

lex_grow_linestr

Перевыделяет буфер лексера ("PL_parser->linestr") для размещения как минимум len байтов (включая завершающий NUL). Возвращает указатель на перевыделенный буфер. Это необходимо перед любыми прямыми изменениями буфера, которые увеличат его длину. "lex_stuff_pvn" предоставляет более удобный способ вставки текста в буфер.

Не используйте SvGROW или sv_grow непосредственно с PL_parser->linestr; эта функция обновляет все переменные лексера, которые указывают непосредственно на буфер.

char *  lex_grow_linestr(STRLEN len)

lex_next_chunk

Считывает следующий фрагмент текста для лексического анализа, добавляя его к "PL_parser->linestr". Это нужно вызывать, когда код лексирования дошел до конца текущего фрагмента и хочет получить больше данных. Обычно, но необязательно, лексирование потребляет весь текущий фрагмент в этот момент.

Если "PL_parser->bufptr" указывает на самый конец текущего фрагмента (т.е., текущий фрагмент полностью обработан), обычно текущий фрагмент будет отброшен одновременно с чтением нового фрагмента. Если flags имеет установленный бит LEX_KEEP_PREVIOUS, текущий фрагмент не будет отброшен. Если текущий фрагмент не полностью обработан, он не будет отброшен независимо от флага.

Возвращает true, если в буфер был добавлен новый текст, или false, если буфер достиг конца входного текста.

bool    lex_next_chunk(U32 flags)

lex_peek_unichar

Предварительно просматривает следующий (символ Юникода) в тексте, который в настоящее время анализируется. Возвращает код символа (целое без знака) следующего символа или -1, если лексирование достигло конца входного текста. Для обработки просмотренного символа используйте "lex_read_unichar".

Если следующий символ находится (или простирается в) следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет отброшен одновременно, но если flags имеет установленный бит LEX_KEEP_PREVIOUS, текущий фрагмент не будет отброшен.

Если вход интерпретируется как UTF-8, и встречается ошибка кодировки UTF-8, генерируется исключение.

I32     lex_peek_unichar(U32 flags)

lex_read_space

Считывает необязательные пробелы в стиле Perl в тексте, который в настоящее время анализируется. Пробелы могут включать обычные пробельные символы и комментарии в стиле Perl. #line директивы обрабатываются при встрече. "PL_parser->bufptr" перемещается мимо пробелов, так что он указывает на символ, не являющийся пробелом (или конец входного текста).

Если пробелы простираются в следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет отброшен одновременно, но если flags имеет установленный бит LEX_KEEP_PREVIOUS, текущий фрагмент не будет отброшен.

void    lex_read_space(U32 flags)

lex_read_to

Обрабатывает текст в буфере лексера, от "PL_parser->bufptr" до ptr. Это перемещает "PL_parser->bufptr" для соответствия ptr, выполняя корректные операции при прохождении символа новой строки. Это обычный способ обработки проанализированного текста.

Интерпретацию байтов буфера можно абстрагировать, используя функции более высокого уровня "lex_peek_unichar" и "lex_read_unichar".

void    lex_read_to(char *ptr)

lex_read_unichar

Читает следующий (символ Юникода) в тексте, который в настоящее время анализируется. Возвращает код символа (целое без знака) прочитанного символа и перемещает "PL_parser->bufptr" за символом или возвращает -1, если лексирование достигло конца входного текста. Для неразрушающего просмотра следующего символа используйте "lex_peek_unichar".

Если вход интерпретируется как UTF-8, и встречается ошибка кодировки UTF-8, генерируется исключение.

I32     lex_read_unichar(U32 flags)

lex_start

Создаёт и инициализирует новый объект состояния лексера/парсера, предоставляя контекст для лексического анализа и разбора нового источника кода Perl. Указатель на новый объект состояния помещается в "PL_parser". В стеке сохранения создаётся запись, чтобы при разворачивании новый объект состояния был уничтожен, а прежнее значение "PL_parser" было восстановлено. Больше ничего не нужно делать для очистки контекста разбора.

Анализируемый код берётся из line и rsfp. line, если не равно нулю, предоставляет строку (в формате SV) содержащую код для разбора. Создаётся копия строки, поэтому последующие изменения line не влияют на разбор. rsfp, если не равно нулю, предоставляет поток ввода, из которого будет считываться код для разбора. Если оба не равны нулю, код в line идёт первым и должен состоять из полных строк ввода, а rsfp предоставляет остальную часть исходного кода.

Параметр flags зарезервирован для будущего использования. В настоящее время он используется только Perl внутри, поэтому расширения всегда должны передавать ноль.

void    lex_start(SV *line, PerlIO *rsfp, U32 flags)

lex_stuff_pv

Вставляет символы в буфер лексера ("PL_parser->linestr") сразу после текущей точки лексического анализа ("PL_parser->bufptr"), перевыделяя буфер при необходимости. Это означает, что код лексирования, который выполняется позже, будет видеть символы так, как будто они появились в вводе. Не рекомендуется делать это как часть обычного разбора, и большинство применений этой функции рискуют неправильной интерпретацией вставленных символов.

Строка для вставки представляется байтами, начинающимися в pv и продолжающимися до первого нуля. Эти байты интерпретируются как UTF-8 или Latin-1 в зависимости от того, установлен ли флаг LEX_STUFF_UTF8 в flags. Символы перекодируются для буфера лексера в соответствии с тем, как в настоящее время интерпретируется буфер ("lex_bufutf8"). Если неудобно завершать строку нулём для вставки, более подходящей функцией является "lex_stuff_pvn".

void    lex_stuff_pv(const char *pv, U32 flags)

lex_stuff_pvn

Строка для вставки представлена len байтами, начинающимися в pv. Эти байты интерпретируются как UTF-8 или Latin-1, в зависимости от того, установлен ли флаг LEX_STUFF_UTF8 в flags. Символы перекодируются для буфера лексера в соответствии с тем, как в настоящее время интерпретируется буфер ("lex_bufutf8"). Если строка для вставки доступна как скаляр Perl, более удобной функцией является "lex_stuff_sv".

void    lex_stuff_pvn(const char *pv, STRLEN len,
                      U32 flags)

lex_stuff_pvs

Как "lex_stuff_pvn", но принимает строку-литерал вместо пары строка/длина.

void    lex_stuff_pvs("literal string" pv, U32 flags)

lex_stuff_sv

Вставляет символы в буфер лексического анализатора ("PL_parser->linestr"), сразу после текущей точки лексического анализа ("PL_parser->bufptr"), перераспределяя буфер при необходимости. Это означает, что код лексического анализа, выполняющийся позже, увидит символы так, как будто они появились в входных данных. Не рекомендуется делать это в рамках обычного анализа, и большинство применений этой функции рискуют тем, что вставленные символы будут интерпретированы нежелательным образом.

Вставляемая строка — это строковое значение sv. Символы кодируются для буфера лексического анализатора в соответствии с текущей интерпретацией буфера ("lex_bufutf8"). Если вставляемая строка еще не является скаляром Perl, функция "lex_stuff_pvn" позволяет избежать необходимости создания скаляра.

void    lex_stuff_sv(SV *sv, U32 flags)

lex_unstuff

Отбрасывает текст, который собираются проанализировать, начиная с "PL_parser->bufptr" до ptr. Текст, следующий за ptr, будет перемещен, а буфер укорочен. Это скрывает отбрасываемый текст от любого кода лексического анализа, выполняющегося позже, как будто этот текст никогда не появлялся.

Это не обычный способ потребления проанализированного текста. Для этого используйте "lex_read_to".

void    lex_unstuff(char *ptr)

parse_arithexpr

Анализирует арифметическое выражение Perl. Оно может содержать операторы приоритета вплоть до операторов битовых сдвигов. Выражение должно быть завершено либо оператором сравнения или оператором с меньшим приоритетом, либо чем-то, что обычно завершает выражение, например, точкой с запятой. Если flags имеет бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае — обязательным. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода и лексического контекста для выражения.

Возвращается дерево операций, представляющее выражение. Если необязательное выражение отсутствует, возвращается нулевой указатель, в противном случае указатель не будет нулевым.

В случае возникновения ошибки при анализе или компиляции, в большинстве случаев возвращается действительное дерево операций. Об ошибке сообщается в состоянии парсера, что обычно приводит к одному исключению на верхнем уровне анализа, охватывающему все возникшие ошибки компиляции. Некоторые ошибки компиляции, однако, вызовут исключение немедленно.

OP *    parse_arithexpr(U32 flags)

parse_barestmt

Анализирует единственное простое утверждение Perl. Это может быть обычное императивное утверждение или объявление, имеющее эффект во время компиляции. Оно не включает метку или другие приставки. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода и лексического контекста для утверждения.

Возвращается дерево операций, представляющее утверждение. Оно может быть нулевым указателем, если утверждение является нулевым, например, если это было фактически определение подпрограммы (которое имеет побочный эффект во время компиляции). Если не нулевой, это будут операции, непосредственно реализующие утверждение, подходящие для передачи в "newSTATEOP". Обычно он не будет включать nextstate или эквивалентную операцию (кроме тех, которые встроены в область, полностью содержащуюся в утверждении).

Если при анализе или компиляции возникнет ошибка, в большинстве случаев возвращается действительное дерево операций (скорее всего, нулевое). Об ошибке сообщается в состоянии парсера, что обычно приводит к одному исключению на верхнем уровне анализа, охватывающему все возникшие ошибки компиляции. Некоторые ошибки компиляции, однако, вызовут исключение немедленно.

Параметр flags зарезервирован для будущего использования и должен всегда быть нулевым.

OP *    parse_barestmt(U32 flags)

parse_block

Анализирует один полный блок кода Perl. Он состоит из открытой фигурной скобки, последовательности утверждений и закрывающей фигурной скобки. Блок представляет собой лексическую область, поэтому my переменные и различные эффекты во время компиляции могут быть в нём содержатся. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода и лексического контекста для утверждения.

Возвращается дерево операций, представляющее блок кода. Это всегда действительная операция, никогда не нулевой указатель. Обычно это список lineseq, включая nextstate или эквивалентные операции. Операции для создания любого типа области выполнения не включены в силу того, что это блок.

В случае возникновения ошибки при анализе или компиляции, в большинстве случаев возвращается действительное дерево операций (скорее всего, нулевое). Об ошибке сообщается в состоянии парсера, что обычно приводит к одному исключению на верхнем уровне анализа, охватывающему все возникшие ошибки компиляции. Некоторые ошибки компиляции, однако, вызовут исключение немедленно.

Параметр flags зарезервирован для будущего использования и должен всегда быть нулевым.

OP *    parse_block(U32 flags)

parse_fullexpr

Анализирует одно полное выражение Perl. Это позволяет использовать всю грамматику выражений, включая операторы с наименьшим приоритетом, такие как or. Выражение должно быть завершено токеном, которым обычно завершается выражение: концом файла, закрывающей скобкой, точкой с запятой или одним из ключевых слов, которые обозначают модификатор оператора выражения послефикс. Если flags имеет бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае — обязательным. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода и лексического контекста для выражения.

OP *    parse_fullexpr(U32 flags)

parse_fullstmt

Анализирует одно полное утверждение Perl. Это может быть обычное императивное утверждение или объявление, имеющее эффект во время компиляции, и может включать необязательные метки. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода и лексического контекста для утверждения.

Возвращается дерево операций, представляющее утверждение. Оно может быть нулевым указателем, если утверждение является нулевым, например, если это было фактически определение подпрограммы (которое имеет побочный эффект во время компиляции). Если не нулевой, это будет результат вызова "newSTATEOP", обычно включающий nextstate или эквивалентную операцию.

Параметр flags зарезервирован для будущего использования и должен всегда быть нулевым.

OP *    parse_fullstmt(U32 flags)

parse_label

Анализирует единственную метку, возможно необязательную, типа, который может предварять утверждение Perl. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода. Если flags имеет бит PARSE_OPTIONAL, то метка является необязательной, в противном случае — обязательной.

Имя метки возвращается в виде свежего скаляра. Если необязательная метка отсутствует, возвращается нулевой указатель.

Если при анализе возникнет ошибка, которая может произойти только в том случае, если метка обязательна, метка возвращается как действительная. Об ошибке сообщается в состоянии парсера, что обычно приводит к одному исключению на верхнем уровне анализа, охватывающему все возникшие ошибки компиляции.

SV *    parse_label(U32 flags)

parse_listexpr

Анализирует выражение списка Perl. Оно может содержать операторы приоритета вплоть до оператора запятой. Выражение должно быть завершено либо логическим оператором низкого приоритета, например, or, либо чем-то, что обычно завершает выражение, например, точкой с запятой. Если flags имеет бит PARSE_OPTIONAL, то выражение необязательное, в противном случае — обязательное. От вызывающей стороны требуется обеспечить правильное задание динамического состояния парсера ("PL_parser" и т. д.) для отражения источника анализируемого кода и лексического контекста для выражения.

OP *    parse_listexpr(U32 flags)

parse_stmtseq

Разбирает последовательность нуля или более перловых операторов. Они могут быть обычными операторами, включая необязательные метки, или объявлениями, которые оказывают влияние на время компиляции, или любой их комбинацией. Последовательность операторов заканчивается, когда встречается закрывающая фигурная скобка или конец файла в месте, где новый оператор мог бы быть допустимо начат. От вызывающей стороны требуется, чтобы динамическое состояние анализатора ("PL_parser" и т. д.) было правильно установлено для отражения источника кода, подлежащего разбору, и лексического контекста для операторов.

Возвращается дерево операторов, представляющее последовательность операторов. Это может быть указатель на пустой объект, если все операторы были пустыми, например, если операторов не было или если были только определения подпрограмм (которые имеют побочные эффекты во время компиляции). Если указатель не пустой, это будет lineseq список, обычно включающий nextstate или эквивалентные операторы.

Если при разборе или компиляции произошла ошибка, в большинстве случаев возвращается действительное дерево операторов. Об ошибке отражается в состоянии анализатора, что обычно приводит к одному исключению на верхнем уровне разбора, которое охватывает все произошедшие ошибки компиляции. Однако некоторые ошибки компиляции будут выбрасывать исключение немедленно.

Параметр flags зарезервирован для будущего использования и всегда должен быть равен нулю.

OP *    parse_stmtseq(U32 flags)

parse_termexpr

Разбирает выражение перлового термина. Оно может содержать операторы с приоритетом до операторов присваивания. Выражение должно следовать (и тем самым завершаться) либо запятой, либо оператором с меньшим приоритетом, либо чем-то, что обычно завершает выражение, например, точкой с запятой. Если flags имеет установленный бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно обязательно. От вызывающей стороны требуется, чтобы динамическое состояние анализатора ("PL_parser" и т. д.) было правильно установлено для отражения источника кода, подлежащего разбору, и лексического контекста для выражения.

Возвращается дерево операторов, представляющее выражение. Если необязательное выражение отсутствует, возвращается указатель на пустой объект, в противном случае указатель не пустой.

OP *    parse_termexpr(U32 flags)

PL_parser

Указатель на структуру, которая описывает состояние операции разбора, которая в данный момент выполняется. Указатель может быть локально изменён для выполнения вложенного разбора без вмешательства в состояние внешнего разбора. Отдельные члены PL_parser имеют собственные документации.

PL_parser->bufend

Прямой указатель на конец фрагмента текста, который в данный момент лексируется, конец буфера лексического анализатора. Это равно SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr). Символ NUL (нулевой байт) всегда расположен в конце буфера и не считается частью содержимого буфера.

PL_parser->bufptr

Указывает на текущую позицию лексического анализа внутри буфера лексического анализатора. Символы вокруг этой точки могут быть свободно просмотрены в диапазоне, ограниченном SvPVX("PL_parser->linestr") и "PL_parser->bufend". Байты буфера могут быть предназначены для интерпретации как UTF-8, так и Latin-1, как указано в "lex_bufutf8".

Код лексического анализа (будь то в ядре Perl или нет) перемещает этот указатель мимо потребляемых символов. Также ожидается, что он выполнит некоторые бухгалтерские операции всякий раз, когда потребляется символ новой строки. Это перемещение можно более удобно выполнить с помощью функции "lex_read_to", которая обрабатывает символы новой строки соответствующим образом.

Интерпретацию байтов буфера можно абстрагировать, используя немного более высокоуровневые функции "lex_peek_unichar" и "lex_read_unichar".

PL_parser->linestart

Указывает на начало текущей строки внутри буфера лексического анализатора. Это полезно для указания столбца, в котором произошла ошибка, и почти больше ни для чего. Это должно обновляться любым кодом лексического анализа, который потребляет символ новой строки; функция "lex_read_to" обрабатывает эту деталь.

PL_parser->linestr

Буфер скаляр, содержащий фрагмент, который в данный момент рассматривается, текста, который в данный момент лексируется. Это всегда обычный строковый скаляр (для которого SvPOK верно). Не предполагается использовать его как скаляр обычным способом; вместо этого обращайтесь к буферу напрямую с помощью указателей переменных, описанных ниже.

Лексический анализатор сохраняет различные char* указатели на вещи в буфере PL_parser->linestr. Если буфер PL_parser->linestr будет перераспределён, все эти указатели должны быть обновлены. Не пытайтесь делать это вручную, а используйте "lex_grow_linestr", если вам нужно перераспределить буфер.

Содержимое фрагмента текста в буфере обычно представляет собой ровно одну полную строку входных данных, включая символ новой строки, но есть ситуации, когда это иначе. Байты буфера могут быть предназначены для интерпретации как UTF-8, так и Latin-1. Функция "lex_bufutf8" сообщает вам, какой.

Не используйте флаг SvUTF8 на этом скаляре, который может противоречить ему.

Для прямого просмотра буфера переменная "PL_parser->bufend" указывает на конец буфера. Текущая позиция лексического анализатора указывается переменной "PL_parser->bufptr". Прямое использование этих указателей обычно предпочтительнее, чем просмотр скаляра обычным способом.

wrap_keyword_plugin

Вставляет C-функцию в цепочку плагинов ключевых слов. Это предпочтительный способ манипулирования переменной "PL_keyword_plugin". new_plugin — указатель на C-функцию, которая должна быть добавлена в цепочку плагинов ключевых слов, а old_plugin_p указывает на место хранения указателя на следующую функцию в цепочке. Значение new_plugin записывается в переменную "PL_keyword_plugin", а значение, ранее хранившееся там, записывается в *old_plugin_p.

"PL_keyword_plugin" является глобальной для всего процесса, и модуль, желающий подключиться к разбору ключевых слов, может быть вызван более одного раза на процесс, как правило, в разных потоках. Для обработки этой ситуации функция является идемпотентной. Место *old_plugin_p первоначально (один раз на процесс) должно содержать пустой указатель. C-переменная со статическим сроком жизни (объявленная на уровне файла, обычно также помеченная static для предоставления ей внутренней связи) будет неявным образом инициализирована соответствующим образом, если у неё нет явной инициализации. Эта функция будет фактически изменять цепочку плагинов только в том случае, если обнаружит *old_plugin_p пустым. Эта функция также потокобезопасна в небольших масштабах. Она использует соответствующие блокировки, чтобы избежать гонок при доступе к "PL_keyword_plugin".

Когда эта функция вызывается, функция, на которую ссылается new_plugin, должна быть готова к вызову, за исключением *old_plugin_p, которое не заполнено. В ситуации с потоками new_plugin может быть вызвана немедленно, даже до возвращения этой функции. *old_plugin_p всегда будет правильно установлено перед вызовом new_plugin. Если new_plugin решает ничего не делать со словом, которое ей дано (что является типичным случаем для большинства вызовов плагина ключевых слов), она должна передать функцию-плагин, на которую ссылается *old_plugin_p.

В совокупности код XS для установки плагина ключевых слов обычно выглядит примерно так:

static Perl_keyword_plugin_t next_keyword_plugin;
static OP *my_keyword_plugin(pTHX_
    char *keyword_plugin, STRLEN keyword_len, OP **op_ptr)
{
    if (memEQs(keyword_ptr, keyword_len,
               "my_new_keyword")) {
        ...
    } else {
        return next_keyword_plugin(aTHX_
            keyword_ptr, keyword_len, op_ptr);
    }
}
BOOT:
    wrap_keyword_plugin(my_keyword_plugin,
                        &next_keyword_plugin);

Прямой доступ к "PL_keyword_plugin" следует избегать.

void    wrap_keyword_plugin(
            Perl_keyword_plugin_t new_plugin,
            Perl_keyword_plugin_t *old_plugin_p
        )

DECLARATION_FOR_LC_NUMERIC_MANIPULATION

Этот макрос следует использовать как оператор. Он объявляет частную переменную (название которой начинается с нижнего подчеркивания), необходимую другим макросам в этом разделе. Отсутствие правильной декларации приведет к синтаксической ошибке. Для совместимости с компиляторами C89 C, его следует поместить в блок перед любыми исполняемыми операторами.

void    DECLARATION_FOR_LC_NUMERIC_MANIPULATION

Perl_langinfo

Это (почти) полная замена системной функции nl_langinfo(3), принимающая те же item параметры и возвращающая ту же информацию. Однако она более безопасна в многопоточных средах, скрывает особенности обработки локалей в Perl от вашего кода и может быть использована на системах, где отсутствует собственная nl_langinfo.

Более подробно:

Причина, по которой она не является полной заменой, на самом деле является преимуществом. Единственное отличие заключается в том, что она возвращает const char *, в то время как обычная nl_langinfo() возвращает char *, но вам (только по документации) запрещено записывать в буфер. Объявив эту const, компилятор навязывает это ограничение, поэтому, если оно нарушено, вы узнаете об этом во время компиляции, а не получите ошибку сегментирования во время выполнения.
Она обеспечивает правильные результаты для элементов RADIXCHAR и THOUSEP, без необходимости написания дополнительного кода. Причина дополнительного кода заключается в том, что эти элементы относятся к категории локалей LC_NUMERIC, которая обычно устанавливается Perl так, что разделитель десятичных знаков — точка, а разделитель — пустая строка, независимо от того, какой должна быть базовая локаль. Чтобы получить ожидаемые результаты, необходимо временно переключиться на базовую локаль, а затем вернуться обратно. (Вы могли бы использовать обычные nl_langinfo и "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING", но тогда вы бы не получили других преимуществ Perl_langinfo(); отсутствие LC_NUMERIC в C (или эквивалентной) локали нарушит работу многих модулей CPAN, которые ожидают, что разделитель десятичных знаков будет точкой.)
Система, которую она заменяет, может иметь свой статический буфер возвращаемых значений поврежден не только последующим вызовом этой же функции, но и freelocale, setlocale, или другими изменениями локали. Буфер, возвращаемый этой функцией, не изменяется до следующего вызова, поэтому буфер никогда не находится в поврежденном состоянии.
Её буфер возвращаемых значений относится к потоку, поэтому он также никогда не перезаписывается вызовом этой функции из другого потока, в отличие от функции, которую она заменяет.
Но, что самое важное, она работает на системах, где нет nl_langinfo, таких как Windows, что делает ваш код более переносимым. Из примерно пятидесяти возможных элементов, определённых стандартом POSIX 2008, http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html, только один полностью не реализован, хотя на платформах, отличных от Windows, ещё один существенный элемент также не реализован. Она использует различные техники для извлечения других элементов, включая вызов localeconv(3) и strftime(3), которые определены в C89 и, следовательно, всегда должны быть доступны. Более поздние версии strftime() обладают дополнительными возможностями; для тех, что недоступны на вашей системе, возвращается "".

Важно отметить, что при вызове с элементом, полученным с помощью localeconv, буфер из любого предыдущего явного вызова localeconv будет перезаписан. Это означает, что вам необходимо сохранить содержимое этого буфера, если вам нужно получить к нему доступ после вызова этой функции. (Однако обратите внимание, что вам, возможно, не следует использовать localeconv() напрямую из-за проблем, перечисленных во втором пункте этого списка (выше) для RADIXCHAR и THOUSEP. Вы можете использовать методы, указанные в perlcall для вызова "localeconv" в POSIX и избежать всех проблем, но тогда у вас будет хеш для распаковки).

Подробное описание тех элементов, которые могут отличаться от возвращаемых этой эмуляцией и от того, что вернула бы собственная nl_langinfo(), приведено в I18N::Langinfo.

При использовании Perl_langinfo на системах, не имеющих собственной nl_langinfo(), вы должны

#include "perl_langinfo.h"

перед perl.h #include. Вы можете заменить свою langinfo.h #include на эту. (Такой подход исключает символы, которые обычная langinfo.h пыталась бы импортировать в пространство имён для кода, которому они не нужны.)

Первоначальный стимул для Perl_langinfo() заключался в том, чтобы код, которому нужно определить текущий символ валюты, разделитель десятичных знаков или разделитель группировки цифр, мог использовать более простой и многопоточный nl_langinfo API вместо localeconv(3), что сложно сделать многопоточным. Для других полей, возвращаемых localeconv, лучше использовать методы, описанные в perlcall, для вызова POSIX::localeconv(), который многопоточный.

const char* Perl_langinfo(const nl_item item)

Perl_setlocale

Это (почти) полная замена системной функции setlocale(3), принимающая те же параметры и возвращающая ту же информацию, за исключением того, что она возвращает правильную базовую LC_NUMERIC локаль. Обычная setlocale вместо этого вернёт C, если базовая локаль имеет символ десятичного разделителя, отличного от точки, или разделитель тысяч, отличный от пустой строки, для отображения чисел с плавающей запятой. Это потому, что Perl сохраняет эту категорию локалей, чтобы она содержала точку и пустой разделитель, временно изменяя локаль во время операций, где требуется базовая. Perl_setlocale об этом знает и компенсирует; обычная setlocale — нет.

Ещё одна причина, по которой она не является полной заменой, заключается в том, что она объявлена как возвращающая const char *, в то время как системная setlocale опускает const (вероятно, потому, что её API был определён давно и не может быть обновлён; изменение информации, возвращаемой setlocale, недопустимо; при этом возникает ошибка сегментирования).

Наконец, Perl_setlocale работает во всех ситуациях, в то время как обычная setlocale может быть совершенно неэффективной на некоторых платформах в некоторых конфигурациях.

Perl_setlocale не следует использовать для изменения локали, за исключением систем, где предопределённая переменная ${^SAFE_LOCALES} равна 1. На некоторых таких системах системная setlocale() неэффективна, возвращает неправильную информацию и не изменяет локаль на самом деле. Perl_setlocale, однако, работает правильно во всех случаях.

Возвращаемое значение указывает на статический буфер, связанный с потоком, который перезаписывается при следующем вызове Perl_setlocale из того же потока.

const char* Perl_setlocale(const int category,
                           const char* locale)

RESTORE_LC_NUMERIC

Используется совместно с одним из макросов "STORE_LC_NUMERIC_SET_TO_NEEDED" и "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" для правильного восстановления LC_NUMERIC состояния.

Вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" должен был быть сделан для объявления во время компиляции частной переменной, используемой этим макросом и двумя STORE.

Этот макрос должен вызываться как отдельный оператор, а не выражение, но с пустым списком аргументов, например так:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   RESTORE_LC_NUMERIC();
    ...
}

       void    RESTORE_LC_NUMERIC()

STORE_LC_NUMERIC_FORCE_TO_UNDERLYING

Используется кодом XS, который LC_NUMERIC учитывает локаль, для принудительного изменения локали категории LC_NUMERIC на то, что Perl считает текущей базовой локалью. (Интерпретатор Perl может ошибаться относительно фактической базовой локали, если какой-то C или XS код вызывал функцию C-библиотеки setlocale(3) скрытно; вызов "sync_locale" перед вызовом этого макроса обновит записи Perl.)

Вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" должен был быть сделан для объявления во время компиляции частной переменной, используемой этим макросом.

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

Частная переменная используется для сохранения текущего состояния локали, чтобы соответствующий вызов "RESTORE_LC_NUMERIC" мог восстановить её.

В многопоточных Perl, не работающих с многопоточной безопасностью, этот макрос использует мьютекс для принудительного создания критической секции. Следовательно, соответствующий RESTORE должен быть вблизи и гарантированно вызываться.

void    STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()

STORE_LC_NUMERIC_SET_TO_NEEDED

Используется для помощи в оболочке кода XS или C, который LC_NUMERIC учитывает локаль. Эта категория локалей обычно устанавливается в локаль, где разделитель десятичных знаков — точка, а разделитель между группами цифр — пустая строка. Это связано с тем, что большинство кодов XS, которые считывают числа с плавающей запятой, ожидают их в таком формате.

Этот макрос гарантирует, что текущее LC_NUMERIC состояние установлено должным образом, чтобы учитывать локаль, если вызов XS или C-кода из Perl-программы происходит внутри области use locale; или игнорировать локаль, если вызов происходит вне такой области.

Этот макрос — начало оболочки C или XS-кода; окончание оболочки выполняется вызовом макроса "RESTORE_LC_NUMERIC" после операции. В противном случае состояние может измениться, что негативно повлияет на другой XS-код.

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_SET_TO_NEEDED();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

void    STORE_LC_NUMERIC_SET_TO_NEEDED()

switch_to_global_locale

В системах без поддержки локали, в типичных однопоточных сборках или на платформах, не поддерживающих операции с локалью на уровне потока, эта функция ничего не делает. В таких системах, которые поддерживают локаль, доступна только глобальная для всей программы локаль.

В многопоточных сборках на системах, которые поддерживают операции с локалью на уровне потока, эта функция переключает поток, в котором она выполняется, на использование глобальной локали. Это делается для кода, который ещё не или не может быть обновлён для обработки многопоточных операций с локалью. Пока преобразуется только один поток, всё работает нормально, так как все остальные потоки продолжают игнорировать глобальную локаль, поэтому только этот поток её рассматривает.

Однако, на системах Windows это не совсем верно до Visual Studio 15, после чего Microsoft исправила ошибку. Возможна гонка, если вы используете следующие операции на более ранних платформах Windows:

POSIX::localeconv
I18N::Langinfo, элементы CRNCYSTR и THOUSEP
"Perl_langinfo" в perlapi, элементы CRNCYSTR и THOUSEP

Первый элемент нельзя исправить (кроме обновления до более поздней версии Visual Studio), но можно обойти последние два элемента, используя функции API Windows GetNumberFormat и GetCurrencyFormat; предложения по исправлениям приветствуются.

Без этого вызова функции, потоки, которые используют системную функцию setlocale(3), не будут работать должным образом, так как все функции, чувствительные к локали, будут обращаться к локали на уровне потока, и setlocale не будет иметь никакого эффекта для этого потока.

Код Perl должен преобразовать вызов либо Perl_setlocale (который является прямым аналогом системной функции setlocale) или использовать методы, указанные в perlcall, для вызова POSIX::setlocale. Любой из вариантов прозрачно и правильно обрабатывает все случаи — однопоточные или многопоточные, поддерживающие POSIX 2008 или нет.

Библиотеки, не являющиеся Perl, такие как gtk, которые вызывают системную функцию setlocale, могут продолжать работать, если эта функция вызывается перед передачей управления библиотеке.

По возвращении из кода, которому требуется использование глобальной локали, следует вызвать sync_locale(), чтобы восстановить безопасную многопоточную работу.

void    switch_to_global_locale()

sync_locale

Perl_setlocale может использоваться в любое время для запроса или изменения локали (хотя изменение локали небезопасно и опасно в многопоточных системах, не имеющих многопоточно-безопасных операций с локалью. (См. "Многопоточная работа" в perllocale). Следует избегать использования системной функции setlocale(3). Тем не менее, некоторые библиотеки, не являющиеся Perl, вызываемые из XS, такие как Gtk это делают, и это нельзя изменить. Когда локаль изменяется кодом XS, который не использовал Perl_setlocale, Perl нужно сообщить, что локаль изменилась. Используйте эту функцию для этого, прежде чем вернуться в Perl.

Возвращаемое значение — логическое: TRUE, если глобальная локаль на момент вызова была активна; и FALSE, если активна локаль на уровне потока. Это может использоваться вызывающей стороной, которая нуждается в восстановлении первоначальных настроек, чтобы решить, вызывать ли Perl_switch_to_global_locale или нет.

bool    sync_locale()

Магические функции

mg_clear

Очистка магической информации, представленной SV. См. "sv_magic".

int     mg_clear(SV* sv)

mg_copy

Копирует магическую информацию из одного SV в другой. См. "sv_magic".

int     mg_copy(SV *sv, SV *nsv, const char *key,
                I32 klen)

mg_find

Поиск указателя на магическую информацию для type, соответствующего SV. См. "sv_magic".

MAGIC*  mg_find(const SV* sv, int type)

mg_findext

Поиск указателя на магическую информацию типа type с заданным vtbl для SV. См. "sv_magicext".

MAGIC*  mg_findext(const SV* sv, int type,
                   const MGVTBL *vtbl)

mg_free

Освобождение любого магического хранилища, используемого SV. См. "sv_magic".

int     mg_free(SV* sv)

mg_freeext

Удаление любой магической информации типа how, использующей виртуальную таблицу vtbl из SV sv. См. "sv_magic".

mg_freeext(sv, how, NULL) эквивалентно mg_free_type(sv, how).

void    mg_freeext(SV* sv, int how, const MGVTBL *vtbl)

mg_free_type

Удаление любой магической информации типа how из SV sv. См. "sv_magic".

void    mg_free_type(SV *sv, int how)

mg_get

Выполнение магической обработки перед получением значения из SV. Тип SV должен быть >= SVt_PVMG. См. "sv_magic".

int     mg_get(SV* sv)

mg_length

УСТАРЕВШАЯ! Планируется удалить эту функцию в будущих версиях Perl. Не используйте её в новом коде; удалите из существующего кода.

Отчёт о длине SV в байтах, вызов магической функции длины, если она доступна, но не устанавливает флаг UTF8 для sv. Обращается к магической функции 'get', если нет 'length' магической функции, но без указания, вызывалась ли 'get' магическая функция. Предполагается, что sv — PVMG или выше. Используйте sv_len() вместо этого.

U32     mg_length(SV* sv)

mg_magical

Включение магического состояния SV. См. "sv_magic".

void    mg_magical(SV* sv)

mg_set

Выполнение магической обработки после присваивания значения SV. См. "sv_magic".

int     mg_set(SV* sv)

SvGETMAGIC

Вызов mg_get для SV, если у него есть 'get' магия. Например, это вызовет FETCH для связанной переменной. Эта макрокоманда оценивает свой аргумент более одного раза.

void    SvGETMAGIC(SV* sv)

SvLOCK

Обеспечивает получение блокировки взаимного исключения для sv, если соответствующий модуль загружен.

void    SvLOCK(SV* sv)

SvSETMAGIC

Вызов mg_set для SV, если у него есть 'set' магия. Это необходимо после изменения скаляра, если это магическая переменная, например, $|, или связанная переменная (вызывает STORE). Эта макрокоманда оценивает свой аргумент более одного раза.

void    SvSETMAGIC(SV* sv)

SvSetMagicSV

Как SvSetSV, но выполняет любые необходимые 'set' магические действия после.

void    SvSetMagicSV(SV* dsv, SV* ssv)

SvSetMagicSV_nosteal

Как SvSetSV_nosteal, но выполняет любые необходимые 'set' магические действия после.

void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)

SvSetSV

Вызывает sv_setsv, если dsv не совпадает с ssv. Может оценивать аргументы более одного раза. Не обрабатывает 'set' магию для целевого SV.

void    SvSetSV(SV* dsv, SV* ssv)

SvSetSV_nosteal

Вызывает неразрушающую версию sv_setsv, если dsv не совпадает с ssv. Может оценивать аргументы более одного раза.

void    SvSetSV_nosteal(SV* dsv, SV* ssv)

SvSHARE

Обеспечивает совместное использование sv между потоками, если соответствующий модуль загружен.

void    SvSHARE(SV* sv)

sv_string_from_errnum

Генерирует строку сообщения, описывающую ошибку ОС, и возвращает её как SV. errnum должно быть значением, которое errno могло бы принять, идентифицируя тип ошибки.

Если tgtsv не null, то строка будет записана в этот SV (перезаписывая существующее содержимое), и он будет возвращён. Если tgtsv null, то строка будет записана в новый смертный SV, который будет возвращён.

Сообщение будет взято из локали, используемой $!, и будет закодировано в SV соответствующим образом, как используется $!. Подробности этого процесса могут быть изменены в будущем. В настоящее время сообщение по умолчанию берётся из C-локали (обычно генерируя английское сообщение), и из выбранной локали, когда находится в области действия pragma use locale. Предпринимается попытка декодирования сообщения из кодировки символов локали, но оно будет декодировано либо как UTF-8, либо как ISO-8859-1. Оно всегда правильно декодируется в UTF-8 локали, обычно в ISO-8859-1 локали и никогда в других локалях.

SV всегда возвращает строку, и никакие другие биты OK не установлены. В отличие от $!, сообщение выдаётся даже для errnum нуля (означающего успех), и если нет полезного сообщения, возвращается бесполезная строка (в настоящее время пустая).

SV *    sv_string_from_errnum(int errnum, SV *tgtsv)

SvUNLOCK

Освобождает блокировку взаимного исключения для sv, если соответствующий модуль загружен.

void    SvUNLOCK(SV* sv)

Управление памятью

Копирование

Интерфейс XSUB-писателя для функции C memcpy. src — это источник, dest — это место назначения, nitems — количество элементов, а type — тип. Может завершиться ошибкой при перекрывающихся копиях. См. также "Move".

void    Copy(void* src, void* dest, int nitems, type)

КопированиеD

Аналогично Copy, но возвращает dest. Полезно для стимулирования компиляторов к оптимизации хвостовых вызовов.

void *  CopyD(void* src, void* dest, int nitems, type)

Перемещение

Интерфейс XSUB-писателя для функции C memmove. src — это источник, dest — это место назначения, nitems — количество элементов, а type — тип. Может выполнять перекрывающиеся перемещения. См. также "Copy".

void    Move(void* src, void* dest, int nitems, type)

ПеремещениеD

Аналогично Move, но возвращает dest. Полезно для стимулирования компиляторов к оптимизации хвостовых вызовов.

void *  MoveD(void* src, void* dest, int nitems, type)

Newx

Интерфейс XSUB-писателя для функции C malloc.

Память, полученная этим методом, ТОЛЬКО должна быть освобождена с помощью "Safefree".

В версии 5.9.3 функции Newx() и аналогичные заменяют более старые функции API New(), и удаляют первый параметр, x, который был вспомогательным инструментом отладки, позволяющим вызывающим функциям идентифицировать себя. Этот инструмент устарел и заменён новым параметром сборки, PERL_MEM_LOG (см. "PERL_MEM_LOG" в perlhacktips). Более старый API всё ещё доступен для использования в XS-модулях, поддерживающих более старые версии Perl.

void    Newx(void* ptr, int nitems, type)

Newxc

Интерфейс XSUB-писателя для функции C malloc с приведением типов. См. также "Newx".

Память, полученная этим методом, ТОЛЬКО должна быть освобождена с помощью "Safefree".

void    Newxc(void* ptr, int nitems, type, cast)

Newxz

Интерфейс XSUB-писателя для функции C malloc. Выделенная память обнуляется с помощью memzero. См. также "Newx".

Память, полученная этим методом, ТОЛЬКО должна быть освобождена с помощью "Safefree".

void    Newxz(void* ptr, int nitems, type)

Отравление

PoisonWith(0xEF) для отслеживания доступа к освобождённой памяти.

void    Poison(void* dest, int nitems, type)

Освобождение с отравлением

PoisonWith(0xEF) для отслеживания доступа к освобождённой памяти.

void    PoisonFree(void* dest, int nitems, type)

Отравление при создании

PoisonWith(0xAB) для отслеживания доступа к выделенной, но не инициализированной памяти.

void    PoisonNew(void* dest, int nitems, type)

Отравление значением

Заполнение памяти шаблоном байтов (повторённый байт), который, надеюсь, позволит отслеживать попытки доступа к неинициализированной памяти.

void    PoisonWith(void* dest, int nitems, type,
                   U8 byte)

Перевыделение

Интерфейс XSUB-писателя для функции C realloc.

Память, полученная этим методом, ТОЛЬКО должна быть освобождена с помощью "Safefree".

void    Renew(void* ptr, int nitems, type)

Перевыделение с приведением типов

Интерфейс XSUB-писателя для функции C realloc с приведением типов.

Память, полученная этим методом, ТОЛЬКО должна быть освобождена с помощью "Safefree".

void    Renewc(void* ptr, int nitems, type, cast)

Безопасное освобождение

Интерфейс XSUB-писателя для функции C free.

Использовать только с памятью, полученной с помощью "Newx" и аналогичных функций.

void    Safefree(void* ptr)

savepv

Версия Perl функции strdup(). Возвращает указатель на новую выделенную строку, которая является дубликатом pv. Размер строки определяется strlen(), что означает, что она может не содержать встроенных NUL символов и должна иметь заключительный NUL символ. Выделенную память для новой строки можно освободить с помощью функции Safefree().

На некоторых платформах, например, Windows, вся выделенная память, принадлежащая потоку, освобождается при завершении этого потока. Поэтому, если вам нужно этого избежать, необходимо использовать функции общей памяти, такие как "savesharedpv".

char*   savepv(const char* pv)

savepvn

Версия Perl того, что было бы strndup() (если бы это существовало). Возвращает указатель на новую выделенную строку, которая является дубликатом первых len байтов из pv, плюс заключительный NUL байт. Выделенную память для новой строки можно освободить с помощью функции Safefree().

char*   savepvn(const char* pv, I32 len)

savepvs

Аналогично savepvn, но принимает строковый литерал вместо пары строка/длина.

char*   savepvs("literal string" s)

savesharedpv

Версия savepv(), которая выделяет дублированную строку в памяти, которая является общей для потоков.

char*   savesharedpv(const char* pv)

savesharedpvn

Версия savepvn(), которая выделяет дублированную строку в памяти, общей для потоков. (С конкретным отличием, что указатель NULL недопустим).

char*   savesharedpvn(const char *const pv,
                      const STRLEN len)

savesharedpvs

Версия savepvs(), которая выделяет дублированную строку в памяти, общей для потоков.

char*   savesharedpvs("literal string" s)

savesharedsvpv

Версия savesharedpv(), которая выделяет дублированную строку в памяти, общей для потоков.

char*   savesharedsvpv(SV *sv)

savesvpv

Версия savepv()/savepvn(), которая получает дублируемую строку из переданного SV с помощью SvPV().

char*   savesvpv(SV* sv)

Копирование структуры

Это независимая от архитектуры макрокоманда для копирования одной структуры в другую.

void    StructCopy(type *src, type *dest, type)

Обнуление

Интерфейс XSUB-писателя для функции C memzero . dest — это место назначения, nitems — количество элементов, а type — тип.

void    Zero(void* dest, int nitems, type)

ОбнулениеD

Аналогично Zero, но возвращает dest. Полезно для стимулирования компиляторов к оптимизации хвостовых вызовов.

void *  ZeroD(void* dest, int nitems, type)

Дополнительные функции

dump_c_backtrace

Выводит трассировку стека вызовов C в указанный fp.

Возвращает true, если трассировка стека была получена, и false — в противном случае.

bool    dump_c_backtrace(PerlIO* fp, int max_depth,
                         int skip)

fbm_compile

Анализирует строку, чтобы создать быстрый поиск по ней с использованием fbm_instr() — алгоритма Бойера-Мура.

void    fbm_compile(SV* sv, U32 flags)

fbm_instr

Возвращает расположение SV в строке, ограниченной big и bigend (bigend) — это символ, следующий за последним символом). Возвращает NULL, если строка не найдена. sv не обязательно fbm_compiled, но тогда поиск будет менее быстрым.

char*   fbm_instr(unsigned char* big,
                  unsigned char* bigend, SV* littlestr,
                  U32 flags)

foldEQ

Возвращает true, если ведущие len байта строк s1 и s2 одинаковы, не учитывая регистр; в противном случае возвращает false. Байты верхнего и нижнего регистров ASCII соответствуют сами себе и своим аналогам в противоположном регистре. Байты вне ASCII и без регистра соответствуют только сами себе.

I32     foldEQ(const char* a, const char* b, I32 len)

foldEQ_locale

Возвращает true, если ведущие len байта строк s1 и s2 одинаковы, не учитывая регистр, в текущей локали; в противном случае возвращает false.

I32     foldEQ_locale(const char* a, const char* b,
                      I32 len)

form

Принимает шаблон форматирования в стиле sprintf и обычные (не SV) аргументы и возвращает отформатированную строку.

(char *) Perl_form(pTHX_ const char* pat, ...)

может быть использован там, где требуется строка (char *):

char * s = Perl_form("%d.%d",major,minor);

Использует единственный внутренний буфер, поэтому если вы хотите отформатировать несколько строк, вы должны явно скопировать предыдущие строки (и освободить копии, когда закончите).

char*   form(const char* pat, ...)

getcwd_sv

Заполняет sv текущим рабочим каталогом

int     getcwd_sv(SV* sv)

get_c_backtrace_dump

Возвращает SV, содержащий дамп depth кадров стека вызовов, пропуская skip вложенных. Обычно достаточно depth кадров.

Присоединенный вывод выглядит так:

... 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl ...

Поля разделены табуляцией. Первый столбец — глубина (нуль — самый вложенный не пропущенный кадр). В шестнадцатеричном представлении:смещение, шестнадцатеричное значение — местоположение счётчика команд в S_parse_body, а :смещение (может отсутствовать) указывает, насколько внутри S_parse_body находился счётчик команд.

util.c:1716 — файл исходного кода и номер строки.

/usr/bin/perl — очевидно (надеюсь).

Неизвестные — "-". К сожалению, неизвестные могут возникать довольно легко: если платформа не поддерживает извлечение информации; если в двоичном файле отсутствуют отладочные данные; если оптимизатор преобразовывал код, например, с помощью встраивания.

SV*     get_c_backtrace_dump(int max_depth, int skip)

ibcmp

Это синоним для (! foldEQ())

I32     ibcmp(const char* a, const char* b, I32 len)

ibcmp_locale

Это синоним для (! foldEQ_locale())

I32     ibcmp_locale(const char* a, const char* b,
                     I32 len)

is_safe_syscall

Проверка, что данное pv не содержит внутренних NUL символов. Если содержит, установить errno на ENOENT, по желанию вывести предупреждение и вернуть FALSE.

Возвращает TRUE, если имя безопасно.

Используется макросом IS_SAFE_SYSCALL().

bool    is_safe_syscall(const char *pv, STRLEN len,
                        const char *what,
                        const char *op_name)

memEQ

Сравнение двух буферов (которые могут содержать встроенные NUL символы), чтобы определить, равны ли они. Параметр len указывает количество байтов для сравнения. Возвращает ноль, если равны, или ненулевое значение, если не равны.

bool    memEQ(char* s1, char* s2, STRLEN len)

memNE

Сравнение двух буферов (которые могут содержать встроенные NUL символы), чтобы определить, не равны ли они. Параметр len указывает количество байтов для сравнения. Возвращает ноль, если не равны, или ненулевое значение, если равны.

bool    memNE(char* s1, char* s2, STRLEN len)

mess

Принимает шаблон форматирования в стиле sprintf и список аргументов. Используется для генерации строкового сообщения. Если сообщение не заканчивается символом новой строки, оно будет дополнено указанием текущего местоположения в коде, как описано для "mess_sv".

Обычно результирующее сообщение возвращается в новом временном SV. Во время глобального уничтожения один SV может быть общим для нескольких вызовов этой функции.

SV *    mess(const char *pat, ...)

mess_sv

Расширяет сообщение, предназначенное для пользователя, добавлением указания текущего местоположения в коде, если сообщение не кажется полным.

basemsg — начальное сообщение или объект. Если это ссылка, она будет использована как есть, и она же будет результатом этой функции. В противном случае, она используется как строка, и если она уже заканчивается новой строкой, она считается полной, и результат этой функции будет той же строкой. Если сообщение не заканчивается новой строкой, то к нему будет добавлен фрагмент, такой как at foo.pl line 37, и, возможно, другие фрагменты, указывающие текущее состояние выполнения. Результирующее сообщение будет заканчиваться точкой и новой строкой.

Обычно результирующее сообщение возвращается в новом временном SV. Во время глобального уничтожения один SV может быть общим для нескольких вызовов этой функции. Если consume истинно, то функция может (но не обязана) изменить и вернуть basemsg вместо выделения нового SV.

SV *    mess_sv(SV *basemsg, bool consume)

my_snprintf

Функциональность C-библиотеки snprintf, если доступна и соответствует стандартам (использует vsnprintf, на самом деле). Однако, если vsnprintf недоступна, к сожалению, будет использоваться небезопасная функция vsprintf, которая может переполнить буфер (есть проверка на переполнение, но она может быть слишком поздней). Рассмотрите возможность использования sv_vcatpvf вместо неё или получение vsnprintf.

int     my_snprintf(char *buffer, const Size_t len,
                    const char *format, ...)

my_strlcat

Функция C-библиотеки strlcat, если доступна, или реализация её в Perl. Работает со строками C, завершенными нулём.

my_strlcat() добавляет строку src в конец dst. Она добавит не более size - strlen(dst) - 1 символов. Затем она завершит её нулём, если size не равно 0, или если исходная строка dst была длиннее size (на практике это не должно произойти, поскольку это означает, что либо size неправильно, либо dst не является правильной строкой, завершённой нулём).

Обратите внимание, что size — это полный размер целевого буфера, и результат гарантированно завершён нулём, если есть место. Обратите внимание, что место для NUL должно быть включено в size.

Значение возврата — общая длина, которую dst имела бы, если size достаточно велика. Таким образом, это начальная длина dst плюс длина src. Если size меньше возвращаемого значения, избыток не был добавлен.

Size_t  my_strlcat(char *dst, const char *src,
                   Size_t size)

my_strlcpy

Функция C-библиотеки strlcpy, если доступна, или реализация её в Perl. Работает со строками C, завершёнными нулём.

my_strlcpy() копирует не более size - 1 символов из строки src в dst, завершая результат нулём, если size не равно 0.

Значение возврата — общая длина, которую src имела бы, если бы копирование прошло полностью успешно. Если оно больше size, избыток не был скопирован.

Size_t  my_strlcpy(char *dst, const char *src,
                   Size_t size)

my_strnlen

Функция C-библиотеки strnlen, если доступна, или её реализация в Perl.

my_strnlen() вычисляет длину строки до maxlen символов. Она никогда не пытается обратиться к более чем maxlen символам, что делает её подходящей для использования со строками, не гарантированно завершёнными нулём.

Size_t  my_strnlen(const char *str, Size_t maxlen)

my_vsnprintf

Функциональность C-библиотеки vsnprintf, если доступна и соответствует стандартам. Однако, если vsnprintf недоступна, к сожалению, будет использоваться небезопасная функция vsprintf, которая может переполнить буфер (есть проверка на переполнение, но она может быть слишком поздней). Рассмотрите возможность использования sv_vcatpvf вместо неё или получение vsnprintf.

int     my_vsnprintf(char *buffer, const Size_t len,
                     const char *format, va_list ap)

ninstr

Поиск первого (самого левого) вхождения последовательности байтов в другой последовательности. Это версия Perl функции strstr(), расширенная для обработки произвольных последовательностей, потенциально содержащих встроенные NUL символы (NUL — то, что означает начальное n в имени функции; некоторые системы имеют эквивалент, memmem(), но с несколько другим API).

Другой способ понять эту функцию — это поиск иглы в стоге сена. big указывает на первый байт в стоге сена. big_end указывает на байт, следующий за последним байтом в стоге сена. little указывает на первый байт в игле. little_end указывает на байт, следующий за последним байтом в игле. Все параметры должны быть ненулевыми.

Функция возвращает NULL, если вхождение little в big отсутствует. Если little — это пустая строка, возвращается big.

Поскольку эта функция работает на уровне байтов, и из-за свойств UTF-8 (или UTF-EBCDIC), она будет работать корректно, если и игла, и стог сена — это строки с одинаковой UTF-8ностью, но не в случае, если UTF-8ность отличается.

char *  ninstr(char * big, char * bigend, char * little,
               char * little_end)

PERL_SYS_INIT

Обеспечивает настройку среды выполнения C, специфичную для системы, необходимую для запуска интерпретаторов Perl. Этот вызов должен быть выполнен только один раз, до создания каких-либо интерпретаторов Perl.

void    PERL_SYS_INIT(int *argc, char*** argv)

PERL_SYS_INIT3

Обеспечивает настройку среды выполнения C, специфичную для системы, необходимую для запуска интерпретаторов Perl. Вызывать следует только один раз, перед созданием любых интерпретаторов Perl.

void    PERL_SYS_INIT3(int *argc, char*** argv,
                       char*** env)

PERL_SYS_TERM

Обеспечивает очистку среды выполнения C, специфичную для системы, после завершения работы интерпретаторов Perl. Вызывать следует только один раз, после освобождения всех оставшихся интерпретаторов Perl.

void    PERL_SYS_TERM()

quadmath_format_needed

quadmath_format_needed() возвращает true, если строка format содержит по крайней мере один спецификатор формата %[efgaEFGA], не имеющий префикса Q, иначе возвращает false.

Обнаружение спецификатора формата не является полным определением синтаксиса printf, но оно должно обрабатывать большинство распространенных случаев.

Если возвращается true, эти аргументы должны теоретически обрабатываться с помощью quadmath_snprintf(), но в случае наличия более одного такого спецификатора формата (см. "quadmath_format_single"), и если есть что-либо еще помимо этого (даже просто один байт), они не могут обрабатываться, потому что quadmath_snprintf() очень строг, принимая только один спецификатор формата и ничего более. В этом случае код, вероятно, должен завершиться ошибкой.

bool    quadmath_format_needed(const char* format)

quadmath_format_single

quadmath_snprintf() очень строг в отношении своей строки format и завершится ошибкой, вернув -1, если формат некорректен. Он принимает ровно один спецификатор формата.

quadmath_format_single() проверяет, что предполагаемый одиночный спецификатор выглядит разумно: начинается с %, содержит только один %, заканчивается на [efgaEFGA], и имеет Q перед ним. Это не полная проверка синтаксиса printf, а только основы.

Возвращает формат, если он корректен, NULL, если нет.

quadmath_format_single() может и фактически подставит отсутствующий Q, если необходимо. В этом случае он вернёт изменённую копию формата, которую вызывающий код обязан освободить.

См. также "quadmath_format_needed".

const char* quadmath_format_single(const char* format)

READ_XDIGIT

Возвращает значение шестнадцатеричной цифры в ASCII-диапазоне и продвигает указатель строки. Поведение определено только при условии, что isXDIGIT(*str) истинно.

U8      READ_XDIGIT(char str*)

rninstr

Аналогично "ninstr", но вместо этого находит последнее (крайнее справа) вхождение последовательности байтов в другой последовательности, возвращая NULL, если такое вхождение отсутствует.

char *  rninstr(char * big, char * bigend,
                char * little, char * little_end)

strEQ

Сравнивает две строки, завершающиеся NUL, на предмет равенства. Возвращает true или false.

bool    strEQ(char* s1, char* s2)

strGE

Сравнивает две строки, завершающиеся NUL, на предмет того, больше ли первая, s1, чем или равна второй, s2. Возвращает true или false.

bool    strGE(char* s1, char* s2)

strGT

Сравнивает две строки, завершающиеся NUL, на предмет того, больше ли первая, s1, чем вторая, s2. Возвращает true или false.

bool    strGT(char* s1, char* s2)

strLE

Сравнивает две строки, завершающиеся NUL, на предмет того, меньше ли первая, s1, чем или равна второй, s2. Возвращает true или false.

bool    strLE(char* s1, char* s2)

strLT

Сравнивает две строки, завершающиеся NUL, на предмет того, меньше ли первая, s1, чем вторая, s2. Возвращает true или false.

bool    strLT(char* s1, char* s2)

strNE

Сравнивает две строки, завершающиеся NUL, на предмет неравенства. Возвращает true или false.

bool    strNE(char* s1, char* s2)

strnEQ

Сравнивает две строки, завершающиеся NUL, на предмет равенства. Параметр len указывает количество байтов для сравнения. Возвращает true или false. (Обёртка для strncmp).

bool    strnEQ(char* s1, char* s2, STRLEN len)

strnNE

Сравнивает две строки, завершающиеся NUL, на предмет неравенства. Параметр len указывает количество байтов для сравнения. Возвращает true или false. (Обёртка для strncmp).

bool    strnNE(char* s1, char* s2, STRLEN len)

sv_destroyable

Псевдофункция, которая сообщает, что объект может быть уничтожен, когда модуль совместного использования отсутствует. Она игнорирует свой единственный аргумент SV и возвращает 'true'. Существует, чтобы избежать проверки на наличие указателя на функцию NULL и потому, что потенциально может выдавать предупреждение при определённых уровнях строгости.

bool    sv_destroyable(SV *sv)

sv_nosharing

Псевдофункция, которая "совместно использует" SV, когда модуль совместного использования отсутствует. Или "блокирует" его. Или "разблокирует" его. Другими словами, игнорирует свой единственный аргумент SV. Существует, чтобы избежать проверки на наличие указателя на функцию NULL и потому, что потенциально может выдавать предупреждение при определённых уровнях строгости.

void    sv_nosharing(SV *sv)

vmess

pat и args — это шаблон формата в стиле sprintf и переданный список аргументов соответственно. Они используются для создания строкового сообщения. Если сообщение не заканчивается символом новой строки, оно будет дополнено указанием текущей позиции в коде, как описано для "mess_sv".

Как правило, результирующее сообщение возвращается в новом временном SV. Во время глобального уничтожения один SV может использоваться совместно для нескольких вызовов этой функции.

SV *    vmess(const char *pat, va_list *args)

Функции MRO

Эти функции относятся к порядку разрешения методов для классов Perl

mro_get_linear_isa

Возвращает линейную упорядоченность MRO для данного хранилища. По умолчанию, это будет то, что возвращает mro_get_linear_isa_dfs, если для хранилища не используется какой-либо другой порядок MRO. Возвращаемое значение — постоянный массив AV*.

Вы несете ответственность за SvREFCNT_inc() возвращаемого значения, если вы планируете сохранить его где-либо полупостоянно (иначе он может быть удалён из-под вас в следующий момент, когда кеш станет недействительным).

AV*     mro_get_linear_isa(HV* stash)

mro_method_changed_in

Делает кеширование методов недействительными для всех дочерних классов данного хранилища, чтобы они могли заметить изменения в нём.

В идеале, все экземпляры PL_sub_generation++ в исходном коде Perl вне mro.c должны быть заменены вызовами этой функции.

Perl автоматически обрабатывает большинство распространённых способов переопределения метода. Однако, есть несколько способов изменить метод в хранилище, не затронув код кеширования, в этом случае вам нужно вызвать этот метод позже:

1) Прямое управление записями хранилища HV из кода XS.

2) Присвоение ссылки на неизменяемый скалярный констант в запись хранилища, чтобы создать постоянную подпрограмму (как это делает constant.pm).

Эта же функция доступна из чистого Perl через mro::method_changed_in(classname).

void    mro_method_changed_in(HV* stash)

mro_register

Регистрирует пользовательский плагин MRO. Подробнее см. perlmroapi.

void    mro_register(const struct mro_alg *mro)

Функции Multicall

dMULTICALL

Объявляет локальные переменные для вызова multicall. См. "ЛЕГКИЕ ОБРАБОТЧИКИ СОБЫТИЙ" в perlcall.

dMULTICALL;

MULTICALL

Создаёт лёгкий обработчик событий. См. "ЛЕГКИЕ ОБРАБОТЧИКИ СОБЫТИЙ" в perlcall.

MULTICALL;

POP_MULTICALL

Закрывающая скобка для лёгкого обработчика событий. См. "ЛЕГКИЕ ОБРАБОТЧИКИ СОБЫТИЙ" в perlcall.

POP_MULTICALL;

PUSH_MULTICALL

Открывающая скобка для лёгкого обработчика событий. См. "ЛЕГКИЕ ОБРАБОТЧИКИ СОБЫТИЙ" в perlcall.

PUSH_MULTICALL;

Функции чисел

grok_bin

преобразует строку, представляющую двоичное число, в числовой вид.

На входе start и *len задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или при первом недопустимом символе. Если PERL_SCAN_SILENT_ILLDIGIT не установлен в *flags, встреча с недопустимым символом также вызовет предупреждение. На выходе *len устанавливается в длину просканированной строки, а *flags задаёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_bin возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX во флагах вывода и записывает значение в *result (или значение отбрасывается, если result равно NULL).

Двоичное число может быть необязательно префиксным "0b" или "b", если PERL_SCAN_DISALLOW_PREFIX не установлен в *flags на входе. Если PERL_SCAN_ALLOW_UNDERSCORES установлен в *flags, двоичное число может использовать символы "_" для разделения цифр.

UV      grok_bin(const char* start, STRLEN* len_p,
                 I32* flags, NV *result)

grok_hex

преобразует строку, представляющую шестнадцатеричное число, в числовой вид.

На входе start и *len_p задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или при первом недопустимом символе. Если PERL_SCAN_SILENT_ILLDIGIT не установлен в *flags, встреча с недопустимым символом также вызовет предупреждение. На выходе *len устанавливается в длину просканированной строки, а *flags задаёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_hex возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX во флагах вывода и записывает значение в *result (или значение отбрасывается, если result равно NULL).

Шестнадцатеричное число может быть необязательно префиксным "0x" или "x", если PERL_SCAN_DISALLOW_PREFIX не установлен в *flags на входе. Если PERL_SCAN_ALLOW_UNDERSCORES установлен в *flags, шестнадцатеричное число может использовать символы "_" для разделения цифр.

UV      grok_hex(const char* start, STRLEN* len_p,
                 I32* flags, NV *result)

grok_infnan

Помощник для grok_number(), принимает различные способы написания "бесконечность" или "не число" и возвращает одно из следующих сочетаний флагов:

IS_NUMBER_INFINITY
IS_NUMBER_NAN
IS_NUMBER_INFINITY | IS_NUMBER_NEG
IS_NUMBER_NAN | IS_NUMBER_NEG
0

возможно |-ed с IS_NUMBER_TRAILING.

Если распознана бесконечность или не число, *sp укажет на байт, следующий за концом распознанной строки. Если распознавание не удалось, возвращается ноль, и *sp не сместится.

int     grok_infnan(const char** sp, const char *send)

grok_number

Идентично grok_number_flags() с flags установленным в ноль.

int     grok_number(const char *pv, STRLEN len,
                    UV *valuep)

grok_number_flags

Распознавание (или не распознавание) числа. Тип числа возвращается (0, если не распознано), в противном случае это битовое ИЛИ сочетание IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (определены в perl.h).

Если значение числа помещается в UV, оно возвращается в *valuep. IS_NUMBER_IN_UV будет установлено, чтобы указать, что *valuep является допустимым, IS_NUMBER_IN_UV никогда не будет установлено, если *valuep не является допустимым, но *valuep может быть назначено в процессе, даже если IS_NUMBER_IN_UV не установлено на выходе. Если valuep равно NULL, IS_NUMBER_IN_UV будет установлено для тех же случаев, что и когда valuep не равно NULL, но никакого фактического назначения (или SEGV) не произойдёт.

IS_NUMBER_NOT_INT будет установлено с IS_NUMBER_IN_UV, если были замечены десятичные разделители (в этом случае *valuep даёт истинное значение, усеченное до целого числа), и IS_NUMBER_NEG, если число отрицательное (в этом случае *valuep содержит абсолютное значение). IS_NUMBER_IN_UV не устанавливается, если использовалась нотация е или число больше UV.

flags разрешает только PERL_SCAN_TRAILING, что позволяет иметь тексты, не являющиеся числами, в конце, при этом успешном вызове grok, устанавливая IS_NUMBER_TRAILING в результате.

int     grok_number_flags(const char *pv, STRLEN len,
                          UV *valuep, U32 flags)

grok_numeric_radix

Сканирование и пропуск числового десятичного разделителя (radix).

bool    grok_numeric_radix(const char **sp,
                           const char *send)

grok_oct

преобразует строку, представляющую восьмеричное число, в числовой вид.

На входе start и *len задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или при первом недопустимом символе. Если PERL_SCAN_SILENT_ILLDIGIT не установлен в *flags, встреча с 8 или 9 также вызовет предупреждение. На выходе *len устанавливается в длину просканированной строки, а *flags задаёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_oct возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX во флагах вывода и записывает значение в *result (или значение отбрасывается, если result равно NULL).

Если PERL_SCAN_ALLOW_UNDERSCORES установлен в *flags, восьмеричное число может использовать символы "_" для разделения цифр.

UV      grok_oct(const char* start, STRLEN* len_p,
                 I32* flags, NV *result)

isinfnan

Perl_isinfnan() — это вспомогательная функция, которая возвращает true, если аргумент NV является бесконечностью или NaN, и false в противном случае. Для более подробного тестирования используйте Perl_isinf() и Perl_isnan().

Это также логическое отрицание Perl_isfinite().

bool    isinfnan(NV nv)

my_strtod

Эта функция эквивалентна функции libc strtod(), и доступна даже на платформах, где нет обычной strtod(). Её возвращаемое значение — наилучшая доступная точность, зависящая от возможностей платформы и опций Configure.

Она правильно обрабатывает символ разделителя десятичных знаков локали, то есть ожидает точку, за исключением случаев, когда она вызвана из области use locale, в этом случае символом разделителя десятичных знаков должна быть заданная текущей локалью.

Вместо неё можно использовать синоним Strod().

NV      my_strtod(const char * const s, char ** e)

Perl_signbit

ПРИМЕЧАНИЕ: эта функция экспериментальна и может быть изменена или удалена без предварительного уведомления.

Возвращает ненулевое целое число, если бит знака в NV установлен, и 0, если нет.

Если Configure обнаруживает, что эта система имеет signbit(), которая будет работать с нашими NV, тогда мы просто используем её через #define в perl.h. В противном случае используется данная реализация. Основное назначение этой функции — отслеживание -0.0.

Configure Примечания: Эта функция называется 'Perl_signbit' вместо обычной 'signbit', потому что легко представить систему, имеющую функцию или макрос signbit(), которая не работает с нашими конкретными NV. Мы не должны просто переопределять #define signbit как Perl_signbit и ожидать, что стандартные системные заголовки будут довольны. Кроме того, это функция без контекста (без pTHX_) потому что Perl_signbit() обычно переопределяется в perl.h как простая макрокоманда для системной signbit(). Пользователи должны всегда вызывать Perl_signbit().

int     Perl_signbit(NV f)

scan_bin

Для обратной совместимости. Используйте grok_bin вместо этого.

NV      scan_bin(const char* start, STRLEN len,
                 STRLEN* retlen)

scan_hex

Для обратной совместимости. Используйте grok_hex вместо этого.

NV      scan_hex(const char* start, STRLEN len,
                 STRLEN* retlen)

scan_oct

Для обратной совместимости. Используйте grok_oct вместо этого.

NV      scan_oct(const char* start, STRLEN len,
                 STRLEN* retlen)

Функции устаревшей обратной совместимости

Некоторые из них также устарели. Вы можете исключить их из компилируемого Perl, добавив эту опцию в Configure: -Accflags='-DNO_MATHOMS'

custom_op_desc

Возвращает описание заданного пользовательского оператора. Раньше использовался макросом OP_DESC, но больше не используется: он сохранен только для совместимости и не должен использоваться.

const char * custom_op_desc(const OP *o)

custom_op_name

Возвращает имя заданного пользовательского оператора. Раньше использовался макросом OP_NAME, но больше не используется: он сохранен только для совместимости и не должен использоваться.

const char * custom_op_name(const OP *o)

gv_fetchmethod

См. "gv_fetchmethod_autoload".

GV*     gv_fetchmethod(HV* stash, const char* name)

is_utf8_char

УСТАНОВЛЕНО! Планируется удалить эту функцию из будущей версии Perl. Не используйте её в новом коде; удалите из существующего кода.

Проверяет, начинается ли заданное произвольное количество байтов с допустимого символа UTF-8. Обратите внимание, что ИНВАРИАНТНЫЙ (т.е. ASCII на не-EBCDIC машинах) символ является допустимым символом UTF-8. Фактическое количество байтов в символе UTF-8 будет возвращено, если он корректен, в противном случае 0.

Эта функция устарела из-за возможности того, что некорректный ввод может привести к чтению за пределами буфера ввода. Используйте "isUTF8_CHAR" вместо неё.

STRLEN  is_utf8_char(const U8 *s)

is_utf8_char_buf

Это идентично макросу "isUTF8_CHAR".

STRLEN  is_utf8_char_buf(const U8 *buf,
                         const U8 *buf_end)

pack_cat

Двигатель, реализующий функцию pack() Perl. Примечание: параметры next_in_list и flags не используются. Этот вызов не следует использовать; используйте packlist вместо него.

void    pack_cat(SV *cat, const char *pat,
                 const char *patend, SV **beglist,
                 SV **endlist, SV ***next_in_list,
                 U32 flags)

pad_compname_type

Определяет тип лексической переменной в позиции po в текущем компилируемом блоке. Если переменная типизирована, возвращается стейшн класса, к которому она типизирована. В противном случае возвращается NULL.

HV *    pad_compname_type(PADOFFSET po)

sv_2pvbyte_nolen

Возвращает указатель на байтовое представление SV. Может привести к понижению SV с UTF-8 как побочному эффекту.

Обычно вызывается через макрос SvPVbyte_nolen.

char*   sv_2pvbyte_nolen(SV* sv)

sv_2pvutf8_nolen

Возвращает указатель на UTF-8-представление SV. Может привести к повышению SV до UTF-8 как побочному эффекту.

Обычно вызывается через макрос SvPVutf8_nolen.

char*   sv_2pvutf8_nolen(SV* sv)

sv_2pv_nolen

Подобно sv_2pv(), но не возвращает длину тоже. Вы обычно должны использовать оберточку макроса SvPV_nolen(sv) вместо этого.

char*   sv_2pv_nolen(SV* sv)

sv_catpvn_mg

Подобно sv_catpvn, но также обрабатывает магию 'set'.

void    sv_catpvn_mg(SV *sv, const char *ptr,
                     STRLEN len)

sv_catsv_mg

Подобно sv_catsv, но также обрабатывает магию 'set'.

void    sv_catsv_mg(SV *dsv, SV *ssv)

sv_force_normal

Отменяет различные виды подделок на SV: если PV — это общая строка, создаёт её частную копию; если мы являемся ссылкой, прекращаем ссылаться; если мы — глобальный объект, понижаем до xpvmg. См. также "sv_force_normal_flags".

void    sv_force_normal(SV *sv)

sv_iv

Внутренняя реализация макроса SvIVx для компиляторов, которые не справляются со сложными выражениями макросов. Всегда используйте макрос вместо этого.

IV      sv_iv(SV* sv)

sv_nolocking

Выполняющая роль процедура, которая "блокирует" SV, когда модуль блокировки отсутствует. Существует, чтобы избежать проверки на указатель функции NULL и потому, что она потенциально может выдать предупреждение при определённом уровне строгости.

"Заменено" на sv_nosharing().

void    sv_nolocking(SV *sv)

sv_nounlocking

Выполняющая роль процедура, которая "разблокирует" SV, когда модуль блокировки отсутствует. Существует, чтобы избежать проверки на указатель функции NULL и потому, что она потенциально может выдать предупреждение при определённом уровне строгости.

"Заменено" на sv_nosharing().

void    sv_nounlocking(SV *sv)

sv_nv

Внутренняя реализация макроса SvNVx для компиляторов, которые не справляются со сложными выражениями макросов. Всегда используйте макрос вместо этого.

NV      sv_nv(SV* sv)

sv_pv

Используйте макрос SvPV_nolen вместо этого.

char*   sv_pv(SV *sv)

sv_pvbyte

Используйте SvPVbyte_nolen вместо этого.

char*   sv_pvbyte(SV *sv)

sv_pvbyten

Внутренняя реализация макроса SvPVbyte для компиляторов, которые не справляются со сложными выражениями макросов. Всегда используйте макрос вместо этого.

char*   sv_pvbyten(SV *sv, STRLEN *lp)

sv_pvn

Внутренняя реализация макроса SvPV для компиляторов, которые не справляются со сложными выражениями макросов. Всегда используйте макрос вместо этого.

char*   sv_pvn(SV *sv, STRLEN *lp)

sv_pvutf8

Используйте макрос SvPVutf8_nolen вместо этого.

char*   sv_pvutf8(SV *sv)

sv_pvutf8n

Внутренняя реализация макроса SvPVutf8 для компиляторов, которые не справляются со сложными выражениями макросов. Всегда используйте макрос вместо этого.

char*   sv_pvutf8n(SV *sv, STRLEN *lp)

sv_taint

Пометить SV. Используйте SvTAINTED_on вместо этого.

void    sv_taint(SV* sv)

sv_unref

Сбрасывает состояние RV SV и уменьшает счётчик ссылок на то, на что ссылался RV. Это почти можно рассматривать как обращение newSVrv. Это sv_unref_flags с flag равным нулю. См. "SvROK_off".

void    sv_unref(SV* sv)

sv_usepvn

Указывает SV использовать ptr для поиска своего строкового значения. Реализовано вызовом sv_usepvn_flags с flags равным 0, поэтому не обрабатывает магию 'set'. См. "sv_usepvn_flags".

void    sv_usepvn(SV* sv, char* ptr, STRLEN len)

sv_usepvn_mg

Подобно sv_usepvn, но также обрабатывает магию 'set'.

void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)

sv_uv

Внутренняя реализация макроса SvUVx для компиляторов, которые не справляются со сложными выражениями макросов. Всегда используйте макрос вместо этого.

UV      sv_uv(SV* sv)

unpack_str

Двигатель, реализующий функцию unpack() Perl. Примечание: параметры strbeg, new_s и ocnt не используются. Не следует использовать этот вызов, используйте unpackstring вместо этого.

SSize_t unpack_str(const char *pat, const char *patend,
                   const char *s, const char *strbeg,
                   const char *strend, char **new_s,
                   I32 ocnt, U32 flags)

utf8_to_uvuni

Возвращает код Unicode первого символа в строке s, которая предполагается в кодировке UTF-8; retlen будет установлено равным длине этого символа в байтах.

Обнаружены некоторые, но не все, некорректности UTF-8, и, фактически, некоторые некорректные данные могут привести к чтению за пределами буфера ввода, что является одной из причин устаревания этой функции. Другая причина в том, что в крайне ограниченных случаях код Unicode по сравнению с кодом кодировки должен быть для вас любого интереса. Смотрите "utf8_to_uvuni_buf" для альтернатив.

Если s указывает на одну из обнаруженных некорректных последовательностей, и предупреждения UTF8 включены, возвращается ноль, а *retlen устанавливается (если retlen не указывает на NULL) в -1. Если эти предупреждения выключены, вычисляемое значение, если оно определено (или СИМВОЛ ЗАМЕЩЕНИЯ Юникода, если нет), возвращается молча, и *retlen устанавливается (если retlen не является NULL), так что (s + *retlen) является следующей возможной позицией в s, которая могла бы начать не некорректный символ. Смотрите "utf8n_to_uvchr" для подробностей о том, когда возвращается СИМВОЛ ЗАМЕЩЕНИЯ Юникода.

UV      utf8_to_uvuni(const U8 *s, STRLEN *retlen)

Дерево обработки опций

newASSIGNOP

Создаёт, проверяет и возвращает оператор присваивания. left и right предоставляют параметры присваивания; они используются этой функцией и становятся частью построенного дерева операторов.

Если optype равно OP_ANDASSIGN, OP_ORASSIGN, или OP_DORASSIGN, то строится соответствующее условное дерево операторов. Если optype является кодом двоичного оператора, например, OP_BIT_OR, то строится оператор, выполняющий двоичную операцию и присваивающий результат левому аргументу. В любом случае, если optype не равно нулю, то flags не оказывает никакого влияния.

Если optype равно нулю, то строится обычное присваивание скаляра или списка. Тип присваивания определяется автоматически. flags задаёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 или 2 будет установлен автоматически, как требуется.

OP *    newASSIGNOP(I32 flags, OP *left, I32 optype,
                    OP *right)

newBINOP

Создаёт, проверяет и возвращает оператор любого типа двоичного оператора. type — это код оператора. flags задаёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 или 2 будет установлен автоматически, как требуется. first и last предоставляют до двух операторов, которые будут непосредственными дочерними операторами двоичного оператора; они используются этой функцией и становятся частью построенного дерева операторов.

OP *    newBINOP(I32 type, I32 flags, OP *first,
                 OP *last)

newCONDOP

Создаёт, проверяет и возвращает оператор условного выражения (cond_expr) . flags задаёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 будет установлен автоматически. first предоставляет выражение, выбирающее между двумя ветвями, а trueop и falseop предоставляют эти ветви; они используются этой функцией и становятся частью построенного дерева операторов.

OP *    newCONDOP(I32 flags, OP *first, OP *trueop,
                  OP *falseop)

newDEFSVOP

Создаёт и возвращает оператор для доступа к $_.

OP *    newDEFSVOP()

newFOROP

Создаёт, проверяет и возвращает дерево операторов, представляющее цикл foreach (итерация по списку значений). Это цикл с объёмной структурой, которая позволяет выходить из цикла с помощью last и аналогичных конструкций.

sv необязательно предоставляет переменную, которая будет алиасирована с каждым элементом поочерёдно; если null, она по умолчанию $_. expr предоставляет список значений, по которым следует итерироваться. block предоставляет основной цикл, а cont необязательно предоставляет блок continue, который работает как вторая половина тела. Все эти входные данные дерева операторов потребляются этой функцией и становятся частью построенного дерева операторов.

flags задаёт восемь битов op_flags для оператора leaveloop и, сдвинутые влево на восемь битов, восемь битов op_private для оператора leaveloop, за исключением того, что (в обоих случаях) некоторые биты будут установлены автоматически.

OP *    newFOROP(I32 flags, OP *sv, OP *expr, OP *block,
                 OP *cont)

newGIVENOP

Создаёт, проверяет и возвращает дерево операторов, выражающее блок given. cond предоставляет выражение, значение которого $_ будет алиасировано локально, а block предоставляет тело конструкции given; они используются этой функцией и становятся частью построенного дерева операторов. defsv_off должно быть равно нулю (используется для идентификации слота заполнения лексического $_).

OP *    newGIVENOP(OP *cond, OP *block,
                   PADOFFSET defsv_off)

newGVOP

Создаёт, проверяет и возвращает оператор любого типа, который включает встроенную ссылку на GV. type — это код оператора. flags задаёт восемь битов op_flags. gv идентифицирует GV, на который должен ссылаться оператор; вызов этой функции не передаёт права собственности на любую ссылку на него.

OP *    newGVOP(I32 type, I32 flags, GV *gv)

newLISTOP

Создаёт, проверяет и возвращает оператор любого типа списка. type — это код оператора. flags задаёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, если необходимо. first и last предоставляют до двух операторов, которые будут непосредственными дочерними операторами оператора списка; они потребляются этой функцией и становятся частью построенного дерева операторов.

Для большинства операторов списка функция проверки ожидает, что все операторы-потомки уже присутствуют, поэтому вызов newLISTOP(OP_JOIN, ...) (например) не подходит. В этом случае вы хотите создать оператор типа OP_LIST, добавить к нему дополнительные потомки, а затем вызвать "op_convert_list". Дополнительная информация в "op_convert_list".

OP *    newLISTOP(I32 type, I32 flags, OP *first,
                  OP *last)

newLOGOP

Создаёт, проверяет и возвращает логический (управляющий потоком) оператор. type — это код оператора. flags задаёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 будет установлен автоматически. first предоставляет выражение, управляющее потоком, а other предоставляет побочную (альтернативную) цепочку операторов; они потребляются этой функцией и становятся частью построенного дерева операторов.

OP *    newLOGOP(I32 type, I32 flags, OP *first,
                 OP *other)

newLOOPEX

Создаёт, проверяет и возвращает оператор выхода из цикла (например, goto или last). type — это код оператора. label предоставляет параметр, определяющий цель оператора; он потребляется этой функцией и становится частью построенного дерева операторов.

OP *    newLOOPEX(I32 type, OP *label)

newLOOPOP

Создаёт, проверяет и возвращает дерево операторов, выражающее цикл. Это только цикл в потоке управления через дерево операторов; он не имеет тяжёлой структуры цикла, которая позволяет выходить из цикла с помощью last и аналогичных конструкций. flags задаёт восемь битов op_flags для оператора верхнего уровня, за исключением того, что некоторые биты будут установлены автоматически, как требуется. expr предоставляет выражение, управляющее итерацией цикла, а block предоставляет тело цикла; они потребляются этой функцией и становятся частью построенного дерева операторов. debuggable в настоящее время не используется и всегда должно быть равно 1.

OP *    newLOOPOP(I32 flags, I32 debuggable, OP *expr,
                  OP *block)

newMETHOP

Создаёт, проверяет и возвращает оператор типа метода с именем метода, вычисляемым во время выполнения. type — это код оператора. flags задаёт восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 будет установлен автоматически. dynamic_meth предоставляет оператор, который вычисляет имя метода; он потребляется этой функцией и становится частью построенного дерева операторов. Поддерживаемые типы операторов: OP_METHOD.

OP *    newMETHOP(I32 type, I32 flags, OP *first)

newMETHOP_named

Создаёт, проверяет и возвращает оператор типа метода с постоянным именем метода. type — это код оператора. flags задаёт восемь битов op_flags, а, сдвинутое влево на восемь битов, восемь битов op_private. const_meth предоставляет постоянное имя метода; это должна быть общая строка COW. Поддерживаемые типы операторов: OP_METHOD_NAMED.

OP *    newMETHOP_named(I32 type, I32 flags,
                        SV *const_meth)

newNULLLIST

Создаёт, проверяет и возвращает новый оператор stub, который представляет пустое выражение списка.

OP *    newNULLLIST()

newOP

Создаёт, проверяет и возвращает оператор любого базового типа (любой тип, у которого нет дополнительных полей). type — это код оператора. flags задаёт восемь битов op_flags, а, сдвинутое влево на восемь битов, восемь битов op_private.

OP *    newOP(I32 type, I32 flags)

newPADOP

Создаёт, проверяет и возвращает оператор любого типа, который включает ссылку на элемент блока заполнения. type — это код оператора. flags задаёт восемь битов op_flags. Слот заполнения автоматически выделяется и заполняется sv; эта функция принимает права собственности на одну ссылку на него.

Эта функция существует только если Perl был скомпилирован с использованием ithreads.

OP *    newPADOP(I32 type, I32 flags, SV *sv)

newPMOP

Создаёт, проверяет и возвращает оператор любого типа сопоставления с образцом. type — это код оператора. flags задаёт восемь битов op_flags и, сдвинутые влево на восемь битов, восемь битов op_private.

OP *    newPMOP(I32 type, I32 flags)

newPVOP

Создаёт, проверяет и возвращает оператор любого типа, который включает встроенный указатель уровня C (PV). type — это код оператора. flags задаёт восемь битов op_flags. pv предоставляет указатель уровня C. В зависимости от типа оператора, память, на которую ссылается pv, может быть освобождена при уничтожении оператора. Если оператор является оператором освобождения, pv должен был быть выделен с использованием PerlMemShared_malloc.

OP *    newPVOP(I32 type, I32 flags, char *pv)

newRANGE

Создаёт и возвращает оператор range, с подчиненными операторами flip и flop. flags задаёт восемь битов op_flags для оператора flip и, сдвинутые влево на восемь битов, восемь битов op_private для операторов flip и range, за исключением того, что бит со значением 1 будет установлен автоматически. left и right предоставляют выражения, контролирующие конечные точки диапазона; они потребляются этой функцией и становятся частью построенного дерева операторов.

OP *    newRANGE(I32 flags, OP *left, OP *right)

newSLICEOP

Создаёт, проверяет и возвращает операцию lslice (срез списка). flags предоставляет восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутые влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 или 2 устанавливается автоматически, как требуется. listval и subscript предоставляют параметры среза; они потребляются этой функцией и становятся частью построенного дерева операций.

OP *    newSLICEOP(I32 flags, OP *subscript,
                   OP *listval)

newSTATEOP

Создаёт операцию состояния (COP). Операция состояния обычно является операцией nextstate, но будет операцией dbstate при включённом режиме отладки для текущего компилируемого кода. Операция состояния заполняется из PL_curcop (или PL_compiling). Если label не равно null, оно предоставляет имя метки для прикрепления к операции состояния; эта функция берёт на себя управление памятью, на которую указывает label, и освободит её. flags предоставляет восемь битов op_flags для операции состояния.

Если o равно null, операция состояния возвращается. В противном случае операция состояния объединяется с o в операцию списка lineseq, которая и возвращается. o потребляется этой функцией и становится частью возвращаемого дерева операций.

OP *    newSTATEOP(I32 flags, char *label, OP *o)

newSVOP

Создаёт, проверяет и возвращает операцию любого типа, которая включает встроенный SV. type — это код операции. flags предоставляет восемь битов op_flags. sv предоставляет SV для встраивания в операцию; эта функция берёт на себя управление одной ссылкой на него.

OP *    newSVOP(I32 type, I32 flags, SV *sv)

newUNOP

Создаёт, проверяет и возвращает операцию любого унарного типа. type — это код операции. flags предоставляет восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически при необходимости, и, сдвинутые влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 устанавливается автоматически. first предоставляет необязательную операцию, которая будет прямым потомком унарной операции; она потребляется этой функцией и становится частью построенного дерева операций.

OP *    newUNOP(I32 type, I32 flags, OP *first)

newUNOP_AUX

Аналогично newUNOP, но создаёт структуру UNOP_AUX, с op_aux инициализированной как aux

OP*     newUNOP_AUX(I32 type, I32 flags, OP* first,
                    UNOP_AUX_item *aux)

newWHENOP

Создаёт, проверяет и возвращает дерево операций, выражающее блок when. cond предоставляет выражение проверки, а block предоставляет блок, который будет выполнен, если проверка вернёт true; они потребляются этой функцией и становятся частью построенного дерева операций. cond будет интерпретировано DWIM-образом, часто как сравнение с $_, и может быть null для создания блока default.

OP *    newWHENOP(OP *cond, OP *block)

newWHILEOP

Создаёт, проверяет и возвращает дерево операций, выражающее цикл while. Это цикл высокой сложности, со структурой, позволяющей выйти из цикла с помощью last и тому подобного.

loop — это необязательная предварительно построенная операция enterloop для использования в цикле; если она равна null, то подходящая операция будет построена автоматически. expr предоставляет выражение управления циклом. block предоставляет основную часть цикла, а cont необязательно предоставляет блок continue, который работает как вторая половина тела. Все эти входные данные optree потребляются этой функцией и становятся частью построенного дерева операций.

flags предоставляет восемь битов op_flags для операции leaveloop и, сдвинутые влево на восемь битов, восемь битов op_private для операции leaveloop, за исключением того, что (в обоих случаях) некоторые биты будут установлены автоматически. debuggable в настоящее время не используется и должно всегда быть равно 1. has_my может быть предоставлено как true, чтобы принудительно заключить тело цикла в свой собственный scope.

OP *    newWHILEOP(I32 flags, I32 debuggable,
                   LOOP *loop, OP *expr, OP *block,
                   OP *cont, I32 has_my)

Функции обработки деревьев операций

alloccopstash

Доступна только в многопоточных сборках, эта функция выделяет запись в PL_stashpad для стека, переданного ей.

PADOFFSET alloccopstash(HV *hv)

block_end

Обрабатывает выход из области видимости во время компиляции. floor — это индекс стека сохранений, возвращённый функцией block_start, а seq — это тело блока. Возвращает блок, возможно, изменённый.

OP *    block_end(I32 floor, OP *seq)

block_start

Обрабатывает вход в область видимости во время компиляции. Обеспечивает восстановление подсказок при выходе из блока и также обрабатывает последовательные номера заполнения, чтобы обеспечить правильную область видимости лексических переменных. Возвращает индекс стека сохранений для использования с block_end.

int     block_start(int full)

ck_entersub_args_list

Выполняет стандартную обработку аргументов в дереве операций entersub. Она включает применение контекста списка к каждой операции аргумента. Это стандартная обработка, используемая для вызовов, отмеченных &, или для вызовов методов, или для вызовов через ссылку на подпрограмму, или для любых других вызовов, где вызываемый объект не может быть определён во время компиляции, или для вызовов, где вызываемый объект не имеет прототипа.

OP *    ck_entersub_args_list(OP *entersubop)

ck_entersub_args_proto

Выполняет обработку аргументов в дереве операций entersub на основе прототипа подпрограммы. Это включает различные изменения в операциях аргументов, от применения контекста до вставки операций refgen, и проверки количества и синтаксических типов аргументов в соответствии с прототипом. Это стандартная обработка, используемая для вызова подпрограммы, не отмеченной &, где вызываемый объект может быть определён во время компиляции и имеет прототип.

protosv предоставляет прототип подпрограммы для применения к вызову. Он может быть обычным скаляром, в котором будет использовано строковое значение. Или, для удобства, это может быть объект подпрограммы (CV*, который был преобразован в SV*), имеющий прототип. Предоставленный прототип, в любом виде, не обязательно должен соответствовать фактическому вызываемому объекту, на который ссылается дерево операций.

Если операции аргументов не соответствуют прототипу, например, из-за недопустимого количества аргументов, всё равно возвращается валидное дерево операций. Ошибка отражается в состоянии парсера, обычно приводя к одному исключению на верхнем уровне парсинга, которое охватывает все произошедшие ошибки компиляции. В сообщении об ошибке вызываемый объект указывается по имени, определённому параметром namegv.

OP *    ck_entersub_args_proto(OP *entersubop,
                               GV *namegv, SV *protosv)

ck_entersub_args_proto_or_list

Выполняет обработку аргументов в дереве операций entersub либо на основе прототипа подпрограммы, либо с помощью обработки по умолчанию в контексте списка. Это стандартная обработка, используемая для вызова подпрограммы, не отмеченной &, где вызываемый объект может быть определён во время компиляции.

protosv предоставляет прототип подпрограммы для применения к вызову или указывает, что прототип отсутствует. Это может быть обычный скаляр, в котором, если он определён, будет использоваться строковое значение в качестве прототипа, а если он не определён, прототипа нет. Или, для удобства, это может быть объект подпрограммы (CV*, преобразованный в SV*), прототип которого будет использован, если он есть. Предоставленный прототип (или его отсутствие), в любом виде, не обязательно должен соответствовать фактическому вызываемому объекту, на который ссылается дерево операций.

OP *    ck_entersub_args_proto_or_list(OP *entersubop,
                                       GV *namegv,
                                       SV *protosv)

cv_const_sv

Если cv — константная подпрограмма, подходящая для инлайнинга, возвращает константное значение, возвращённое подпрограммой. В противном случае, возвращает NULL.

Константные подпрограммы могут быть созданы с помощью newCONSTSUB или, как описано в "Константные функции" в perlsub.

SV*     cv_const_sv(const CV *const cv)

cv_get_call_checker

Исходный вид "cv_get_call_checker_flags", который не возвращает флаги проверки. При использовании функции проверки, возвращённой этой функцией, безопасно вызывать её только с настоящим GV в качестве аргумента namegv.

void    cv_get_call_checker(CV *cv,
                            Perl_call_checker *ckfun_p,
                            SV **ckobj_p)

cv_get_call_checker_flags

Возвращает функцию, которая будет использоваться для обработки вызова cv. Конкретно, функция применяется к дереву операций entersub для вызова подпрограммы, не отмеченной &, где вызываемый объект может быть идентифицирован во время компиляции как cv.

Указатель на функцию на уровне C возвращается в *ckfun_p, аргумент SV для неё возвращается в *ckobj_p, а управляющие флаги возвращаются в *ckflags_p. Функция предназначена для вызова следующим образом:

entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));

В этом вызове entersubop — указатель на операцию entersub, которая может быть заменена функцией проверки, а namegv предоставляет имя, которое функция проверки должна использовать для обращения к вызываемому объекту операции entersub в случае необходимости вывода диагностических сообщений. Разрешается применять функцию проверки в нестандартных ситуациях, таких как вызов другой подпрограммы или вызов метода.

namegv фактически может не быть GV. Если бит CALL_CHECKER_REQUIRE_GV в *ckflags_p сброшен, разрешается передать CV или другой SV вместо него, что может использоваться в качестве первого аргумента для "cv_name". Если бит CALL_CHECKER_REQUIRE_GV установлен в *ckflags_p, функция проверки требует, чтобы namegv был настоящим GV.

По умолчанию функцией проверки является Perl_ck_entersub_args_proto_or_list, параметром SV является cv сам, и флаг CALL_CHECKER_REQUIRE_GV сброшен. Это реализует стандартную обработку прототипов. Она может быть изменена для конкретной подпрограммы с помощью "cv_set_call_checker_flags".

Если бит CALL_CHECKER_REQUIRE_GV установлен в gflags, это означает, что вызывающий объект знает только о версии namegv в виде настоящего GV, и соответственно соответствующий бит всегда будет установлен в *ckflags_p, независимо от требований функции проверки. Если бит CALL_CHECKER_REQUIRE_GV сброшен в gflags, это означает, что вызывающий объект знает о возможности передачи чего-то другого, помимо GV, в качестве namegv, и соответственно соответствующий бит может быть либо установлен, либо сброшен в *ckflags_p, указывая на требования функции проверки.

gflags — это битовая маска, передаваемая в cv_get_call_checker_flags, в которой только бит CALL_CHECKER_REQUIRE_GV в настоящее время имеет определённое значение (см. выше). Все остальные биты должны быть сброшены.

void    cv_get_call_checker_flags(
            CV *cv, U32 gflags,
            Perl_call_checker *ckfun_p, SV **ckobj_p,
            U32 *ckflags_p
        )

cv_set_call_checker

Исходный вид "cv_set_call_checker_flags", который передаёт флаг CALL_CHECKER_REQUIRE_GV для обратной совместимости. В результате установки этого флага функция проверки гарантированно получит настоящий GV в качестве аргумента namegv.

void    cv_set_call_checker(CV *cv,
                            Perl_call_checker ckfun,
                            SV *ckobj)

cv_set_call_checker_flags

Устанавливает функцию, которая будет использоваться для обработки вызова cv. Конкретно, функция применяется к дереву операций entersub для вызова подпрограммы, не отмеченной &, где вызываемый объект может быть идентифицирован во время компиляции как cv.

Указатель на функцию на уровне C передаётся в ckfun, аргумент SV для неё передаётся в ckobj, а управляющие флаги передаются в ckflags. Функция должна быть определена так:

STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)

Она предназначена для вызова следующим образом:

entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);

namegv фактически может не быть GV. Для повышения эффективности Perl может передать CV или другой SV вместо него. Переданное значение может быть использовано в качестве первого аргумента для "cv_name". Для принудительной передачи GV включите CALL_CHECKER_REQUIRE_GV в ckflags.

ckflags — это битовая маска, в которой только бит CALL_CHECKER_REQUIRE_GV в настоящее время имеет определённое значение (см. выше). Все остальные биты должны быть сброшены.

Текущее значение для конкретного CV может быть получено с помощью "cv_get_call_checker_flags".

void    cv_set_call_checker_flags(
            CV *cv, Perl_call_checker ckfun, SV *ckobj,
            U32 ckflags
        )

LINKLIST

Исходя из корня дерева операций, связывает дерево в порядке выполнения, используя указатели op_next, и возвращает первую выполняемую операцию. Если это уже было сделано, оно не будет переделано, и будет возвращено o->op_next. Если o->op_next ещё не установлен, o должен быть, по крайней мере, UNOP.

OP*     LINKLIST(OP *o)

newCONSTSUB

Ведёт себя как "newCONSTSUB_flags", за исключением того, что name имеет нуль-терминатор, а не счёт длины, и не устанавливаются никакие флаги. (Это означает, что name всегда интерпретируется как Latin-1.)

CV *    newCONSTSUB(HV *stash, const char *name, SV *sv)

newCONSTSUB_flags

Создайте подпрограмму-константу, также выполняя некоторые связанные задачи. Скалярная подпрограмма с постоянным значением подходит для встраивания во время компиляции, и в коде Perl она может быть создана с помощью sub FOO () { 123 }. Другие виды константных подпрограмм имеют другое обращение.

Подпрограмма будет иметь пустой прототип и игнорировать любые аргументы при вызове. Ее поведение в качестве константы определяется sv. Если sv равно null, подпрограмма вернёт пустой список. Если sv указывает на скаляр, подпрограмма всегда вернёт этот скаляр. Если sv указывает на массив, подпрограмма всегда вернёт список элементов этого массива в контексте списка или количество элементов в массиве в скалярном контексте. Эта функция берёт на себя владение одной учтённой ссылкой на скаляр или массив и организует существование объекта до тех пор, пока существует подпрограмма. Если sv указывает на скаляр, то встраивание предполагает, что значение скаляра никогда не изменится, поэтому вызывающая сторона должна гарантировать, что скаляр не будет записан впоследствии. Если sv указывает на массив, то такое предположение не делается, поэтому, по видимости, безопасно изменять массив или его элементы, но подтверждено ли это на самом деле, не определено.

Подпрограмма будет иметь CvFILE установленным в соответствии с PL_curcop. Другие аспекты подпрограммы останутся по умолчанию. Вызывающая сторона может изменять состояние подпрограммы после возврата этой функции.

Если name равно null, подпрограмма будет анонимной, а её CvGV будет ссылаться на __ANON__ глобальную переменную. Если name не равно null, подпрограмма будет именованной, на которую будет ссылаться соответствующая глобальная переменная. name — строка длиной len байт, содержащая имя символа без сигнатуры, в UTF-8, если у flags установлен бит SVf_UTF8, и в Latin-1 в противном случае. Имя может быть квалифицированным или неквалифицированным. Если имя неквалифицировано, оно по умолчанию находится в хранилище, указанном stash, если оно не равно null, или в PL_curstash, если stash равно null. Символ всегда добавляется в хранилище при необходимости с семантикой GV_ADDMULTI.

flags не должно иметь установленных битов, кроме SVf_UTF8.

Если уже существует подпрограмма с указанным именем, новая подпрограмма заменит существующую в глобальной переменной. Может быть выведено предупреждение о переопределении.

Если у подпрограммы одно из нескольких специальных имён, таких как BEGIN или END, она будет передана в соответствующую очередь для автоматического запуска подпрограмм, связанных с этапом. В этом случае соответствующая глобальная переменная останется пустой, даже если она содержала подпрограмму ранее. Выполнение подпрограммы, вероятно, будет пустой операцией, если sv был связанным массивом или вызывающая сторона изменила подпрограмму каким-либо интересным образом до её выполнения. В случае BEGIN обработка является некорректной: подпрограмма будет выполнена только наполовину, и может быть удалена преждевременно, что, возможно, приведёт к сбою.

Функция возвращает указатель на созданную подпрограмму. Если подпрограмма анонимная, то владение одной учтённой ссылкой на подпрограмму передаётся вызывающей стороне. Если подпрограмма именованная, то вызывающая сторона не получает владение ссылкой. В большинстве таких случаев, когда у подпрограммы имя не связано с этапом, подпрограмма будет активной в момент возврата благодаря включению в глобальную переменную, которая её называет. Подпрограмма, имеющая имя этапа, обычно будет активной благодаря ссылке, принадлежащей автоматической очереди выполнения этапа. Подпрограмма BEGIN может быть уже уничтожена к моменту возврата этой функции, но в настоящее время ошибки возникают в этом случае до того, как вызывающая сторона получает управление. Вызывающая сторона отвечает за то, чтобы знать, какая из этих ситуаций применима.

CV *    newCONSTSUB_flags(HV *stash, const char *name,
                          STRLEN len, U32 flags, SV *sv)

newXS

Используется xsubpp для подключения XSUB в качестве Perl-подпрограмм. filename должен находиться в статическом хранилище, поскольку он используется непосредственно как CvFILE() без создания копии.

op_append_elem

Добавить элемент в список операций, содержащихся непосредственно в списке-операции, возвращая удлинённый список. first — операция списка, а last — операция, которую нужно добавить в список. optype определяет предполагаемый код операции для списка. Если first ещё не является списком нужного типа, он будет преобразован в него. Если first или last равно null, то другой возвращается без изменений.

OP *    op_append_elem(I32 optype, OP *first, OP *last)

op_append_list

Конкатенация списков операций, содержащихся непосредственно в двух операциях списка, возвращая объединённый список. first и last — операции списка, которые необходимо конкатенировать. optype определяет предполагаемый код операции для списка. Если first или last ещё не являются списком нужного типа, они будут преобразованы в него. Если first или last равно null, то другой возвращается без изменений.

OP *    op_append_list(I32 optype, OP *first, OP *last)

OP_CLASS

Возвращает класс предоставленной операции: то есть, какой из структур *OP она использует. Для основных операций это в настоящее время извлекает информацию из PL_opargs, что не всегда точно отражает используемый тип; начиная с версии 5.26, см. также функцию "op_class", которая может лучше определить используемый тип.

Для пользовательских операций тип возвращается из регистрации, и регистрируемая сторона отвечает за то, чтобы он был точным. Возвращаемое значение будет одним из констант OA_* из op.h.

U32     OP_CLASS(OP *o)

op_contextualize

Применяет синтаксический контекст к дереву операций, представляющему выражение. o — дерево операций, а context должно быть G_SCALAR, G_ARRAY, или G_VOID, чтобы указать применяемый контекст. Изменённое дерево операций возвращается.

OP *    op_contextualize(OP *o, I32 context)

op_convert_list

Преобразует o в операцию списка, если это не уже список, а затем преобразует её в указанную type, вызывая её функцию проверки, выделяя целевой объект, если он нужен, и сворачивая константы.

Список-операция обычно создаётся по одному элементу за раз с помощью newLISTOP, op_prepend_elem и op_append_elem. Затем, наконец, он передаётся op_convert_list для приведения к нужному типу.

OP *    op_convert_list(I32 type, I32 flags, OP *o)

OP_DESC

Возвращает краткое описание предоставленной операции.

const char * OP_DESC(OP *o)

op_free

Освободить операцию. Используйте только тогда, когда операция больше не связана ни с одним деревом операций.

void    op_free(OP *o)

OpHAS_SIBLING

Возвращает true, если o имеет sibling

bool    OpHAS_SIBLING(OP *o)

OpLASTSIB_set

Помечает o как не имеющий дальнейших siblings и помечает o как имеющего указанного родителя. См. также "OpMORESIB_set" и OpMAYBESIB_set. Для более высокого уровня интерфейса см. "op_sibling_splice".

void    OpLASTSIB_set(OP *o, OP *parent)

op_linklist

Эта функция является реализацией макроса "LINKLIST". Не следует вызывать её напрямую.

OP*     op_linklist(OP *o)

op_lvalue

Распространяет контекст lvalue ("изменяемый") на операцию и её дочерние элементы. type представляет тип контекста, приблизительно основанный на типе операции, которая будет производить изменение, хотя local() представлен OP_NULL, потому что у него нет собственного типа операции (он сигнализируется флагом на операции lvalue).

Эта функция обнаруживает элементы, которые нельзя изменить, такие как $x+1, и генерирует ошибки для них. Например, $x+1 = 2 заставило бы её быть вызванной с операцией типа OP_ADD и аргументом type типа OP_SASSIGN.

Она также помечает элементы, которые должны вести себя особым образом в контексте lvalue, такие как $$x = 5, которые могут потребовать оживления ссылки в $x.

OP *    op_lvalue(OP *o, I32 type)

OpMAYBESIB_set

Условно выполняет OpMORESIB_set или OpLASTSIB_set в зависимости от того, является ли sib не равным null. Для более высокого уровня интерфейса см. "op_sibling_splice".

void    OpMAYBESIB_set(OP *o, OP *sib, OP *parent)

OpMORESIB_set

Устанавливает sibling o на ненулевое значение sib. См. также "OpLASTSIB_set" и "OpMAYBESIB_set". Для более высокого уровня интерфейса см. "op_sibling_splice".

void    OpMORESIB_set(OP *o, OP *sib)

OP_NAME

Возвращает имя предоставленной операции. Для основных операций это ищет имя из op_type; для пользовательских операций из op_ppaddr.

const char * OP_NAME(OP *o)

op_null

Сводит на нет операцию, когда она больше не нужна, но всё ещё связана с другими операциями.

void    op_null(OP *o)

op_parent

Возвращает родительскую операцию o, если у неё есть родитель. В противном случае возвращает NULL.

OP*     op_parent(OP *o)

op_prepend_elem

Добавить элемент в начало списка операций, содержащихся непосредственно в списке-операции, возвращая удлинённый список. first — добавляемая операция, а last — список-операция. optype определяет предполагаемый код операции для списка. Если last ещё не является списком нужного типа, он будет преобразован в него. Если first или last равно null, то другой возвращается без изменений.

OP *    op_prepend_elem(I32 optype, OP *first, OP *last)

op_scope

Оборачивает дерево операций дополнительными операциями, так что во время выполнения будет создан динамический контекст. Исходные операции выполняются в новом динамическом контексте, а затем, при условии нормального завершения, контекст будет развёрнут. Дополнительные операции, используемые для создания и развёртывания динамического контекста, обычно будут парой enter/leave, но вместо этого может быть использована операция scope, если операции достаточно простые, чтобы не требовали полной структуры динамического контекста.

OP *    op_scope(OP *o)

OpSIBLING

Возвращает следующего брата o, или NULL, если брата нет

OP*     OpSIBLING(OP *o)

op_sibling_splice

Общая функция для редактирования структуры существующей цепочки узлов op_sibling. По аналогии с функцией splice() на уровне Perl, позволяет удалить ноль или более последовательных узлов, заменив их нулём или более различными узлами. Выполняет необходимые операции op_first/op_last по обработке родительского узла и манипуляции op_sibling для дочерних узлов. Последний удалённый узел помечается как последний узел путём обновления поля op_sibling/op_sibparent или op_moresib, как соответствующим образом.

Обратите внимание, что op_next не изменяется, и узлы не освобождаются; это ответственность вызывающей стороны. Также не создаёт новый список op для пустого списка и т.д.; используйте функции более высокого уровня, такие как op_append_elem() для этого.

parent — родительский узел цепочки братьев. Он может передаваться как NULL, если вставка не затрагивает первый или последний op в цепочке.

start — узел, предшествующий первому узлу, подлежащему вставке. Узел(ы), следующие за ним, будут удалены, а ops будут вставлены после него. Если это NULL, первый узел и далее удаляются, а узлы вставляются в начало.

del_count — количество узлов для удаления. Если ноль, узлы не удаляются. Если -1 или больше или равно количеству оставшихся детей, все оставшиеся дети удаляются.

insert — первый из цепочки узлов, которые будут вставлены вместо удалённых узлов. Если NULL, узлы не вставляются.

Возвращается головной узел цепочки удалённых ops или NULL, если ops не были удалены.

Например:

action                    before      after         returns
------                    -----       -----         -------

                          P           P
splice(P, A, 2, X-Y-Z)    |           |             B-C
                          A-B-C-D     A-X-Y-Z-D

                          P           P
splice(P, NULL, 1, X-Y)   |           |             A
                          A-B-C-D     X-Y-B-C-D

                          P           P
splice(P, NULL, 3, NULL)  |           |             A-B-C
                          A-B-C-D     D

                          P           P
splice(P, B, 0, X-Y)      |           |             NULL
                          A-B-C-D     A-B-X-Y-C-D

Для более низкоуровневой непосредственной манипуляции с op_sibparent и op_moresib, см. "OpMORESIB_set", "OpLASTSIB_set", "OpMAYBESIB_set".

OP*     op_sibling_splice(OP *parent, OP *start,
                          int del_count, OP* insert)

OP_TYPE_IS

Возвращает true, если данный OP не является указателем NULL и если он является указанного типа.

Отрицание этой макрокоманды, OP_TYPE_ISNT, также доступно, а также OP_TYPE_IS_NN и OP_TYPE_ISNT_NN, которые исключают проверку на NULL-указатель.

bool    OP_TYPE_IS(OP *o, Optype type)

OP_TYPE_IS_OR_WAS

Возвращает true, если данный OP не является NULL-указателем и если он является указанного типа или им был до замены на OP типа OP_NULL.

Отрицание этой макрокоманды, OP_TYPE_ISNT_AND_WASNT, также доступно, а также OP_TYPE_IS_OR_WAS_NN и OP_TYPE_ISNT_AND_WASNT_NN, которые исключают проверку на NULL-указатель.

bool    OP_TYPE_IS_OR_WAS(OP *o, Optype type)

rv2cv_op_cv

Изучает op, который ожидается для идентификации подпрограммы во время выполнения, и пытается определить во время компиляции, какую подпрограмму он идентифицирует. Это обычно используется во время компиляции Perl для определения того, можно ли применить шаблон к вызову функции. cvop — рассматриваемый op, обычно op rv2cv. Возвращается указатель на идентифицированную подпрограмму, если она могла быть определена статически, и возвращается нулевой указатель, если это не удалось определить статически.

В настоящее время подпрограмму можно определить статически, если RV, на котором должен работать rv2cv, предоставляется подходящим op gv или const. Op gv подходит, если слот CV GV заполнен. Op const подходит, если константное значение должно быть RV, указывающим на CV. Подробности этого процесса могут измениться в будущих версиях Perl. Если у op rv2cv установлен флаг OPpENTERSUB_AMPER, то попытка идентифицировать подпрограмму статически не предпринимается: этот флаг используется для подавления магических действий во время компиляции при вызове подпрограммы, заставляя использовать стандартное поведение во время выполнения.

Если у flags установлен бит RV2CVOPCV_MARK_EARLY, то обработка ссылки GV модифицируется. Если был изучен GV и его слот CV оказался пустым, то у op gv установлен флаг OPpEARLY_CV. Если op не оптимизирован, а слот CV позже заполнен подпрограммой с шаблоном, этот флаг в конечном итоге вызывает предупреждение "вызвано слишком рано для проверки шаблона".

Если у flags установлен бит RV2CVOPCV_RETURN_NAME_GV, то вместо возвращения указателя на подпрограмму возвращается указатель на GV, предоставляющий наиболее подходящее имя для подпрограммы в этом контексте. Обычно это просто CvGV подпрограммы, но для анонимной (CvANON) подпрограммы, на которую ссылаются через GV, это будет ссылающийся GV. Результирующий GV* приводится к типу CV* для возврата. Нулевой указатель возвращается как обычно, если статически определяемая подпрограмма отсутствует.

CV *    rv2cv_op_cv(OP *cvop, U32 flags)

Упаковщики и распаковщики

packlist

Двигатель, реализующий функцию pack() Perl.

void    packlist(SV *cat, const char *pat,
                 const char *patend, SV **beglist,
                 SV **endlist)

unpackstring

Двигатель, реализующий функцию unpack() Perl.

Используя шаблон pat..patend, эта функция распаковывает строку s..strend в ряд смертных SVs, которые она помещает на стек аргументов Perl (@_) (поэтому вам необходимо выполнить PUTBACK перед и SPAGAIN после вызова этой функции). Она возвращает количество помещенных элементов.

Указатели strend и patend должны указывать на байт, следующий за последним символом каждой строки.

Хотя эта функция возвращает свои значения на стеке аргументов Perl, она не принимает никаких параметров со стека (и, следовательно, в частности, нет необходимости выполнять PUSHMARK перед вызовом, в отличие от "call_pv", например).

SSize_t unpackstring(const char *pat,
                     const char *patend, const char *s,
                     const char *strend, U32 flags)

Структуры данных Pad

CvPADLIST

В CV может быть установлено CvPADLIST(cv), указывающее на PADLIST. Это рабочая область CV, которая хранит лексические переменные и временные значения кода операций и значения на нить.

Для этих целей «форматы» — это своего рода CV; eval"" тоже (за исключением того, что они не вызываемы по желанию и всегда удаляются после завершения выполнения eval""). Требуемые файлы — это просто evals без внешней лексической области.

XSUB не имеет CvPADLIST. dXSTARG извлекает значения из PL_curpad, но это действительно рабочая область вызывающего (слот которой выделяется при каждом вызове entersub). Не получайте и не устанавливайте CvPADLIST , если CV является XSUB (как определено CvISXSUB()), CvPADLIST слот используется для другой внутренней цели в XSUB.

PADLIST имеет массив C, где хранятся пады.

Нулевой элемент PADLIST — PADNAMELIST, представляющий «имена» или, скорее, «статическую информацию о типе» для лексических переменных. Отдельные элементы PADNAMELIST — это PADNAME. Будущие рефакторинги могут прекратить хранение PADNAMELIST в массиве PADLIST, поэтому не полагайтесь на это. См. "PadlistNAMES".

Элемент с индексом CvDEPTH в PADLIST — это PAD (AV), который является стековым фреймом на данной глубине рекурсии в CV. Нулевой слот фрейма AV — это AV, который @_. Другие элементы — хранилище для переменных и целевых значений операций.

Итерация по PADNAMELIST итерирует по всем возможным элементам пады. Слот пады для целей (SVs_PADTMP) и GVs получают имена &PL_padname_undef, в то время как слоты для констант имеют &PL_padname_const имена (см. "pad_alloc"). Использование &PL_padname_undef и &PL_padname_const является деталью реализации, которая может измениться. Для проверки их используйте !PadnamePV(name) и PadnamePV(name) && !PadnameLEN(name) соответственно.

Только слоты переменных my/our получают действительные имена. Остальные — это целевые значения операций/GVs/константы, которые статически выделены или разрешены на этапе компиляции. У них нет имен, по которым их можно найти из кода Perl во время выполнения через eval"", так как my/our переменные могут быть. Поскольку их нельзя найти по «имени», а только по индексу, выделенному на этапе компиляции (обычно в PL_op->op_targ), выделение для них имени SV не имеет смысла.

Имена падов в PADNAMELIST имеют PV, содержащий имя переменной. Поля COP_SEQ_RANGE_LOW и _HIGH образуют диапазон (low+1..high включительно) номеров cop_seq, для которых имя является допустимым. Во время компиляции эти поля могут содержать специальное значение PERL_PADSEQ_INTRO, чтобы указывать различные стадии:

COP_SEQ_RANGE_LOW        _HIGH
-----------------        -----
PERL_PADSEQ_INTRO            0   variable not yet introduced:
                                 { my ($x
valid-seq#   PERL_PADSEQ_INTRO   variable in scope:
                                 { my ($x);
valid-seq#          valid-seq#   compilation of scope complete:
                                 { my ($x); .... }

Когда лексическая переменная ещё не была введена, она уже существует с точки зрения дублирования объявлений, но не для поиска переменных, например:

my ($x, $x); # '"my" variable $x masks earlier declaration'
my $x = $x;  # equal to my $x = $::x;

Для типизированных лексических переменных PadnameTYPE указывает на хранилище типа. Для our лексических переменных PadnameOURSTASH указывает на хранилище связанной глобальной переменной (чтобы можно было обнаружить дублирующие our объявления в одном пакете). PadnameGEN иногда используется для хранения номера генерации во время компиляции.

Если для имени пады установлено PadnameOUTER, то соответствующий элемент в массиве AV — это имеющий счётчик ссылок reference к лексической переменной из «вне». Такие элементы иногда называют «ложными». В этом случае имя не использует «low» и «high» для хранения диапазона cop_seq, так как оно находится в области видимости на протяжении всего времени. Вместо этого «high» хранит некоторые флаги, содержащие информацию о реальной лексической переменной (объявлена ли она в анонимной функции и может ли быть создана несколько раз?), а для ложных ANON «low» содержит индекс в паде родительской переменной, где хранится значение лексической переменной, чтобы ускорить клонирование.

Если «имя» равно &, соответствующий элемент в PAD — это CV, представляющий возможный замыкание.

Обратите внимание, что форматы обрабатываются как анонимные подпрограммы и клонируются каждый раз, когда вызывается write (если это необходимо).

Флаг SVs_PADSTALE сбрасывается для лексических переменных каждый раз, когда выполняется my(), и устанавливается при выходе из области видимости. Это позволяет генерировать предупреждение "Variable $x is not available" в evals, таких как

{ my $x = 1; sub f { eval '$x'} } f();

Для переменных состояния SVs_PADSTALE перегружено, чтобы означать «ещё не инициализировано», но это внутреннее состояние хранится в отдельном элементе пады.

PADLIST * CvPADLIST(CV *cv)

pad_add_name_pvs

Точно так же, как "pad_add_name_pvn", но принимает строку-литерал вместо пары строка/длина.

PADOFFSET pad_add_name_pvs("literal string" name,
                           U32 flags, HV *typestash,
                           HV *ourstash)

PadARRAY

Массив C элементов пады.

SV **   PadARRAY(PAD pad)

pad_findmy_pvs

Точно так же, как "pad_findmy_pvn", но принимает строку-литерал вместо пары строка/длина.

PADOFFSET pad_findmy_pvs("literal string" name,
                         U32 flags)

PadlistARRAY

Массив C элементов padlist, содержащий пады. Используйте только индексы >= 1, так как нулевой элемент не гарантируется, что останется доступным.

PAD **  PadlistARRAY(PADLIST padlist)

PadlistMAX

Индекс последнего выделенного элемента в padlist. Обратите внимание, что последняя пада может находиться в более раннем слоте. В этом случае все последующие элементы будут NULL.

SSize_t PadlistMAX(PADLIST padlist)

PadlistNAMES

Имена, связанные с элементами пады.

PADNAMELIST * PadlistNAMES(PADLIST padlist)

PadlistNAMESARRAY

Массив C имён пады.

PADNAME ** PadlistNAMESARRAY(PADLIST padlist)

PadlistNAMESMAX

Индекс последнего имени пады.

SSize_t PadlistNAMESMAX(PADLIST padlist)

PadlistREFCNT

Счётчик ссылок padlist. В настоящее время он всегда равен 1.

U32     PadlistREFCNT(PADLIST padlist)

PadMAX

Индекс последнего элемента пады.

SSize_t PadMAX(PAD pad)

PadnameLEN

Длина имени.

STRLEN  PadnameLEN(PADNAME pn)

PadnamelistARRAY

Массив C имён пады.

PADNAME ** PadnamelistARRAY(PADNAMELIST pnl)

PadnamelistMAX

Индекс последнего имени пады.

SSize_t PadnamelistMAX(PADNAMELIST pnl)

PadnamelistREFCNT

Счётчик ссылок списка имён пады.

SSize_t PadnamelistREFCNT(PADNAMELIST pnl)

PadnamelistREFCNT_dec

Уменьшает счётчик ссылок списка имён пады.

void    PadnamelistREFCNT_dec(PADNAMELIST pnl)

PadnamePV

Имя, хранящееся в структуре имени пады. Возвращает NULL для целевого слота.

char *  PadnamePV(PADNAME pn)

PadnameREFCNT

Счётчик ссылок имени пады.

SSize_t PadnameREFCNT(PADNAME pn)

PadnameREFCNT_dec

Уменьшает счётчик ссылок имени пады.

void    PadnameREFCNT_dec(PADNAME pn)

PadnameSV

Возвращает имя пады как временный SV.

SV *    PadnameSV(PADNAME pn)

PadnameUTF8

Является ли PadnamePV в кодировке UTF-8. В настоящее время это всегда true.

bool    PadnameUTF8(PADNAME pn)

pad_new

Создаёт новый padlist, обновляя глобальные переменные, чтобы они указывали на новый padlist. Можно объединять следующие флаги:

padnew_CLONE        this pad is for a cloned CV
padnew_SAVE         save old globals on the save stack
padnew_SAVESUB      also save extra stuff for start of sub

    PADLIST * pad_new(int flags)

PL_comppad

Во время компиляции указывает на массив, содержащий значения части пады для компилируемого кода. (Во время выполнения CV может иметь много таких массивов значений; во время компиляции создаётся только один.) Во время выполнения указывает на массив, содержащий текущие значения для пады для текущего выполняемого кода.

PL_comppad_name

Во время компиляции указывает на массив, содержащий имена части пады для компилируемого кода.

PL_curpad

Указывает непосредственно на тело массива "PL_comppad". (То есть, это PadARRAY(PL_comppad).)

Переменные интерпретатора

PL_modglobal

PL_modglobal — это глобальная переменная интерпретатора общего назначения, предназначенная для использования расширениями, которым нужно сохранять информацию на основе каждого интерпретатора. В крайнем случае, она может использоваться как таблица символов для обмена данными между расширениями. Рекомендуется использовать ключи, префикс которых соответствует имени пакета расширения, владеющего данными.

HV*     PL_modglobal

PL_na

Удобная переменная, обычно используемая с SvPV, когда длина строки не имеет значения. Обычно эффективнее объявить локальную переменную или использовать макрос SvPV_nolen.

STRLEN  PL_na

PL_opfreehook

Если не NULL, то функция, указанная в этой переменной, будет вызываться каждый раз, когда OP освобождается, с соответствующим OP в качестве аргумента. Это позволяет расширениям освобождать любые дополнительные атрибуты, локально присоединенные к OP. Гарантируется, что сначала вызов произойдёт для родительского OP, а затем для его дочерних элементов.

При замене этой переменной рекомендуется сохранить ранее установленный хук и вызвать его внутри собственной функции.

Perl_ophook_t   PL_opfreehook

PL_peepp

Указатель на оптимизатор просматривающего окна для каждой подпрограммы. Это функция, которая вызывается в конце компиляции подпрограммы Perl (или, что эквивалентно, независимого фрагмента кода Perl) для исправления некоторых OP и выполнения оптимизации малого масштаба. Функция вызывается один раз для каждой компилируемой подпрограммы и получает в качестве единственного параметра указатель на OP, являющийся точкой входа в подпрограмму. Она изменяет дерево OP на месте.

Оптимизатор просматривающего окна никогда не должен заменяться полностью. Вместо этого следует добавлять код, оборачивая существующий оптимизатор. Базовый способ сделать это можно посмотреть в "Compile pass 3: peephole optimization" в perlguts. Если новый код хочет работать с OP во всей структуре подпрограммы, а не только на верхнем уровне, то, вероятно, удобнее будет обернуть хук "PL_rpeepp".

peep_t  PL_peepp

PL_rpeepp

Указатель на рекурсивный оптимизатор просматривающего окна. Это функция, которая вызывается в конце компиляции подпрограммы Perl (или, что эквивалентно, независимого фрагмента кода Perl) для исправления некоторых OP и выполнения оптимизации малого масштаба. Функция вызывается один раз для каждой цепочки OP, связанных через поля op_next; она рекурсивно вызывается для обработки каждой боковой цепочки. Она получает в качестве единственного параметра указатель на OP, который находится в начале цепочки. Она изменяет дерево OP на месте.

Оптимизатор просматривающего окна никогда не должен заменяться полностью. Вместо этого следует добавлять код, оборачивая существующий оптимизатор. Базовый способ сделать это можно посмотреть в "Compile pass 3: peephole optimization" в perlguts. Если новый код хочет работать только с OP на верхнем уровне подпрограммы, а не по всей структуре, то, вероятно, удобнее будет обернуть хук "PL_peepp".

peep_t  PL_rpeepp

PL_sv_no

Это false SV. См. "PL_sv_yes". Всегда ссылайтесь на него как на &PL_sv_no.

SV      PL_sv_no

PL_sv_undef

Это undef SV. Всегда ссылайтесь на него как на &PL_sv_undef.

SV      PL_sv_undef

PL_sv_yes

Это true SV. См. "PL_sv_no". Всегда ссылайтесь на него как на &PL_sv_yes.

SV      PL_sv_yes

PL_sv_zero

Этот неизменяемый SV имеет нулевое числовое значение и "0" строковое значение. Он похож на "PL_sv_no", за исключением строкового значения. Может использоваться в качестве дешёвой альтернативы mXPUSHi(0), например. Всегда ссылайтесь на него как на &PL_sv_zero. Введён в 5.28.

SV      PL_sv_zero

Функции REGEXP

SvRX

Удобный макрос для получения REGEXP из SV. Это примерно эквивалентно следующему фрагменту кода:

if (SvMAGICAL(sv))
    mg_get(sv);
if (SvROK(sv))
    sv = MUTABLE_SV(SvRV(sv));
if (SvTYPE(sv) == SVt_REGEXP)
    return (REGEXP*) sv;

NULL будет возвращено, если REGEXP* не найден.

REGEXP * SvRX(SV *sv)

SvRXOK

Возвращает булево значение, указывающее, является ли SV (или тот, на который он ссылается) REGEXP.

Если вы хотите что-то сделать с REGEXP* позже, используйте SvRX и проверьте на NULL.

bool    SvRXOK(SV* sv)

Макросы управления стеком

dMARK

Объявить переменную маркера стека, mark, для XSUB. См. "MARK" и "dORIGMARK".

dMARK;

dORIGMARK

Сохраняет исходную метку стека для XSUB. См. "ORIGMARK".

dORIGMARK;

dSP

Объявляет локальную копию указателя стека Perl для XSUB, доступную через макрос SP. См. "SP".

dSP;

EXTEND

Используется для расширения стека аргументов для значений возврата XSUB. После использования гарантирует, что в стеке есть место для помещения по крайней мере nitems элементов.

void    EXTEND(SP, SSize_t nitems)

MARK

Переменная маркера стека для XSUB. См. "dMARK".

mPUSHi

Поместить целое число в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHi", "mXPUSHi" и "XPUSHi".

void    mPUSHi(IV iv)

mPUSHn

Поместить двойное значение в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHn", "mXPUSHn" и "XPUSHn".

void    mPUSHn(NV nv)

mPUSHp

Поместить строку в стек. В стеке должно быть достаточно места для этого элемента. len указывает длину строки. Не использует TARG. См. также "PUSHp", "mXPUSHp" и "XPUSHp".

void    mPUSHp(char* str, STRLEN len)

mPUSHs

Поместить SV в стек и сделать SV смертельным. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHs" и "mXPUSHs".

void    mPUSHs(SV* sv)

mPUSHu

Поместить беззнаковое целое число в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHu", "mXPUSHu" и "XPUSHu".

void    mPUSHu(UV uv)

mXPUSHi

Поместить целое число в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHi", "mPUSHi" и "PUSHi".

void    mXPUSHi(IV iv)

mXPUSHn

Поместить двойное значение в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHn", "mPUSHn" и "PUSHn".

void    mXPUSHn(NV nv)

mXPUSHp

Поместить строку в стек, расширяя стек при необходимости. len указывает длину строки. Не использует TARG. См. также "XPUSHp", mPUSHp и PUSHp.

void    mXPUSHp(char* str, STRLEN len)

mXPUSHs

Поместить SV в стек, расширяя стек при необходимости и делая SV смертельным. Не использует TARG. См. также "XPUSHs" и "mPUSHs".

void    mXPUSHs(SV* sv)

mXPUSHu

Поместить беззнаковое целое число в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHu", "mPUSHu" и "PUSHu".

void    mXPUSHu(UV uv)

ORIGMARK

Исходная метка стека для XSUB. См. "dORIGMARK".

POPi

Извлечь целое число из стека.

IV      POPi

POPl

Извлечь целое число типа long из стека.

long    POPl

POPn

Извлечь двойное значение из стека.

NV      POPn

POPp

Извлечь строку из стека.

char*   POPp

POPpbytex

Извлекает строку из стека, которая должна состоять из байтов, т.е. символов < 256.

char*   POPpbytex

POPpx

Извлекает строку из стека. Идентично POPp. Есть два имени из-за исторических причин.

char*   POPpx

POPs

Извлечь SV из стека.

SV*     POPs

POPu

Извлечь беззнаковое целое число из стека.

UV      POPu

POPul

Извлечь беззнаковое целое число типа long из стека.

long    POPul

PUSHi

Поместить целое число в стек. В стеке должно быть достаточно места для этого элемента. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHi" вместо этого. См. также "XPUSHi" и "mXPUSHi".

void    PUSHi(IV iv)

PUSHMARK

Открывающая скобка для аргументов при обратном вызове. См. "PUTBACK" и perlcall.

void    PUSHMARK(SP)

PUSHmortal

Поместить новый смертный SV в стек. В стеке должно быть достаточно места для этого элемента. Не использует TARG. См. также "PUSHs", "XPUSHmortal" и "XPUSHs".

void    PUSHmortal()

PUSHn

Поместить двойное значение в стек. В стеке должно быть достаточно места для этого элемента. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHn" вместо этого. См. также "XPUSHn" и "mXPUSHn".

void    PUSHn(NV nv)

PUSHp

Поместить строку в стек. В стеке должно быть достаточно места для этого элемента. len указывает длину строки. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHp" вместо этого. См. также "XPUSHp" и "mXPUSHp".

void    PUSHp(char* str, STRLEN len)

PUSHs

Поместить SV в стек. В стеке должно быть достаточно места для этого элемента. Не обрабатывает магию «set». Не использует TARG. См. также "PUSHmortal", "XPUSHs", и "XPUSHmortal".

void    PUSHs(SV* sv)

PUSHu

Поместить беззнаковое целое число в стек. В стеке должно быть достаточно места для этого элемента. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mPUSHu" вместо этого. См. также "XPUSHu" и "mXPUSHu".

void    PUSHu(UV uv)

PUTBACK

Закрывающая скобка для аргументов XSUB. Обычно обрабатывается xsubpp. См. "PUSHMARK" и perlcall для других применений.

PUTBACK;

SP

Указатель стека. Обычно обрабатывается xsubpp. См. "dSP" и SPAGAIN.

SPAGAIN

Перезагрузить указатель стека. Используется после обратного вызова. См. perlcall.

SPAGAIN;

XPUSHi

Поместить целое число в стек, расширяя стек при необходимости. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mXPUSHi" вместо этого. См. также "PUSHi" и "mPUSHi".

void    XPUSHi(IV iv)

XPUSHmortal

Поместить новый смертный SV в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHs", "PUSHmortal" и "PUSHs".

void    XPUSHmortal()

XPUSHn

Поместить двойное значение в стек, расширяя стек при необходимости. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mXPUSHn" вместо этого. См. также "PUSHn" и "mPUSHn".

void    XPUSHn(NV nv)

XPUSHp

Поместить строку в стек, расширяя стек при необходимости. len указывает длину строки. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mXPUSHp" вместо этого. См. также "PUSHp" и "mPUSHp".

void    XPUSHp(char* str, STRLEN len)

XPUSHs

Поместить SV в стек, расширяя стек при необходимости. Не обрабатывает магию «set». Не использует TARG. См. также "XPUSHmortal", PUSHs и PUSHmortal.

void    XPUSHs(SV* sv)

XPUSHu

Поместить беззнаковое целое число в стек, расширяя стек при необходимости. Обрабатывает магию «set». Использует TARG, поэтому необходимо вызвать dTARGET или dXSTARG для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB — используйте "mXPUSHu" вместо этого. См. также "PUSHu" и "mPUSHu".

void    XPUSHu(UV uv)

XSRETURN

Возврат из XSUB, указывающий количество элементов в стеке. Обычно обрабатывается xsubpp.

void    XSRETURN(int nitems)

XSRETURN_EMPTY

Немедленно вернуть пустой список из XSUB.

XSRETURN_EMPTY;

XSRETURN_IV

Немедленно вернуть целое число из XSUB. Использует XST_mIV.

void    XSRETURN_IV(IV iv)

XSRETURN_NO

Немедленно вернуть &PL_sv_no из XSUB. Использует XST_mNO.

XSRETURN_NO;

XSRETURN_NV

Возвращает double из XSUB немедленно. Использует XST_mNV.

void    XSRETURN_NV(NV nv)

XSRETURN_PV

Возвращает копию строки из XSUB немедленно. Использует XST_mPV.

void    XSRETURN_PV(char* str)

XSRETURN_UNDEF

Возвращает &PL_sv_undef из XSUB немедленно. Использует XST_mUNDEF.

XSRETURN_UNDEF;

XSRETURN_UV

Возвращает целое число из XSUB немедленно. Использует XST_mUV.

void    XSRETURN_UV(IV uv)

XSRETURN_YES

Возвращает &PL_sv_yes из XSUB немедленно. Использует XST_mYES.

XSRETURN_YES;

XST_mIV

Помещает целое число в указанную позицию pos на стеке. Значение сохраняется в новом смертельном SV.

void    XST_mIV(int pos, IV iv)

XST_mNO

Помещает &PL_sv_no в указанную позицию pos на стеке.

void    XST_mNO(int pos)

XST_mNV

Помещает double в указанную позицию pos на стеке. Значение сохраняется в новом смертельном SV.

void    XST_mNV(int pos, NV nv)

XST_mPV

Помещает копию строки в указанную позицию pos на стеке. Значение сохраняется в новом смертельном SV.

void    XST_mPV(int pos, char* str)

XST_mUNDEF

Помещает &PL_sv_undef в указанную позицию pos на стеке.

void    XST_mUNDEF(int pos)

XST_mYES

Помещает &PL_sv_yes в указанную позицию pos на стеке.

void    XST_mYES(int pos)

Флаги SV

SVt_INVLIST

Флаг типа для скаляров. См. "svtype".

SVt_IV

Флаг типа для скаляров. См. "svtype".

SVt_NULL

Флаг типа для скаляров. См. "svtype".

SVt_NV

Флаг типа для скаляров. См. "svtype".

SVt_PV

Флаг типа для скаляров. См. "svtype".

SVt_PVAV

Флаг типа для массивов. См. "svtype".

SVt_PVCV

Флаг типа для подпрограмм. См. "svtype".

SVt_PVFM

Флаг типа для форматов. См. "svtype".

SVt_PVGV

Флаг типа для типглоб. См. "svtype".

SVt_PVHV

Флаг типа для хэшей. См. "svtype".

SVt_PVIO

Флаг типа для объектов I/O. См. "svtype".

SVt_PVIV

Флаг типа для скаляров. См. "svtype".

SVt_PVLV

Флаг типа для скаляров. См. "svtype".

SVt_PVMG

Флаг типа для скаляров. См. "svtype".

SVt_PVNV

Флаг типа для скаляров. См. "svtype".

SVt_REGEXP

Флаг типа для регулярных выражений. См. "svtype".

svtype

Перечисление флагов для типов Perl. Эти флаги находятся в файле sv.h в svtype перечислении. Проверьте эти флаги с помощью SvTYPE макроса.

Типы:

SVt_NULL
SVt_IV
SVt_NV
SVt_RV
SVt_PV
SVt_PVIV
SVt_PVNV
SVt_PVMG
SVt_INVLIST
SVt_REGEXP
SVt_PVGV
SVt_PVLV
SVt_PVAV
SVt_PVHV
SVt_PVCV
SVt_PVFM
SVt_PVIO

Проще всего их объяснить снизу вверх.

SVt_PVIO для объектов ввода-вывода, SVt_PVFM для форматов, SVt_PVCV для подпрограмм, SVt_PVHV для хэшей и SVt_PVAV для массивов.

Все остальные — скалярные типы, то есть вещи, которые могут быть привязаны к $ переменной. Для них внутренние типы в основном ортогональны типам в языке Perl.

Поэтому проверка SvTYPE(sv) < SVt_PVAV — лучший способ узнать, является ли что-то скаляром.

SVt_PVGV представляет типглоб. Если !SvFAKE(sv), то это реальный, непереводимый типглоб. Если SvFAKE(sv), то это скаляр, которому был присвоен типглоб. Присвоение ему снова прекратит его быть типглобом. SVt_PVLV представляет скаляр, который делегирует другому скаляру за кулисами. Он используется, например, для возвращаемого значения substr и для привязанных элементов хэша и массива. Он может содержать любое скалярное значение, включая типглоб. SVt_REGEXP предназначен для регулярных выражений. SVt_INVLIST предназначен только для внутреннего использования Perl.

SVt_PVMG представляет «нормальный» скаляр (не типглоб, регулярное выражение или делегат). Поскольку большинству скаляров не нужны все внутренние поля PVMG, мы экономим память, выделяя меньшие структуры, где это возможно. Все остальные типы — это просто более простые формы SVt_PVMG, с меньшим количеством внутренних полей. SVt_NULL может содержать только undef. SVt_IV может содержать undef, целое число или ссылку. (SVt_RV — псевдоним для SVt_IV, который существует для обратной совместимости.) SVt_NV может содержать любое из этих значений или double. SVt_PV может содержать только undef или строку. SVt_PVIV является супермножеством SVt_PV и SVt_IV. SVt_PVNV аналогичен. SVt_PVMG может содержать все, что может содержать SVt_PVNV, но может, но не обязательно, быть благословленным или магическим.

Функции манипулирования SV

boolSV

Возвращает SV со значением true, если b имеет значение true, или SV со значением false, если b равно 0.

См. также "PL_sv_yes" и "PL_sv_no".

SV *    boolSV(bool b)

croak_xs_usage

Специализированная версия croak() для вывода сообщения об использовании для xsubs

croak_xs_usage(cv, "eee_yow");

определяет имя пакета и подпрограммы из cv, а затем вызывает croak(). Таким образом, если cv равно &ouch::awk, он вызовет croak следующим образом:

Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
                                                    "eee_yow");

       void    croak_xs_usage(const CV *const cv,
                              const char *const params)

get_sv

Возвращает SV указанного Perl-скалярного значения. flags передаются в gv_fetchpv. Если GV_ADD установлено, и переменная Perl не существует, она будет создана. Если flags равно нулю, и переменная не существует, возвращается NULL.

ПРИМЕЧАНИЕ: perl_ версия этой функции устарела.

SV*     get_sv(const char *name, I32 flags)

looks_like_number

Проверяет, выглядит ли содержимое SV как число (или является числом). Inf и Infinity обрабатываются как числа (так что предупреждение о нечисловом значении не выдается), даже если ваше atof() их не понимает. Get-магия игнорируется.

I32     looks_like_number(SV *const sv)

newRV_inc

Создаёт обёртку RV для SV. Счётчик ссылок исходного SV увеличивается.

SV*     newRV_inc(SV* sv)

newRV_noinc

Создаёт обёртку RV для SV. Счётчик ссылок исходного SV не увеличивается.

SV*     newRV_noinc(SV *const tmpRef)

newSV

Создаёт новый SV. Неноль len параметр указывает на количество байтов предварительно выделенной области памяти для строк, которые SV должен содержать. Также выделяется дополнительный байт для заключительного NUL. (SvPOK для SV не устанавливается, даже если выделяется память для строк.) Счётчик ссылок нового SV устанавливается в 1.

В версии 5.9.3, newSV() заменяет более старую NEWSV() API и опускает первый параметр, x, вспомогательное средство отладки, которое позволяло вызывающим сторонам идентифицировать себя. Это вспомогательное средство было заменено новой опцией сборки, PERL_MEM_LOG (см. "PERL_MEM_LOG" в perlhacktips). Более старая API по-прежнему доступна для использования в модулях XS, поддерживающих более старые версии Perl.

SV*     newSV(const STRLEN len)

newSVhek

Создаёт новый SV из структуры ключа хэша. Он будет генерировать скаляры, которые указывают на общую таблицу строк, где это возможно. Возвращает новый (неопределённый) SV, если hek равно NULL.

SV*     newSVhek(const HEK *const hek)

newSViv

Создаёт новый SV и копирует в него целое число. Счётчик ссылок для SV устанавливается в 1.

SV*     newSViv(const IV i)

newSVnv

Создаёт новый SV и копирует в него значение с плавающей запятой. Счётчик ссылок для SV устанавливается в 1.

SV*     newSVnv(const NV n)

newSVpadname

Создаёт новый SV, содержащий имя блока.

SV*     newSVpadname(PADNAME *pn)

newSVpv

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символов). Счётчик ссылок для SV устанавливается в 1. Если len равно нулю, Perl вычислит длину, используя strlen(), (что означает, что если вы используете этот вариант, то s не может иметь вставленных NUL символов и должен иметь заключительный NUL байт).

Эта функция может привести к проблемам надёжности, если вы собираетесь передавать пустые строки, которые не завершены нулём, потому что она будет выполнять strlen на строке и потенциально выходить за пределы допустимой памяти.

Использование "newSVpvn" является более безопасной альтернативой для строк, не завершённых NUL. Для строковых литералов используйте "newSVpvs" вместо этого. Эта функция будет работать нормально для строк, завершенных NUL, но если вы хотите избежать проверки, вызывать ли strlen, используйте newSVpvn вместо этого (вызывая strlen самостоятельно).

SV*     newSVpv(const char *const s, const STRLEN len)

newSVpvf

Создаёт новый SV и инициализирует его строкой, отформатированной как sv_catpvf.

SV*     newSVpvf(const char *const pat, ...)

newSVpvn

Создаёт новый SV и копирует в него строку, которая может содержать NUL символы (\0) и другие двоичные данные. Счётчик ссылок для SV устанавливается в 1. Обратите внимание, что если len равно нулю, Perl создаст строку длиной ноль (Perl). Вы несёте ответственность за то, чтобы исходный буфер был не менее len байтов длиной. Если аргумент buffer равен NULL, новый SV будет неопределённым.

SV*     newSVpvn(const char *const buffer,
                 const STRLEN len)

newSVpvn_flags

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символов). Счётчик ссылок для SV устанавливается в 1. Обратите внимание, что если len равно нулю, Perl создаст строку длиной ноль. Вы несёте ответственность за то, чтобы исходная строка была не менее len байтов длиной. Если аргумент s равен NULL, новый SV будет неопределённым. В настоящее время принимаются только флаги SVf_UTF8 и SVs_TEMP. Если SVs_TEMP установлен, то sv_2mortal() вызывается на результате перед возвращением. Если SVf_UTF8 установлен, s считается кодированным в UTF-8 и SVf_UTF8 флаг будет установлен для нового SV. newSVpvn_utf8() является удобной обёрткой для этой функции, определённой как

#define newSVpvn_utf8(s, len, u)                    \
    newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)

    SV*     newSVpvn_flags(const char *const s,
                           const STRLEN len,
                           const U32 flags)

newSVpvn_share

Создаёт новый SV с его SvPVX_const, указывающим на общую строку в таблице строк. Если строка ещё не существует в таблице, она создаётся сначала. Включает SvIsCOW флаг (или READONLY и FAKE в версиях 5.16 и ранее). Если параметр hash не равен нулю, это значение используется; в противном случае вычисляется хэш. Хэш строки можно получить из SV с помощью макроса SvSHARED_HASH(). Идея заключается в том, что поскольку таблица строк используется для общих ключей хэшей, эти строки будут иметь SvPVX_const == HeKEY, и поиск по хэшу будет избегать сравнения строк.

SV*     newSVpvn_share(const char* s, I32 len, U32 hash)

newSVpvn_utf8

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символов). Если utf8 истинно, вызывает SvUTF8_on для нового SV. Реализовано как обёртка вокруг newSVpvn_flags.

SV*     newSVpvn_utf8(const char* s, STRLEN len,
                      U32 utf8)

newSVpvs

Аналогично newSVpvn, но принимает литеральную строку вместо пары строка/длина.

SV*     newSVpvs("literal string" s)

newSVpvs_flags

Аналогично newSVpvn_flags, но принимает литеральную строку вместо пары строка/длина.

SV*     newSVpvs_flags("literal string" s, U32 flags)

newSVpv_share

Аналогично newSVpvn_share, но принимает строку, завершённую NUL, вместо пары строка/длина.

SV*     newSVpv_share(const char* s, U32 hash)

newSVpvs_share

Аналогично newSVpvn_share, но принимает литеральную строку вместо пары строка/длина и опускает параметр хэша.

SV*     newSVpvs_share("literal string" s)

newSVrv

Создаёт новый SV, на который будет указывать существующий RV, rv. Если rv не является RV, он будет преобразован в него. Если classname не равен NULL, новый SV будет благословлён в указанном пакете. Возвращается новый SV, и его счётчик ссылок равен 1. Счётчик ссылок 1 принадлежит rv. См. также newRV_inc() и newRV_noinc() для правильного создания нового RV.

SV*     newSVrv(SV *const rv,
                const char *const classname)

newSVsv

Создаёт новый SV, являющийся точной копией исходного SV. (Использует sv_setsv.)

SV*     newSVsv(SV *const old)

newSVsv_nomg

Аналогично newSVsv, но не обрабатывает get-магию.

SV*     newSVsv_nomg(SV *const old)

newSV_type

Создаёт новый SV, заданного типа. Счётчик ссылок нового SV устанавливается в 1.

SV*     newSV_type(const svtype type)

newSVuv

Создаёт новый SV и копирует в него целое беззнаковое число. Счётчик ссылок для SV устанавливается в 1.

SV*     newSVuv(const UV u)

sv_2bool

Этот макрос используется только sv_true() или его макро-эквивалентом, и только если аргумент последнего не является SvPOK, SvIOK или SvNOK. Он вызывает sv_2bool_flags с флагом SV_GMAGIC.

bool    sv_2bool(SV *const sv)

sv_2bool_flags

Эта функция используется только sv_true() и т.д., и только если аргумент последнего не является SvPOK, SvIOK или SvNOK. Если флаги содержат SV_GMAGIC, то сначала выполняется mg_get().

bool    sv_2bool_flags(SV *sv, I32 flags)

sv_2cv

Используя различные методы, пытается получить CV из SV; в дополнение, если возможно, устанавливает *st и *gvp в хранилище и GV, связанные с ним. Флаги в lref передаются в gv_fetchsv.

CV*     sv_2cv(SV* sv, HV **const st, GV **const gvp,
               const I32 lref)

sv_2io

Используя различные методы, пытается получить IO из SV: слот IO, если это GV; или рекурсивный результат, если это RV; или слот IO символа, названного по PV, если это строка.

Магия 'Get' игнорируется для передаваемого sv, но будет вызвана для SvRV(sv), если sv является RV.

IO*     sv_2io(SV *const sv)

sv_2iv_flags

Возвращает целое значение SV, выполняя необходимые преобразования строк. Если flags имеет установленный бит SV_GMAGIC, выполняет mg_get() предварительно. Обычно используется через макросы SvIV(sv) и SvIVx(sv).

IV      sv_2iv_flags(SV *const sv, const I32 flags)

sv_2mortal

Помечает существующий SV как смертный. SV будет уничтожен «скоро», либо явным вызовом FREETMPS, либо неявным вызовом в местах, таких как границы операторов. SvTEMP() включён, что означает, буфер строк SV может быть «украден», если этот SV скопирован. См. также "sv_newmortal" и "sv_mortalcopy".

SV*     sv_2mortal(SV *const sv)

sv_2nv_flags

Возвращает числовое значение SV, выполнив необходимые преобразования из строки или целого числа. Если flags имеет установленный бит SV_GMAGIC, выполняет mg_get() вначале. Обычно используется через макросы SvNV(sv) и SvNVx(sv).

NV      sv_2nv_flags(SV *const sv, const I32 flags)

sv_2pvbyte

Возвращает указатель на байтовое представление SV и устанавливает *lp в его длину. Может привести к понижению кодировки SV с UTF-8 в качестве побочного эффекта.

Обычно используется через макрос SvPVbyte.

char*   sv_2pvbyte(SV *sv, STRLEN *const lp)

sv_2pvutf8

Возвращает указатель на UTF-8-представление SV и устанавливает *lp в его длину. Может привести к повышению кодировки SV до UTF-8 в качестве побочного эффекта.

Обычно используется через макрос SvPVutf8.

char*   sv_2pvutf8(SV *sv, STRLEN *const lp)

sv_2pv_flags

Возвращает указатель на строковое значение SV и устанавливает *lp в его длину. Если в флагах установлен бит SV_GMAGIC, выполняет mg_get() вначале. Преобразует sv в строку при необходимости. Обычно вызывается через макрос SvPV_flags . sv_2pv() и sv_2pv_nomg обычно также оказываются здесь.

char*   sv_2pv_flags(SV *const sv, STRLEN *const lp,
                     const I32 flags)

sv_2uv_flags

Возвращает целое беззнаковое значение SV, выполнив необходимые преобразования из строки. Если flags имеет установленный бит SV_GMAGIC, выполняет mg_get() вначале. Обычно используется через макросы SvUV(sv) и SvUVx(sv).

UV      sv_2uv_flags(SV *const sv, const I32 flags)

sv_backoff

Удаляет любой смещение строки. Обычно следует использовать макрос-обёртку SvOOK_off.

void    sv_backoff(SV *const sv)

sv_bless

Присваивает SV указанному пакету. SV должен быть RV. Пакет должен быть обозначен своим хранилищем (см. "gv_stashpv"). Счётчик ссылок SV не затрагивается.

SV*     sv_bless(SV *const sv, HV *const stash)

sv_catpv

Конкатенирует строку, завершённую NUL, в конец строки, которая находится в SV. Если у SV установлен флаг UTF-8, то добавляемые байты должны быть валидным UTF-8. Обрабатывает магию 'get', но не 'set'. См. "sv_catpv_mg".

void    sv_catpv(SV *const sv, const char* ptr)

sv_catpvf

Обрабатывает свои аргументы как sprintf, и добавляет отформатированный вывод в SV. Как и sv_vcatpvfn с ненулевым списком аргументов C-стиля, переупорядочивание аргументов не поддерживается. Если добавленные данные содержат «широкие» символы (включая, но не ограничиваясь, SVs с UTF-8 PV, отформатированными с помощью %s, и символами >255, отформатированными с помощью %c), исходный SV может быть преобразован в UTF-8. Обрабатывает магию 'get', но не 'set'. См. "sv_catpvf_mg". Если исходный SV был UTF-8, шаблон должен быть валидным UTF-8; если исходный SV был байтами, шаблон также должен быть.

void    sv_catpvf(SV *const sv, const char *const pat,
                  ...)

sv_catpvf_mg

Подобно sv_catpvf, но также обрабатывает магию 'set'.

void    sv_catpvf_mg(SV *const sv,
                     const char *const pat, ...)

sv_catpvn

Конкатенирует строку в конец строки, которая находится в SV. len указывает количество байт для копирования. Если у SV установлен флаг UTF-8, то добавляемые байты должны быть валидным UTF-8. Обрабатывает магию 'get', но не 'set'. См. "sv_catpvn_mg".

void    sv_catpvn(SV *dsv, const char *sstr, STRLEN len)

sv_catpvn_flags

Конкатенирует строку в конец строки, которая находится в SV. len указывает количество байт для копирования.

По умолчанию предполагается, что добавляемая строка является валидным UTF-8, если у SV установлен флаг UTF-8, и строкой байтов в противном случае. Можно заставить интерпретировать добавляемую строку как UTF-8, предоставив флаг SV_CATUTF8, и как байты, предоставив флаг SV_CATBYTES; SV или добавленная строка будут преобразованы в UTF-8 при необходимости.

Если flags имеет установленный бит SV_SMAGIC, будет вызвано mg_set по dsv впоследствии, если это необходимо. sv_catpvn и sv_catpvn_nomg реализованы через эту функцию.

void    sv_catpvn_flags(SV *const dstr,
                        const char *sstr,
                        const STRLEN len,
                        const I32 flags)

sv_catpvn_nomg

Подобно sv_catpvn, но не обрабатывает магию.

void    sv_catpvn_nomg(SV* sv, const char* ptr,
                       STRLEN len)

sv_catpvs

Подобно sv_catpvn, но принимает строку вместо пары строка/длина.

void    sv_catpvs(SV* sv, "literal string" s)

sv_catpvs_flags

Подобно sv_catpvn_flags, но принимает строку вместо пары строка/длина.

void    sv_catpvs_flags(SV* sv, "literal string" s,
                        I32 flags)

sv_catpvs_mg

Подобно sv_catpvn_mg, но принимает строку вместо пары строка/длина.

void    sv_catpvs_mg(SV* sv, "literal string" s)

sv_catpvs_nomg

Подобно sv_catpvn_nomg, но принимает строку вместо пары строка/длина.

void    sv_catpvs_nomg(SV* sv, "literal string" s)

sv_catpv_flags

Конкатенирует строку, завершённую NUL, в конец строки, которая находится в SV. Если у SV установлен флаг UTF-8, то добавляемые байты должны быть валидным UTF-8. Если flags имеет установленный бит SV_SMAGIC, будет вызвана mg_set на изменённом SV, если это необходимо.

void    sv_catpv_flags(SV *dstr, const char *sstr,
                       const I32 flags)

sv_catpv_mg

Подобно sv_catpv, но также обрабатывает магию 'set'.

void    sv_catpv_mg(SV *const sv, const char *const ptr)

sv_catpv_nomg

Подобно sv_catpv но не обрабатывает магию.

void    sv_catpv_nomg(SV* sv, const char* ptr)

sv_catsv

Конкатенирует строку из SV ssv в конец строки в SV dsv. Если ssv равно нулю, ничего не делает; в противном случае изменяет только dsv. Обрабатывает магию 'get' для обоих SV, но не 'set'. См. "sv_catsv_mg" и "sv_catsv_nomg".

void    sv_catsv(SV *dstr, SV *sstr)

sv_catsv_flags

Конкатенирует строку из SV ssv в конец строки в SV dsv. Если ssv равно нулю, ничего не делает; в противном случае изменяет только dsv. Если flags имеет установленный бит SV_GMAGIC, вызовёт mg_get для обоих SV, если это необходимо. Если flags имеет установленный бит SV_SMAGIC, mg_set будет вызван для изменённого SV, если это необходимо. sv_catsv, sv_catsv_nomg, и sv_catsv_mg реализованы через эту функцию.

void    sv_catsv_flags(SV *const dsv, SV *const ssv,
                       const I32 flags)

sv_catsv_nomg

Подобно sv_catsv, но не обрабатывает магию.

void    sv_catsv_nomg(SV* dsv, SV* ssv)

sv_chop

Эффективное удаление символов из начала буфера строк. SvPOK(sv), или по крайней мере SvPOKp(sv), должно быть истинным и ptr должен быть указателем на место внутри буфера строк. ptr становится первым символом скорректированной строки. Использует OOK обходной путь. По возвращении, только SvPOK(sv) и SvPOKp(sv) из флагов OK будут истинными.

Внимание: после возврата этой функции, ptr и SvPVX_const(sv) могут больше не ссылаться на один и тот же кусок данных.

Несчастливое сходство имени этой функции с оператором Perl's chop является строго случайным. Эта функция работает слева направо; chop работает справа налево.

void    sv_chop(SV *const sv, const char *const ptr)

sv_clear

Очистка SV: вызов любых деструкторов, освобождение памяти, используемой телом, и освобождение самого тела. Заголовок SV не освобождается, хотя его тип устанавливается в все единицы, чтобы он не был непреднамеренно принят за живой во время глобального уничтожения и т.д. Эту функцию следует вызывать только когда REFCNT равно нулю. В большинстве случаев вы захотите вызвать sv_free() (или её макрос-обёртку SvREFCNT_dec).

void    sv_clear(SV *const orig_sv)

sv_cmp

Сравнение строк в двух SV. Возвращает -1, 0 или 1, указывая, меньше ли, равно ли или больше ли строка в sv1 строки в sv2. Учитывает UTF-8 и 'use bytes', обрабатывает магию get и преобразует аргументы в строки при необходимости. См. также "sv_cmp_locale".

I32     sv_cmp(SV *const sv1, SV *const sv2)

sv_cmp_flags

Сравнение строк в двух SV. Возвращает -1, 0 или 1, указывая, меньше ли, равно ли или больше ли строка в sv1 строки в sv2. Учитывает UTF-8 и 'use bytes', и преобразует аргументы в строки при необходимости. Если в флагах установлен бит SV_GMAGIC, обрабатывает магию get. См. также "sv_cmp_locale_flags".

I32     sv_cmp_flags(SV *const sv1, SV *const sv2,
                     const U32 flags)

sv_cmp_locale

Сравнение строк в двух SV с учётом локали. Учитывает UTF-8 и 'use bytes', обрабатывает магию get и преобразует аргументы в строки при необходимости. См. также "sv_cmp".

I32     sv_cmp_locale(SV *const sv1, SV *const sv2)

sv_cmp_locale_flags

Сравнение строк в двух SV с учётом локали. Учитывает UTF-8 и 'use bytes' и преобразует аргументы в строки при необходимости. Если в флагах содержится SV_GMAGIC, обрабатывает магию get. См. также "sv_cmp_flags".

I32     sv_cmp_locale_flags(SV *const sv1,
                            SV *const sv2,
                            const U32 flags)

sv_collxfrm

Этот вызов sv_collxfrm_flags с флагом SV_GMAGIC. См. "sv_collxfrm_flags".

char*   sv_collxfrm(SV *const sv, STRLEN *const nxp)

sv_collxfrm_flags

END_OF_DOCUMENT_MARKER

Добавляет магию преобразования Collate Transform в SV, если её там ещё нет. Если флаги содержат SV_GMAGIC, выполняется обработка get-магии.

Любая скалярная переменная может содержать магию PERL_MAGIC_collxfrm, содержащую скалярные данные переменной, но преобразованные в формат, позволяющий использовать обычное сравнение памяти для сравнения данных в соответствии с настройками локали.

char*   sv_collxfrm_flags(SV *const sv,
                          STRLEN *const nxp,
                          I32 const flags)

sv_copypv

Копирует строковое представление исходного SV в целевой SV. Автоматически выполняет все необходимые mg_get и приведение численных значений к строкам. Гарантирует сохранение флага UTF8 даже для перегруженных объектов. Похож по своей природе на sv_2pv[_flags], но работает непосредственно со SV, а не только со строкой. В основном использует sv_2pv_flags для выполнения своей работы, за исключением случаев, когда это привело бы к потере UTF-8-ности PV.

void    sv_copypv(SV *const dsv, SV *const ssv)

sv_copypv_flags

Реализация sv_copypv и sv_copypv_nomg. Вызывает get-магию, если в флагах установлен бит SV_GMAGIC.

void    sv_copypv_flags(SV *const dsv, SV *const ssv,
                        const I32 flags)

sv_copypv_nomg

Аналогично sv_copypv, но не вызывает get-магию предварительно.

void    sv_copypv_nomg(SV *const dsv, SV *const ssv)

SvCUR

Возвращает длину строки, находящейся в SV. См. "SvLEN".

STRLEN  SvCUR(SV* sv)

SvCUR_set

Устанавливает текущую длину строки, находящейся в SV. См. "SvCUR" и SvIV_set>.

void    SvCUR_set(SV* sv, STRLEN len)

sv_dec

Автоматическое уменьшение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает магию 'get' и перегрузку операторов.

void    sv_dec(SV *const sv)

sv_dec_nomg

Автоматическое уменьшение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает перегрузку операторов. Пропускает обработку 'get'-магии.

void    sv_dec_nomg(SV *const sv)

sv_derived_from

Точно так же, как "sv_derived_from_pv", но не принимает параметр flags.

bool    sv_derived_from(SV* sv, const char *const name)

sv_derived_from_pv

Точно так же, как "sv_derived_from_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

bool    sv_derived_from_pv(SV* sv,
                           const char *const name,
                           U32 flags)

sv_derived_from_pvn

Возвращает булево значение, указывающее, является ли SV производным от указанного класса на уровне C. Чтобы проверить производное на уровне Perl, вызовите isa() как обычный перл-метод.

В настоящее время единственное значимое значение для flags — это SVf_UTF8.

bool    sv_derived_from_pvn(SV* sv,
                            const char *const name,
                            const STRLEN len, U32 flags)

sv_derived_from_sv

Точно так же, как "sv_derived_from_pvn", но принимает имя строки в виде SV вместо пары строка/длина.

bool    sv_derived_from_sv(SV* sv, SV *namesv,
                           U32 flags)

sv_does

Аналогично "sv_does_pv", но не принимает параметр flags.

bool    sv_does(SV* sv, const char *const name)

sv_does_pv

Аналогично "sv_does_sv", но принимает строку с нулевым завершением вместо SV.

bool    sv_does_pv(SV* sv, const char *const name,
                   U32 flags)

sv_does_pvn

Аналогично "sv_does_sv", но принимает пару строка/длина вместо SV.

bool    sv_does_pvn(SV* sv, const char *const name,
                    const STRLEN len, U32 flags)

sv_does_sv

Возвращает булево значение, указывающее, выполняет ли SV определённую, именованную роль. SV может быть перл-объектом или именем перл-класса.

bool    sv_does_sv(SV* sv, SV* namesv, U32 flags)

SvEND

Возвращает указатель на позицию сразу после последнего символа в строке, находящейся в SV, где обычно находится завершающий символ NUL (хотя перл-скаляры его строго не требуют). См. "SvCUR". Доступ к символу как *(SvEND(sv)).

Предупреждение: Если SvCUR равно SvLEN, то SvEND указывает на невыделенную память.

char*   SvEND(SV* sv)

sv_eq

Возвращает булево значение, указывающее, идентичны ли строки в двух SV. Поддерживает UTF-8 и 'use bytes', обрабатывает get-магию и приведёт аргументы к строкам при необходимости.

I32     sv_eq(SV* sv1, SV* sv2)

sv_eq_flags

Возвращает булево значение, указывающее, идентичны ли строки в двух SV. Поддерживает UTF-8 и 'use bytes', приведёт аргументы к строкам при необходимости. Если в флагах установлен бит SV_GMAGIC, то также обрабатывает get-магию.

I32     sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)

sv_force_normal_flags

Отменяет различные виды фальсификаций в SV, где фальсификация означает "больше, чем" строка: если PV — это общая строка, создайте частную копию; если мы — ссылка, прекратите ссылаться; если мы — шаблон, понизьте до xpvmg; если мы — скаляр с копированием при записи, это время записи, когда мы делаем копию, и также используется локально; если это v-строка, сбросьте магию v-строки. Если SV_COW_DROP_PV установлен, то скаляр с копированием при записи сбрасывает буфер PV (если таковой имеется) и становится SvPOK_off, а не создаёт копию. (Используется, когда этот скаляр собираются установить в другое значение.) Кроме того, параметр flags передаётся в sv_unref_flags() при разрыве ссылки. sv_force_normal вызывает эту функцию с флагами, установленными в 0.

Ожидается, что эта функция будет использоваться для сигнализации перлу, что этот SV собираются изменить, и нужно позаботиться обо всех дополнительных записях. Следовательно, она даёт ошибку для значений только для чтения.

void    sv_force_normal_flags(SV *const sv,
                              const U32 flags)

sv_free

Уменьшает счётчик ссылок SV, и если он падает до нуля, вызывает sv_clear, чтобы вызвать деструкторы и освободить всю используемую память; и, наконец, освобождает сам заголовок SV. Обычно вызывается через оберточную макрос SvREFCNT_dec.

void    sv_free(SV *const sv)

SvGAMAGIC

Возвращает true, если SV имеет get-магию или перегрузку. Если хотя бы одно из них верно, то скаляр является активными данными и потенциально может возвращать новое значение каждый раз при обращении. Поэтому необходимо быть осторожным, чтобы читать его только один раз на логическую операцию пользователя и работать с возвращённым значением. Если ни одно из них не верно, то значение скаляра не может измениться, пока ему не присвоят новое.

U32     SvGAMAGIC(SV* sv)

sv_gets

Получает строку из дескриптора файла и сохраняет её в SV, необязательно добавляя к текущей сохранённой строке. Если append не равно 0, строка добавляется к SV вместо перезаписи. append должен быть установлен в байтовый смещение, с которого должна начинаться добавленная строка в SV (как правило, SvCUR(sv) является подходящим выбором).

char*   sv_gets(SV *const sv, PerlIO *const fp,
                I32 append)

sv_get_backrefs

Если sv является целью слабой ссылки, то возвращает структуру обратных ссылок, связанную с sv; в противном случае возвращает NULL.

Когда возвращается ненулевое значение, тип возвращаемого значения имеет значение. Если это AV, то элементы AV — это слабые ссылки RV, указывающие на этот элемент. Если это любой другой тип, то сам элемент является слабой ссылкой.

См. также Perl_sv_add_backref(), Perl_sv_del_backref(), Perl_sv_kill_backrefs()

SV*     sv_get_backrefs(SV *const sv)

SvGROW

Расширяет буфер символов в SV, чтобы он мог вместить указанное количество байтов (не забудьте зарезервировать место для дополнительного завершающего символа NUL). Вызывает sv_grow для выполнения расширения, если необходимо. Возвращает указатель на буфер символов. SV должен быть типа >= SVt_PV. В качестве альтернативы можно вызвать sv_grow, если вы не уверены в типе SV.

Вы можете ошибочно думать, что len — это количество байтов, добавляемых к существующему размеру, но на самом деле это общий размер, который должен быть у sv.

char *  SvGROW(SV* sv, STRLEN len)

sv_grow

Расширяет буфер символов в SV. При необходимости использует sv_unref и повышает SV до SVt_PV. Возвращает указатель на буфер символов. Используйте оберточную функцию SvGROW вместо этого.

char*   sv_grow(SV *const sv, STRLEN newlen)

sv_inc

Автоматическое увеличение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает магию 'get' и перегрузку операторов.

void    sv_inc(SV *const sv)

sv_inc_nomg

Автоматическое увеличение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает перегрузку операторов. Пропускает обработку 'get'-магии.

void    sv_inc_nomg(SV *const sv)

sv_insert

Вставляет и/или заменяет строку в указанном смещении/длине в SV. Аналогично перл-функции substr(), где littlelen байтов, начиная с little, заменяют len байтов строки в bigstr , начиная с offset. Обрабатывает get-магию.

void    sv_insert(SV *const bigstr, const STRLEN offset,
                  const STRLEN len,
                  const char *const little,
                  const STRLEN littlelen)

sv_insert_flags

То же, что и sv_insert, но дополнительные flags передаются в SvPV_force_flags, которая применяется к bigstr.

void    sv_insert_flags(SV *const bigstr,
                        const STRLEN offset,
                        const STRLEN len,
                        const char *little,
                        const STRLEN littlelen,
                        const U32 flags)

SvIOK

Возвращает значение U32, указывающее, содержит ли SV целое число.

U32     SvIOK(SV* sv)

SvIOK_notUV

Возвращает булево значение, указывающее, содержит ли SV целое число со знаком.

bool    SvIOK_notUV(SV* sv)

SvIOK_off

Сбрасывает статус IV для SV.

void    SvIOK_off(SV* sv)

SvIOK_on

Указывает SV, что это целое число.

void    SvIOK_on(SV* sv)

SvIOK_only

Указывает SV, что это целое число и отключает все остальные биты OK.

void    SvIOK_only(SV* sv)

SvIOK_only_UV

Указывает SV, что это целое без знака и отключает все остальные биты OK.

void    SvIOK_only_UV(SV* sv)

SvIOKp

Возвращает значение U32, указывающее, содержит ли SV целое число. Проверяет приватное значение. Используйте SvIOK вместо этого.

U32     SvIOKp(SV* sv)

SvIOK_UV

Возвращает булево значение, указывающее, содержит ли SV целое число, которое должно интерпретироваться как беззнаковое. Неотрицательное целое число, значение которого находится в диапазоне как IV, так и UV, может быть помечено как SvUOK или SVIOK.

bool    SvIOK_UV(SV* sv)

sv_isa

Возвращает булево значение, указывающее, благословлен ли SV в указанный класс. Это не проверяет подтипы; используйте sv_derived_from для проверки отношения наследования.

int     sv_isa(SV* sv, const char *const name)

SvIsCOW

Возвращает значение U32, указывающее, является ли SV Copy-On-Write (либо общий ключ хэша скаляров, либо полный Copy On Write скаляров, если для COW настроено 5.9.0).

U32     SvIsCOW(SV* sv)

SvIsCOW_shared_hash

Возвращает булево значение, указывающее, является ли SV Copy-On-Write общим скаляром ключа хэша.

bool    SvIsCOW_shared_hash(SV* sv)

sv_isobject

Возвращает булево значение, указывающее, является ли SV RV, указывающим на благословленный объект. Если SV не является RV или объект не благословлен, то возвращает false.

int     sv_isobject(SV* sv)

SvIV

Преобразует данный SV в IV и возвращает его. Возвращаемое значение во многих случаях будет храниться в слоте IV sv, но не во всех. (Используйте "sv_setiv" для гарантированной записи).

См. "SvIVx" для версии, которая гарантирует оценку sv только один раз.

IV      SvIV(SV* sv)

SvIV_nomg

Как SvIV, но не обрабатывает магию.

IV      SvIV_nomg(SV* sv)

SvIV_set

Устанавливает значение указателя IV в sv на val. Возможна реализация той же функции с присваиванием по ссылке к SvIVX. Однако, с будущими версиями Perl будет более эффективным использование SvIV_set вместо присваивания по ссылке к SvIVX.

void    SvIV_set(SV* sv, IV val)

SvIVX

Возвращает исходное значение в слоте IV SV без проверок и преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvIV".

IV      SvIVX(SV* sv)

SvIVx

Эта форма гарантирует, что sv будет вычислено только один раз. Используйте только если sv — это выражение со побочными эффектами; в противном случае используйте более эффективную функцию SvIV.

IV      SvIVx(SV* sv)

SvLEN

Возвращает размер буфера строки в SV, не включая части, относящиеся к SvOOK. См. "SvCUR".

STRLEN  SvLEN(SV* sv)

sv_len

Возвращает длину строки в SV. Обрабатывает магию и приведение типов, а также соответствующим образом устанавливает флаг UTF8. См. также "SvCUR", который предоставляет прямой доступ к слоту xpv_cur.

STRLEN  sv_len(SV *const sv)

SvLEN_set

Устанавливает размер буфера строки для SV. См. "SvLEN".

void    SvLEN_set(SV* sv, STRLEN len)

sv_len_utf8

Возвращает количество символов в строке в SV, считая широкие байты UTF-8 как один символ. Обрабатывает магию и приведение типов.

STRLEN  sv_len_utf8(SV *const sv)

sv_magic

Добавляет магию к SV. В первую очередь повышает sv до типа SVt_PVMG, если необходимо, затем добавляет новый элемент магии типа how в начало списка магии.

См. "sv_magicext" (которое sv_magic теперь вызывает) для описания обработки аргументов name и namlen.

Для добавления магии к SvREADONLY SV и добавления более одного экземпляра той же how необходимо использовать sv_magicext.

void    sv_magic(SV *const sv, SV *const obj,
                 const int how, const char *const name,
                 const I32 namlen)

sv_magicext

Добавляет магию к SV, повышая его тип при необходимости. Применяет предоставленный vtable и возвращает указатель на добавленную магию.

Обратите внимание, что sv_magicext позволит сделать то, что sv_magic не позволит. В частности, вы можете добавить магию к SvREADONLY SV и добавить более одного экземпляра той же how.

Если namlen больше нуля, то выполняется копирование name, если namlen равно нулю, то name сохраняется как есть, и - как еще один особый случай - если (name && namlen == HEf_SVKEY), то name предполагается содержать SV* и сохраняется как есть, с увеличенным REFCNT.

(Теперь это используется в качестве подпрограммы sv_magic.)

MAGIC * sv_magicext(SV *const sv, SV *const obj,
                    const int how,
                    const MGVTBL *const vtbl,
                    const char *const name,
                    const I32 namlen)

SvMAGIC_set

Устанавливает значение указателя MAGIC в sv на val. См. "SvIV_set".

void    SvMAGIC_set(SV* sv, MAGIC* val)

sv_mortalcopy

Создаёт новый SV, являющийся копией исходного SV (используя sv_setsv). Новый SV помечается как временный. Он будет уничтожен «вскоре», либо явным вызовом FREETMPS, либо неявным вызовом в точках, таких как границы операторов. См. также "sv_newmortal" и "sv_2mortal".

SV*     sv_mortalcopy(SV *const oldsv)

sv_newmortal

Создаёт новый нулевой SV, который является временным. Счётчик ссылок SV установлен в 1. Он будет уничтожен «вскоре», либо явным вызовом FREETMPS, либо неявным вызовом в точках, таких как границы операторов. См. также "sv_mortalcopy" и "sv_2mortal".

SV*     sv_newmortal()

sv_newref

Увеличивает счётчик ссылок SV. Используйте обёртку SvREFCNT_inc() вместо неё.

SV*     sv_newref(SV *const sv)

SvNIOK

Возвращает значение U32, указывающее, содержит ли SV число, целое число или двойное значение.

U32     SvNIOK(SV* sv)

SvNIOK_off

Сбрасывает состояние NV/IV для SV.

void    SvNIOK_off(SV* sv)

SvNIOKp

Возвращает значение U32, указывающее, содержит ли SV число, целое число или двойное значение. Проверяет значение private. Используйте SvNIOK вместо этого.

U32     SvNIOKp(SV* sv)

SvNOK

Возвращает значение U32, указывающее, содержит ли SV двойное значение.

U32     SvNOK(SV* sv)

SvNOK_off

Сбрасывает состояние NV для SV.

void    SvNOK_off(SV* sv)

SvNOK_on

Указывает SV, что он представляет собой двойное значение.

void    SvNOK_on(SV* sv)

SvNOK_only

Указывает SV, что он представляет собой двойное значение, и отключает все остальные биты OK.

void    SvNOK_only(SV* sv)

SvNOKp

Возвращает значение U32, указывающее, содержит ли SV двойное значение. Проверяет значение private. Используйте SvNOK вместо этого.

U32     SvNOKp(SV* sv)

SvNV

Преобразует данный SV в NV и возвращает его. Возвращаемое значение во многих случаях будет храниться в слоте NV sv, но не во всех. (Используйте "sv_setnv" для гарантированной записи).

См. "SvNVx" для версии, гарантирующей оценку sv только один раз.

NV      SvNV(SV* sv)

SvNV_nomg

Как SvNV, но не обрабатывает магию.

NV      SvNV_nomg(SV* sv)

SvNV_set

Устанавливает значение указателя NV в sv на val. См. "SvIV_set".

void    SvNV_set(SV* sv, NV val)

SvNVX

Возвращает исходное значение в слоте NV SV без проверок и преобразований. Используйте только когда уверены, что SvNOK истинно. См. также "SvNV".

NV      SvNVX(SV* sv)

SvNVx

NV      SvNVx(SV* sv)

SvOK

Возвращает значение U32, указывающее, определено ли значение. Это имеет смысл только для скаляров.

U32     SvOK(SV* sv)

SvOOK

Возвращает U32, указывающее, смещён ли указатель на буфер строки. Эта уловка используется во внутренней работе для ускорения удаления символов из начала SvPV. Когда SvOOK истинно, начало выделенного буфера строки фактически расположено на SvOOK_offset() байт раньше SvPVX. Раньше этот смещение хранилось в SvIVX, но теперь оно хранится в резервированной части буфера.

U32     SvOOK(SV* sv)

SvOOK_offset

Читает в len смещение от SvPVX до истинного начала выделенного буфера, которое будет отличным от нуля, если sv_chop использовалось для эффективного удаления символов из начала буфера. Реализовано как макрос, который принимает адрес len, который должен иметь тип STRLEN. Вычисляет sv более одного раза. Устанавливает len в 0, если SvOOK(sv) ложно.

void    SvOOK_offset(SV*sv, STRLEN len)

SvPOK

Возвращает значение U32, указывающее, содержит ли SV строку символов.

U32     SvPOK(SV* sv)

SvPOK_off

Сбрасывает состояние PV для SV.

void    SvPOK_off(SV* sv)

SvPOK_on

Указывает SV, что он представляет собой строку.

void    SvPOK_on(SV* sv)

SvPOK_only

Указывает SV, что он представляет собой строку и отключает все остальные биты OK. Также отключит статус UTF-8.

void    SvPOK_only(SV* sv)

SvPOK_only_UTF8

Указывает SV, что он представляет собой строку и отключает все остальные биты OK, оставив статус UTF-8 неизменным.

void    SvPOK_only_UTF8(SV* sv)

SvPOKp

Возвращает значение U32, указывающее, содержит ли SV строку символов. Проверяет значение private. Используйте SvPOK вместо этого.

U32     SvPOKp(SV* sv)

sv_pos_b2u

Преобразует значение, на которое указывает offsetp, из счётчика байтов от начала строки в эквивалентное количество символов UTF-8. Обрабатывает магию и приведение типов.

Вместо этого используйте sv_pos_b2u_flags, которая правильно обрабатывает строки длиной более 2 Гб.

void    sv_pos_b2u(SV *const sv, I32 *const offsetp)

sv_pos_b2u_flags

Преобразует offset из количества байтов с начала строки в количество эквивалентных символов UTF-8. Обрабатывает приведение типов. flags передается в SvPV_flags, и обычно должно быть SV_GMAGIC|SV_CONST_RETURN для обработки магических функций.

STRLEN  sv_pos_b2u_flags(SV *const sv,
                         STRLEN const offset, U32 flags)

sv_pos_u2b

Преобразует значение, на которое указывает offsetp из количества символов UTF-8 с начала строки в количество эквивалентных байтов; если lenp не равно нулю, то делает то же самое для lenp, но на этот раз начиная со смещения, а не с начала строки. Обрабатывает магические функции и приведение типов.

Используйте sv_pos_u2b_flags в качестве предпочтительного варианта, который правильно обрабатывает строки длиннее 2 Гб.

void    sv_pos_u2b(SV *const sv, I32 *const offsetp,
                   I32 *const lenp)

sv_pos_u2b_flags

Преобразует смещение из количества символов UTF-8 с начала строки в количество эквивалентных байтов; если lenp не равно нулю, то делает то же самое для lenp, но на этот раз начиная со offset, а не с начала строки. Обрабатывает приведение типов. flags передается в SvPV_flags, и обычно должно быть SV_GMAGIC|SV_CONST_RETURN для обработки магических функций.

STRLEN  sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
                         STRLEN *const lenp, U32 flags)

SvPV

Возвращает указатель на строку в SV или строковое представление SV, если SV не содержит строку. SV может кэшировать строковое представление, становясь SvPOK. Обрабатывает магические функции 'get'. Переменная len будет установлена в длину строки (это макрос, поэтому не используйте &len). Также см. "SvPVx" для версии, гарантирующей, что sv будет вычислено только один раз.

Обратите внимание, что нет гарантии, что возвращаемое значение SvPV() равно SvPVX(sv), или что SvPVX(sv) содержит корректные данные, или что последовательные вызовы SvPV(sv) каждый раз будут возвращать одно и то же значение указателя. Это связано с тем, как обрабатываются такие вещи, как перегрузка и Copy-On-Write. В этих случаях возвращаемое значение может указывать на временный буфер или что-то подобное. Если вам абсолютно необходимо, чтобы поле SvPVX было действительным (например, если вы намерены записывать в него), см. "SvPV_force".

char*   SvPV(SV* sv, STRLEN len)

SvPVbyte

Аналогично SvPV, но сначала преобразует sv в представление в байтах, если необходимо.

char*   SvPVbyte(SV* sv, STRLEN len)

SvPVbyte_force

Аналогично SvPV_force, но сначала преобразует sv в представление в байтах, если необходимо.

char*   SvPVbyte_force(SV* sv, STRLEN len)

SvPVbyte_nolen

Аналогично SvPV_nolen, но сначала преобразует sv в представление в байтах, если необходимо.

char*   SvPVbyte_nolen(SV* sv)

sv_pvbyten_force

Бэкенд для макроса SvPVbytex_force. Всегда используйте макрос вместо него.

char*   sv_pvbyten_force(SV *const sv, STRLEN *const lp)

SvPVbytex

Аналогично SvPV, но сначала преобразует sv в представление в байтах, если необходимо. Гарантирует, что sv будет вычислено только один раз; в противном случае используйте более эффективный SvPVbyte.

char*   SvPVbytex(SV* sv, STRLEN len)

SvPVbytex_force

Аналогично SvPV_force, но сначала преобразует sv в представление в байтах, если необходимо. Гарантирует, что sv будет вычислено только один раз; в противном случае используйте более эффективный SvPVbyte_force.

char*   SvPVbytex_force(SV* sv, STRLEN len)

SvPVCLEAR

Обеспечивает, что sv - это SVt_PV, что его SvCUR равен 0 и что он правильно завершается нулём. Эквивалентно sv_setpvs(""), но более эффективно.

char *  SvPVCLEAR(SV* sv)

SvPV_force

Аналогично SvPV, но принудительно преобразует SV в строку (SvPOK) и только в строку (SvPOK_only) любым способом. Вам нужна принудительная обработка, если вы собираетесь обновлять SvPVX непосредственно. Обрабатывает магические функции 'get'.

Обратите внимание, что принудительное преобразование произвольного скалярного значения в обычный PV может потенциально удалить полезные данные из него. Например, если SV был SvROK, то ссылка будет иметь уменьшенное значение счётчика ссылок, а сам SV может быть преобразован в скаляр SvPOK со строковым буфером, содержащим значение, например, "ARRAY(0x1234)".

char*   SvPV_force(SV* sv, STRLEN len)

SvPV_force_nomg

Аналогично SvPV_force, но не обрабатывает магические функции 'get'.

char*   SvPV_force_nomg(SV* sv, STRLEN len)

SvPV_nolen

Аналогично SvPV, но не устанавливает переменную длины.

char*   SvPV_nolen(SV* sv)

SvPV_nomg

Аналогично SvPV, но не обрабатывает магические функции.

char*   SvPV_nomg(SV* sv, STRLEN len)

SvPV_nomg_nolen

Аналогично SvPV_nolen, но не обрабатывает магические функции.

char*   SvPV_nomg_nolen(SV* sv)

sv_pvn_force

Получение осмысленной строки из SV каким-либо способом. Закрытая реализация макроса SvPV_force для компиляторов, которые не справляются со сложными выражениями макроса. Всегда используйте макрос вместо него.

char*   sv_pvn_force(SV* sv, STRLEN* lp)

sv_pvn_force_flags

Получение осмысленной строки из SV каким-либо способом. Если у flags установлен бит SV_GMAGIC, то mg_get на sv, в противном случае - нет. sv_pvn_force и sv_pvn_force_nomg реализованы с помощью этой функции. Обычно вы хотите использовать различные обертки-макросы: см. "SvPV_force" и "SvPV_force_nomg".

char*   sv_pvn_force_flags(SV *const sv,
                           STRLEN *const lp,
                           const I32 flags)

SvPV_set

Вероятно, вы не хотите использовать эту функцию, вам, скорее всего, потребуются "sv_usepvn_flags" или "sv_setpvn" или "sv_setpvs".

Устанавливает значение указателя PV в sv на завершающуюся нулём строку val, выделенную Perl. См. также "SvIV_set".

Не забудьте освободить предыдущий буфер PV. Есть много вещей, которые нужно проверить. Будьте осторожны, так как существующий указатель может быть вовлечён в копирование при записи или другой непредсказуемости, поэтому выполните SvOOK_off(sv) и используйте sv_force_normal или SvPV_force (или проверьте флаг SvIsCOW) сначала, чтобы убедиться, что это изменение безопасно. Затем, наконец, если это не COW, вызовите SvPV_free для освобождения предыдущего буфера PV.

void    SvPV_set(SV* sv, char* val)

SvPVutf8

Аналогично SvPV, но сначала преобразует sv в UTF-8, если необходимо.

char*   SvPVutf8(SV* sv, STRLEN len)

sv_pvutf8n_force

Бэкенд для макроса SvPVutf8x_force. Всегда используйте макрос вместо него.

char*   sv_pvutf8n_force(SV *const sv, STRLEN *const lp)

SvPVutf8x

Аналогично SvPV, но сначала преобразует sv в UTF-8, если необходимо. Гарантирует, что sv будет вычислено только один раз; в противном случае используйте более эффективный SvPVutf8.

char*   SvPVutf8x(SV* sv, STRLEN len)

SvPVutf8x_force

Аналогично SvPV_force, но сначала преобразует sv в UTF-8, если необходимо. Гарантирует, что sv будет вычислено только один раз; в противном случае используйте более эффективный SvPVutf8_force.

char*   SvPVutf8x_force(SV* sv, STRLEN len)

SvPVutf8_force

Аналогично SvPV_force, но сначала преобразует sv в UTF-8, если необходимо.

char*   SvPVutf8_force(SV* sv, STRLEN len)

SvPVutf8_nolen

Аналогично SvPV_nolen, но сначала преобразует sv в UTF-8, если необходимо.

char*   SvPVutf8_nolen(SV* sv)

SvPVX

Возвращает указатель на физическую строку в SV. SV должен содержать строку. До версии 5.9.3 этот макрос не является безопасным для использования, если тип SV не >= SVt_PV.

Также используется для хранения имени автоматически загруженной подпрограммы в процедуре XS AUTOLOAD. См. "Загрузка по мере необходимости с помощью XSUB" в perlguts.

char*   SvPVX(SV* sv)

SvPVx

Версия SvPV, гарантирующая, что sv будет вычислено только один раз. Используйте только в том случае, если sv является выражением с побочными эффектами; в противном случае используйте более эффективный SvPV.

char*   SvPVx(SV* sv, STRLEN len)

SvREADONLY

Возвращает true, если аргумент является только для чтения, в противном случае возвращает false. Доступно для кода Perl через Internals::SvREADONLY().

U32     SvREADONLY(SV* sv)

SvREADONLY_off

Отмечает объект как не-только для чтения. Точное значение зависит от типа объекта. Доступно для кода Perl через Internals::SvREADONLY().

U32     SvREADONLY_off(SV* sv)

SvREADONLY_on

Отмечает объект как только для чтения. Точное значение зависит от типа объекта. Доступно для кода Perl через Internals::SvREADONLY().

U32     SvREADONLY_on(SV* sv)

sv_ref

Возвращает SV, описывающий, к чему ссылается переданный SV.

dst может быть SV, который нужно установить в описание, или NULL, в этом случае возвращается временный SV.

Если ob истинно и SV освящен, то описание - это имя класса, в противном случае - тип SV, "SCALAR", "ARRAY" и т. д.

SV*     sv_ref(SV *dst, const SV *const sv,
               const int ob)

SvREFCNT

Возвращает значение счётчика ссылок объекта. Доступно для кода Perl через Internals::SvREFCNT().

U32     SvREFCNT(SV* sv)

SvREFCNT_dec

Уменьшает счётчик ссылок данного SV. sv может быть NULL.

void    SvREFCNT_dec(SV* sv)

SvREFCNT_dec_NN

То же, что и SvREFCNT_dec, но может использоваться только если известно, что sv не NULL. Поскольку проверка на NULL не требуется, она быстрее и компактнее.

void    SvREFCNT_dec_NN(SV* sv)

SvREFCNT_inc

Увеличивает счётчик ссылок данного SV, возвращая SV.

Все следующие SvREFCNT_inc* макросы являются оптимизированными версиями SvREFCNT_inc, и могут быть заменены на SvREFCNT_inc.

SV*     SvREFCNT_inc(SV* sv)

SvREFCNT_inc_NN

То же, что и SvREFCNT_inc, но может использоваться только если известно, что sv не NULL. Поскольку проверка на NULL не требуется, она быстрее и компактнее.

SV*     SvREFCNT_inc_NN(SV* sv)

SvREFCNT_inc_simple

То же самое, что и SvREFCNT_inc, но может использоваться только с выражениями без побочных эффектов. Поскольку нам не нужно хранить временное значение, это быстрее.

SV*     SvREFCNT_inc_simple(SV* sv)

SvREFCNT_inc_simple_NN

То же самое, что и SvREFCNT_inc_simple, но может использоваться только если известно, что sv не NULL. Поскольку нам не нужно проверять на NULL, это быстрее и компактнее.

SV*     SvREFCNT_inc_simple_NN(SV* sv)

SvREFCNT_inc_simple_void

То же самое, что и SvREFCNT_inc_simple, но может использоваться только если вам не нужно значение возврата. Макрос не обязан возвращать осмысленное значение.

void    SvREFCNT_inc_simple_void(SV* sv)

SvREFCNT_inc_simple_void_NN

То же самое, что и SvREFCNT_inc, но может использоваться только если вам не нужно значение возврата, и известно, что sv не NULL. Макрос не обязан возвращать осмысленное значение или проверять на NULL, поэтому он компактнее и быстрее.

void    SvREFCNT_inc_simple_void_NN(SV* sv)

SvREFCNT_inc_void

То же самое, что и SvREFCNT_inc, но может использоваться только если вам не нужно значение возврата. Макрос не обязан возвращать осмысленное значение.

void    SvREFCNT_inc_void(SV* sv)

SvREFCNT_inc_void_NN

void    SvREFCNT_inc_void_NN(SV* sv)

sv_reftype

Возвращает строку, описывающую, к чему ссылается SV.

Если ob истинно и SV благословлён, строка — это имя класса, в противном случае — тип SV, "SCALAR", "ARRAY" и т.д.

const char* sv_reftype(const SV *const sv, const int ob)

sv_replace

Делает первый аргумент копией второго, а затем удаляет оригинал. Целевой SV физически получает владение телом исходного SV и наследует его флаги; однако целевой SV сохраняет всю магию, которую он владеет, а любая магия в исходном SV отбрасывается. Обратите внимание, что это специализированная операция копирования SV; в большинстве случаев вы захотите использовать sv_setsv или один из его многочисленных макро-фронтов.

void    sv_replace(SV *const sv, SV *const nsv)

sv_report_used

Выводит содержимое всех SV, которые ещё не освобождены (помощь при отладке).

void    sv_report_used()

sv_reset

Базовая реализация функции reset Perl. Обратите внимание, что функция на уровне Perl слегка устарела.

void    sv_reset(const char* s, HV *const stash)

SvROK

Проверяет, является ли SV RV.

U32     SvROK(SV* sv)

SvROK_off

Сбрасывает статус RV SV.

void    SvROK_off(SV* sv)

SvROK_on

Устанавливает для SV статус RV.

void    SvROK_on(SV* sv)

SvRV

Дезактивирует RV, чтобы вернуть SV.

SV*     SvRV(SV* sv)

SvRV_set

Устанавливает значение указателя RV в sv на val. См. "SvIV_set".

void    SvRV_set(SV* sv, SV* val)

sv_rvunweaken

Отменяет ослабление ссылки: очищает флаг SvWEAKREF данного RV; удаляет обратную ссылку на этот RV из массива обратных ссылок, связанных с целевым SV, увеличивает счётчик ссылок целевого объекта. Безмолвно игнорирует undef и предупреждает об отсутствии слабых ссылок.

SV*     sv_rvunweaken(SV *const sv)

sv_rvweaken

Ослабляет ссылку: устанавливает флаг SvWEAKREF для этого RV; даёт целевому SV PERL_MAGIC_backref магию, если она ещё не установлена; и добавляет обратную ссылку на этот RV в массив обратных ссылок, связанных с этой магией. Если RV магический, вызывается magic set после очистки RV. Безмолвно игнорирует undef и предупреждает о уже слабых ссылках.

SV*     sv_rvweaken(SV *const sv)

sv_setiv

Копирует целое число в данный SV, предварительно повысив тип, если необходимо. Не обрабатывает магию "set". См. также "sv_setiv_mg".

void    sv_setiv(SV *const sv, const IV num)

sv_setiv_mg

Как sv_setiv, но также обрабатывает магию 'set'.

void    sv_setiv_mg(SV *const sv, const IV i)

sv_setnv

Копирует double в данный SV, предварительно повысив тип, если необходимо. Не обрабатывает магию 'set'. См. также "sv_setnv_mg".

void    sv_setnv(SV *const sv, const NV num)

sv_setnv_mg

Как sv_setnv, но также обрабатывает магию 'set'.

void    sv_setnv_mg(SV *const sv, const NV num)

sv_setpv

Копирует строку в SV. Строка должна завершаться символом NUL, и не содержать вложенных NUL. Не обрабатывает магию 'set'. См. "sv_setpv_mg".

void    sv_setpv(SV *const sv, const char *const ptr)

sv_setpvf

Работает как sv_catpvf, но копирует текст в SV вместо добавления его. Не обрабатывает магию 'set'. См. "sv_setpvf_mg".

void    sv_setpvf(SV *const sv, const char *const pat,
                  ...)

sv_setpvf_mg

Как sv_setpvf, но также обрабатывает магию 'set'.

void    sv_setpvf_mg(SV *const sv,
                     const char *const pat, ...)

sv_setpviv

Копирует целое число в заданный SV, обновляя также его строковое значение. Не обрабатывает магию 'set'. См. "sv_setpviv_mg".

void    sv_setpviv(SV *const sv, const IV num)

sv_setpviv_mg

Как sv_setpviv, но также обрабатывает магию 'set'.

void    sv_setpviv_mg(SV *const sv, const IV iv)

sv_setpvn

Копирует строку (возможно, содержащую вложенные NUL символы) в SV. Параметр len указывает количество копируемых байтов. Если аргумент ptr равен NULL, SV станет неопределённым. Не обрабатывает магию 'set'. См. "sv_setpvn_mg".

void    sv_setpvn(SV *const sv, const char *const ptr,
                  const STRLEN len)

sv_setpvn_mg

Как sv_setpvn, но также обрабатывает магию 'set'.

void    sv_setpvn_mg(SV *const sv,
                     const char *const ptr,
                     const STRLEN len)

sv_setpvs

Как sv_setpvn, но принимает литеральную строку вместо пары строка/длина.

void    sv_setpvs(SV* sv, "literal string" s)

sv_setpvs_mg

Как sv_setpvn_mg, но принимает литеральную строку вместо пары строка/длина.

void    sv_setpvs_mg(SV* sv, "literal string" s)

sv_setpv_bufsize

Устанавливает SV в строку длиной cur байт, с доступными как минимум len байтами. Гарантирует наличие нулевого байта в SvEND. Возвращает указатель char * на буфер SvPV.

char  * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
                         const STRLEN len)

sv_setpv_mg

Как sv_setpv, но также обрабатывает магию 'set'.

void    sv_setpv_mg(SV *const sv, const char *const ptr)

sv_setref_iv

Копирует целое число в новый SV, при необходимости благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV*     sv_setref_iv(SV *const rv,
                     const char *const classname,
                     const IV iv)

sv_setref_nv

Копирует double в новый SV, при необходимости благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV*     sv_setref_nv(SV *const rv,
                     const char *const classname,
                     const NV nv)

sv_setref_pv

Копирует указатель в новый SV, при необходимости благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Если аргумент pv равен NULL, то PL_sv_undef будет помещено в SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

Не использовать с другими типами Perl, такими как HV, AV, SV, CV, потому что эти объекты будут повреждены процессом копирования указателя.

Обратите внимание, что sv_setref_pvn копирует строку, а эта функция копирует указатель.

SV*     sv_setref_pv(SV *const rv,
                     const char *const classname,
                     void *const pv)

sv_setref_pvn

Копирует строку в новый SV, при необходимости благословляя SV. Длина строки должна быть указана параметром n. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

Обратите внимание, что sv_setref_pv копирует указатель, а эта функция копирует строку.

SV*     sv_setref_pvn(SV *const rv,
                      const char *const classname,
                      const char *const pv,
                      const STRLEN n)

sv_setref_pvs

Как sv_setref_pvn, но принимает литеральную строку вместо пары строка/длина.

SV *    sv_setref_pvs("literal string" s)

sv_setref_uv

Копирует беззнаковое целое число в новый SV, при необходимости благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV*     sv_setref_uv(SV *const rv,
                     const char *const classname,
                     const UV uv)

sv_setsv

Копирует содержимое исходного SV ssv в целевой SV dsv. Исходный SV может быть уничтожен, если он смертный, поэтому не используйте эту функцию, если исходный SV нужно повторно использовать. Не обрабатывает магию 'set' в целевом SV. Вызывает магию 'get' в исходном SV. Грубо говоря, выполняет копирование по значению, уничтожая предыдущее содержимое целевого объекта.

Вероятно, вы захотите использовать один из наборов обёрток, таких как SvSetSV, SvSetSV_nosteal, SvSetMagicSV и SvSetMagicSV_nosteal.

void    sv_setsv(SV *dstr, SV *sstr)

sv_setsv_flags

Копирует содержимое исходного SV ssv в целевой SV dsv. Исходный SV может быть уничтожен, если он смертный, поэтому не используйте эту функцию, если исходный SV нужно повторно использовать. Не обрабатывает магию 'set'. Грубо говоря, выполняет копирование по значению, уничтожая любое предыдущее содержимое назначения. Если параметр flags имеет установленный бит SV_GMAGIC, будет mg_get на ssv, в противном случае — нет. Если параметр flags имеет установленный бит SV_NOSTEAL, буферы временных переменных не будут украдены. sv_setsv и sv_setsv_nomg реализованы с помощью этой функции.

Вероятно, вам следует использовать один из наборов обёртки, таких как SvSetSV, SvSetSV_nosteal, SvSetMagicSV и SvSetMagicSV_nosteal.

Это основная функция для копирования скаляров, и большинство других функций и макросов копирования используют её в качестве подфункции.

void    sv_setsv_flags(SV *dstr, SV *sstr,
                       const I32 flags)

sv_setsv_mg

Как sv_setsv, но также обрабатывает магию 'set'.

void    sv_setsv_mg(SV *const dstr, SV *const sstr)

sv_setsv_nomg

Как sv_setsv, но не обрабатывает магию.

void    sv_setsv_nomg(SV* dsv, SV* ssv)

sv_setuv

Копирует целое беззнаковое число в заданный SV, сначала выполняя повышение, если необходимо. Не обрабатывает магию 'set'. См. также "sv_setuv_mg".

void    sv_setuv(SV *const sv, const UV num)

sv_setuv_mg

Как sv_setuv, но также обрабатывает магию 'set'.

void    sv_setuv_mg(SV *const sv, const UV u)

sv_set_undef

Эквивалентно sv_setsv(sv, &PL_sv_undef), но более эффективно. Не обрабатывает магию set.

Аналог в perl — $sv = undef;. Обратите внимание, что он не освобождает буферы строк, в отличие от undef $sv.

Введён в perl 5.25.12.

void    sv_set_undef(SV *sv)

SvSTASH

Возвращает stash объекта SV.

HV*     SvSTASH(SV* sv)

SvSTASH_set

Устанавливает значение указателя STASH в sv на val. См. "SvIV_set".

void    SvSTASH_set(SV* sv, HV* val)

SvTAINT

Помечает SV как испорченный, если включена маркировка, и если какой-либо ввод в текущее выражение помечен — обычно переменная, но также могут быть явные вводы, такие как настройки локали. SvTAINT распространяет эту метку испорченности на выходные данные выражения пессимистичным образом; т. е., не обращая внимания на то, какие именно выходные данные влияют на какие вводы.

void    SvTAINT(SV* sv)

SvTAINTED

Проверяет, помечен ли SV как испорченный. Возвращает ИСТИНА, если помечен, ЛОЖЬ — если нет.

bool    SvTAINTED(SV* sv)

sv_tainted

Проверка SV на испорченность. Используйте SvTAINTED вместо этого.

bool    sv_tainted(SV *const sv)

SvTAINTED_off

Снимает метку испорченности с SV. Будьте очень осторожны с этой процедурой, так как она обходит некоторые основные функции безопасности Perl. Авторы модулей XS не должны использовать эту функцию, если они полностью не понимают всех последствий безусловного снятия метки испорченности со значения. Снятие метки испорченности должно выполняться стандартным способом Perl с помощью тщательно продуманного регулярного выражения, а не прямым снятием метки с переменных.

void    SvTAINTED_off(SV* sv)

SvTAINTED_on

Помечает SV как испорченный, если включена маркировка испорченности.

void    SvTAINTED_on(SV* sv)

SvTRUE

Возвращает булево значение, указывающее, будет ли Perl оценивать SV как истинное или ложное. См. "SvOK" для проверки определённости/неопределённости. Обрабатывает магию 'get', если скаляр ещё не SvPOK, SvIOK или SvNOK (общедоступные, а не приватные флаги).

bool    SvTRUE(SV* sv)

sv_true

Возвращает ИСТИНА, если SV имеет истинное значение по правилам Perl. Используйте макрос SvTRUE, который может вызвать sv_true(), или может использовать встроенный вариант.

I32     sv_true(SV *const sv)

SvTRUE_nomg

Возвращает булево значение, указывающее, будет ли Perl оценивать SV как истинное или ложное. См. "SvOK" для проверки определённости/неопределённости. Не обрабатывает магию 'get'.

bool    SvTRUE_nomg(SV* sv)

SvTYPE

Возвращает тип SV. См. "svtype".

svtype  SvTYPE(SV* sv)

sv_unmagic

Удаляет всю магию типа type из SV.

int     sv_unmagic(SV *const sv, const int type)

sv_unmagicext

Удаляет всю магию типа type со специфицированным vtbl из SV.

int     sv_unmagicext(SV *const sv, const int type,
                      MGVTBL *vtbl)

sv_unref_flags

Снимает статус RV для SV и уменьшает счётчик ссылок на то, что ссылалось через RV. Это можно рассматривать как обратную операцию к newSVrv. Аргумент cflags может содержать SV_IMMEDIATE_UNREF для принудительного уменьшения счётчика ссылок (в противном случае уменьшение происходит при условии, что счётчик ссылок отличен от единицы или ссылка относится к только-для-чтения SV). См. "SvROK_off".

void    sv_unref_flags(SV *const ref, const U32 flags)

sv_untaint

Снимает метку испорченности с SV. Используйте SvTAINTED_off вместо этого.

void    sv_untaint(SV *const sv)

SvUOK

Возвращает булево значение, указывающее, содержит ли SV целое число, которое должно интерпретироваться как беззнаковое. Целое число, неотрицательное и попадающее в диапазон и IV и UV, может быть помечено как SvUOK или SVIOK.

bool    SvUOK(SV* sv)

SvUPGRADE

Используется для повышения SV до более сложной формы. Использует sv_upgrade для выполнения повышения при необходимости. См. "svtype".

void    SvUPGRADE(SV* sv, svtype type)

sv_upgrade

Повышает SV до более сложной формы. Обычно добавляет новый тип тела к SV, затем копирует как можно больше информации из старого тела. Вызывает ошибку, если SV уже имеет более сложную форму, чем требуется. Обычно следует использовать обёртку-макрос SvUPGRADE, которая проверяет тип перед вызовом sv_upgrade, и поэтому не вызывает ошибку. См. также "svtype".

void    sv_upgrade(SV *const sv, svtype new_type)

sv_usepvn_flags

Указывает SV использовать ptr для поиска своего строкового значения. Обычно строка хранится внутри SV, но sv_usepvn позволяет SV использовать внешнюю строку. ptr должен указывать на память, выделенную функцией Newx. Он должен быть началом Newx-блока памяти, а не указателем на середину (следите за OOK и копированием при записи), и не должен происходить из не-Newx менеджера памяти, например, malloc. Длина строки, len, должна быть указана. По умолчанию эта функция будет Renew (т. е. перевыделять, перемещать) память, на которую указывает ptr, поэтому программисту не следует освобождать или использовать этот указатель после передачи его в sv_usepvn, и ни один указатель "ниже" этого указателя (например, ptr + 1) не должен использоваться.

Если flags & SV_SMAGIC истинно, будет вызвано SvSETMAGIC. Если flags & SV_HAS_TRAILING_NUL истинно, то ptr[len] должно быть NUL, и перевыделение будет пропущено (т. е. буфер фактически на 1 байт длиннее, чем len, и уже отвечает требованиям хранения в SvPVX).

void    sv_usepvn_flags(SV *const sv, char* ptr,
                        const STRLEN len,
                        const U32 flags)

SvUTF8

Возвращает значение U32, указывающее на состояние UTF-8 объекта SV. При правильной настройке это указывает, содержит ли SV данные в кодировке UTF-8. Вы должны использовать это после вызова SvPV() или одного из его вариантов, на случай, если какой-либо вызов перегрузки строк обновит внутренний флаг.

Если вы хотите учесть прагму bytes, используйте "DO_UTF8" вместо этого.

U32     SvUTF8(SV* sv)

sv_utf8_decode

Если PV объекта SV является последовательностью октетов в расширенном UTF-8 Perl и содержит символ с несколькими байтами, флаг SvUTF8 устанавливается, чтобы он выглядел как символ. Если PV содержит только символы с одним байтом, флаг SvUTF8 остаётся выключенным. Проверяет PV на корректность и возвращает ЛОЖЬ, если PV не является корректным UTF-8.

bool    sv_utf8_decode(SV *const sv)

sv_utf8_downgrade

Пытается преобразовать PV объекта SV из символов в байты. Если PV содержит символ, который не помещается в байт, это преобразование завершится неудачей; в этом случае либо возвращает ложь, или, если fail_ok не истинно, вызывает ошибку.

Это не универсальный интерфейс для кодирования Unicode в байты: для этого используйте расширение Encode.

bool    sv_utf8_downgrade(SV *const sv,
                          const bool fail_ok)

sv_utf8_encode

Преобразует PV объекта SV в UTF-8, но затем выключает флаг SvUTF8, чтобы он снова выглядел как октеты.

void    sv_utf8_encode(SV *const sv)

sv_utf8_upgrade

Преобразует PV объекта SV в его форму UTF-8. Принудительно переводит SV в строковый формат, если он им не является. Будет mg_get на sv при необходимости. Всегда устанавливает флаг SvUTF8, чтобы избежать будущих проверок корректности, даже если вся строка идентична в UTF-8 и без него. Возвращает количество байтов в преобразованной строке.

Это не универсальный интерфейс для кодирования байтов в Unicode: используйте расширение Encode для этого.

STRLEN  sv_utf8_upgrade(SV *sv)

sv_utf8_upgrade_flags

Преобразует PV объекта SV в его форму UTF-8. Принудительно переводит SV в строковый формат, если он им не является. Всегда устанавливает флаг SvUTF8, чтобы избежать будущих проверок корректности, даже если все байты неизменны в UTF-8. Если flags имеет установленный бит SV_GMAGIC, будет mg_get на sv при необходимости, в противном случае — нет.

Флаг SV_FORCE_UTF8_UPGRADE теперь игнорируется.

Возвращает количество байтов в преобразованной строке.

Это не универсальный интерфейс для кодирования байтов в Unicode: используйте расширение Encode для этого.

STRLEN  sv_utf8_upgrade_flags(SV *const sv,
                              const I32 flags)

sv_utf8_upgrade_flags_grow

Как sv_utf8_upgrade_flags, но имеет дополнительный параметр extra, который представляет количество неиспользуемых байтов, гарантированно свободных в строке sv после возврата. Это позволяет вызывающей стороне зарезервировать дополнительное пространство, которое она намеревается заполнить, чтобы избежать дополнительных увеличений.

sv_utf8_upgrade, sv_utf8_upgrade_nomg, и sv_utf8_upgrade_flags реализованы с использованием этой функции.

Возвращает количество байтов в преобразованной строке (без учета резервных).

STRLEN  sv_utf8_upgrade_flags_grow(SV *const sv,
                                   const I32 flags,
                                   STRLEN extra)

sv_utf8_upgrade_nomg

Как sv_utf8_upgrade, но не выполняет магических операций над sv.

STRLEN  sv_utf8_upgrade_nomg(SV *sv)

SvUTF8_off

Сбрасывает статус UTF-8 для SV (данные не изменяются, только флаг). Не используйте бездумно.

void    SvUTF8_off(SV *sv)

SvUTF8_on

Включает статус UTF-8 для SV (данные не изменяются, только флаг). Не используйте бездумно.

void    SvUTF8_on(SV *sv)

SvUV

Преобразует данный SV в UV и возвращает его. Возвращаемое значение во многих случаях будет сохранено в слоте UV sv, но не во всех. (Используйте "sv_setuv", чтобы убедиться, что это так).

См. "SvUVx", чтобы получить версию, которая гарантирует, что sv будет вычислена только один раз.

UV      SvUV(SV* sv)

SvUV_nomg

Как SvUV, но не обрабатывает магические операции.

UV      SvUV_nomg(SV* sv)

SvUV_set

Устанавливает значение указателя UV в sv на val. См. "SvIV_set".

void    SvUV_set(SV* sv, UV val)

SvUVX

Возвращает исходное значение в слоте UV SV без проверок или преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvUV".

UV      SvUVX(SV* sv)

SvUVx

Эта форма гарантирует, что sv будет вычислена только один раз. Используйте только в том случае, если sv является выражением со побочными эффектами; в противном случае используйте более эффективную функцию SvUV.

UV      SvUVx(SV* sv)

sv_vcatpvf

Обрабатывает свои аргументы как sv_vcatpvfn с использованием непустого списка аргументов C-стиля и добавляет отформатированный вывод в SV. Не обрабатывает магию 'set'. См. "sv_vcatpvf_mg".

Обычно используется через её фронтенд sv_catpvf.

void    sv_vcatpvf(SV *const sv, const char *const pat,
                   va_list *const args)

sv_vcatpvfn

void    sv_vcatpvfn(SV *const sv, const char *const pat,
                    const STRLEN patlen,
                    va_list *const args,
                    SV **const svargs,
                    const Size_t sv_count,
                    bool *const maybe_tainted)

sv_vcatpvfn_flags

Обрабатывает свои аргументы как vsprintf и добавляет отформатированный вывод в SV. Использует массив SV, если список аргументов C-стиля отсутствует (NULL). Переупорядочивание аргументов (использование спецификаторов формата, таких как %2$d или %*2$d ) поддерживается только при использовании массива SV; использование списка аргументов C-стиля с строкой формата, использующей переупорядочивание аргументов, приведет к исключению.

При включённых проверках на загрязнение, указывает через maybe_tainted , являются ли результаты недостоверными (часто из-за использования локали).

Если вызвана как sv_vcatpvfn или флаг имеет установленный бит SV_GMAGIC, вызывает магию.

Предполагает, что pat имеет такой же тип utf8, как и sv. Ответственность вызывающей стороны - убедиться в этом.

Обычно используется через один из её фронтендов sv_vcatpvf и sv_vcatpvf_mg.

void    sv_vcatpvfn_flags(SV *const sv,
                          const char *const pat,
                          const STRLEN patlen,
                          va_list *const args,
                          SV **const svargs,
                          const Size_t sv_count,
                          bool *const maybe_tainted,
                          const U32 flags)

sv_vcatpvf_mg

Как sv_vcatpvf, но также обрабатывает магию 'set'.

Обычно используется через её фронтенд sv_catpvf_mg.

void    sv_vcatpvf_mg(SV *const sv,
                      const char *const pat,
                      va_list *const args)

SvVOK

Возвращает булево значение, указывающее, содержит ли SV строку v-типа.

bool    SvVOK(SV* sv)

sv_vsetpvf

Работает как sv_vcatpvf , но копирует текст в SV вместо добавления. Не обрабатывает магию 'set'. См. "sv_vsetpvf_mg".

Обычно используется через её фронтенд sv_setpvf.

void    sv_vsetpvf(SV *const sv, const char *const pat,
                   va_list *const args)

sv_vsetpvfn

Работает как sv_vcatpvfn , но копирует текст в SV вместо добавления.

Обычно используется через один из её фронтендов sv_vsetpvf и sv_vsetpvf_mg.

void    sv_vsetpvfn(SV *const sv, const char *const pat,
                    const STRLEN patlen,
                    va_list *const args,
                    SV **const svargs,
                    const Size_t sv_count,
                    bool *const maybe_tainted)

sv_vsetpvf_mg

Как sv_vsetpvf, но также обрабатывает магию 'set'.

Обычно используется через её фронтенд sv_setpvf_mg.

void    sv_vsetpvf_mg(SV *const sv,
                      const char *const pat,
                      va_list *const args)

Поддержка Unicode

"Поддержка Unicode" в perlguts содержит введение в этот API.

См. также "Классификация символов" и "Изменение регистра символов". Различные функции за пределами этого раздела также работают специально с Unicode. Поиск строки "utf8" в этом документе.

BOM_UTF8

Это макрос, который вычисляет строковую константу байтов UTF-8, определяющих метку порядка байтов Юникода (U+FEFF) для платформы, на которой скомпилирован perl. Это позволяет использовать мнемоническое обозначение для этого символа, которое работает как на платформах ASCII, так и EBCDIC. sizeof(BOM_UTF8) - 1 может использоваться для получения его длины в байтах.

bytes_cmp_utf8

Сравнивает последовательность символов (хранящихся как октеты) в b, blen с последовательностью символов (хранящихся как UTF-8) в u, ulen. Возвращает 0, если они равны, -1 или -2, если первая строка меньше второй строки, +1 или +2, если первая строка больше второй строки.

-1 или +1 возвращается, если более короткая строка была идентична началу более длинной строки. -2 или +2 возвращаются, если были различия между символами в строках.

int     bytes_cmp_utf8(const U8 *b, STRLEN blen,
                       const U8 *u, STRLEN ulen)

bytes_from_utf8

Преобразует потенциально закодированную в UTF-8 строку s длиной *lenp в кодировку байтов по умолчанию. На входе булево значение *is_utf8p указывает, закодирована ли s в UTF-8.

В отличие от "utf8_to_bytes", но подобно "bytes_to_utf8", эта функция не изменяет входную строку.

Не делает ничего, если *is_utf8p равно 0 или если в строке есть символы, которые невозможно представить в кодировке байтов по умолчанию. В этих случаях *is_utf8p и *lenp остаются неизменными, а возвращаемое значение — исходное s.

В противном случае *is_utf8p устанавливается в 0, а возвращаемое значение — указатель на только что созданную строку, содержащую пониженную копию s, и длина которой возвращается в *lenp, обновлённая. Новая строка завершается символом NUL. Вызывающий код отвечает за освобождение памяти, используемой этой строкой.

После успешного возврата количество вариантов в строке можно вычислить, сохранив значение *lenp перед вызовом и вычитав из него значение *lenp после вызова.

U8*     bytes_from_utf8(const U8 *s, STRLEN *lenp,
                        bool *is_utf8p)

bytes_to_utf8

Преобразует строку s длиной *lenp байтов из кодировки по умолчанию в UTF-8. Возвращает указатель на только что созданную строку и устанавливает *lenp для отражения новой длины в байтах. Вызывающий код отвечает за освобождение памяти, используемой этой строкой.

После успешного возврата количество вариантов в строке можно вычислить, сохранив значение *lenp перед вызовом и вычитав его из значения *lenp после вызова.

Символ NUL будет записан после конца строки.

Если требуется конвертация в UTF-8 из кодировок, отличных от кодировки по умолчанию (Latin1 или EBCDIC), см. "sv_recode_to_utf8"().

U8*     bytes_to_utf8(const U8 *s, STRLEN *lenp)

DO_UTF8

Возвращает булево значение, указывающее, должна ли переменная PV в sv рассматриваться как закодированная в UTF-8.

Следует использовать эту функцию после вызова SvPV() или одной из её разновидностей, на случай, если какой-либо вызов перегрузки строк обновит внутренний флаг кодировки UTF-8.

bool    DO_UTF8(SV* sv)

foldEQ_utf8

Возвращает true, если начальные части строк s1 и s2 (любая из которых или обе могут быть в UTF-8) одинаковы с точки зрения регистра; иначе — false. Расстояние, до которого нужно сравнивать строки, определяется другими входными параметрами.

Если u1 истинно, строка s1 предполагается закодированной в UTF-8 Unicode; в противном случае — в кодировке родного 8-битного кода. Соответственно для u2 относительно s2.

Если длина в байтах l1 не нулевая, она указывает, насколько далеко в s1 нужно искать равенство с учётом регистра. Другими словами, s1+l1 будут использоваться как цель. Сопоставление не считается совпадением, если цель не достигнута, и сканирование не будет продолжено после достижения этой цели. Соответственно для l2 относительно s2.

Если pe1 не равно NULL и указатель, на который оно указывает, не равен NULL, этот указатель рассматривается как конечный указатель на позицию в 1 байт за максимальной точкой в s1, за которой сканирование не будет продолжаться ни при каких обстоятельствах. (Эта функция предполагает, что входные строки, закодированные в UTF-8, не содержат ошибок; неправильный ввод может привести к чтению за пределы pe1). Это означает, что если оба l1 и pe1 указаны, а pe1 меньше, чем s1+l1, совпадение никогда не будет успешным, потому что оно никогда не сможет достичь цели (и на самом деле проверяется против неё). Соответственно для pe2 относительно s2.

По крайней мере, одна из s1 и s2 должна иметь цель (по крайней мере, одно из l1 и l2 должно быть ненулевым), и если оба имеют, оба должны быть достигнуты для успешного совпадения. Также, если преобразование символа при учёте регистра даёт несколько символов, все они должны быть согласованы (см. ссылку tr21 ниже для "преобразования регистра").

При успешном совпадении, если pe1 не равно NULL, оно будет установлено на указатель начала следующего символа в s1 за пределами сопоставленной части. Соответственно для pe2 и s2.

Для учёта регистра используется "преобразование регистра" Юникода вместо преобразования символов в верхний и нижний регистр, см. http://www.unicode.org/unicode/reports/tr21/ (Преобразования регистра).

I32     foldEQ_utf8(const char *s1, char **pe1, UV l1,
                    bool u1, const char *s2, char **pe2,
                    UV l2, bool u2)

is_ascii_string

Это немного вводящее в заблуждение синоним для "is_utf8_invariant_string". На платформах, похожих на ASCII, название не вводит в заблуждение: символы диапазона ASCII — это именно инварианты UTF-8. Но на машинах EBCDIC инвариантов больше, чем просто символы ASCII, поэтому is_utf8_invariant_string предпочтительнее.

bool    is_ascii_string(const U8* const s, STRLEN len)

is_c9strict_utf8_string

Возвращает ИСТИНА, если первые len байтов строки s образуют корректную строку UTF-8, которая соответствует Поправке #9 к Юникоду; в противном случае — ЛОЖЬ. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот вариант, то в s не может быть вложенных NUL символов и должен быть завершающий NUL байт). Обратите внимание, что все символы ASCII составляют "корректную строку UTF-8".

Эта функция возвращает ЛОЖЬ для строк, содержащих любые кодовые точки выше максимального значения Юникода 0x10FFFF или суррогатные кодовые точки, но принимает несимвольные кодовые точки в соответствии с Поправкой #9.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_utf8_string_flags", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_c9strict_utf8_string(const U8 *s, STRLEN len)

is_c9strict_utf8_string_loc

Как "is_c9strict_utf8_string" , но сохраняет местоположение ошибки (в случае "ошибки utf8") или местоположение s+len (в случае "успеха utf8") в указателе ep.

См. также "is_c9strict_utf8_string_loclen".

bool    is_c9strict_utf8_string_loc(const U8 *s,
                                    STRLEN len,
                                    const U8 **ep)

is_c9strict_utf8_string_loclen

Как "is_c9strict_utf8_string" , но сохраняет местоположение ошибки (в случае "ошибки utf8") или местоположение s+len (в случае "успеха utf8") в указателе ep и количество закодированных в UTF-8 символов в указателе el.

См. также "is_c9strict_utf8_string_loc".

bool    is_c9strict_utf8_string_loclen(const U8 *s,
                                       STRLEN len,
                                       const U8 **ep,
                                       STRLEN *el)

isC9_STRICT_UTF8_CHAR

Принимает ненулевое значение, если первые несколько байтов строки, начиная с s и не дальше, чем e - 1, представляют собой корректную строку UTF-8, представляющую некоторую несуррогатную кодовую точку Юникода; в противном случае — 0. Если не равно нулю, значение показывает количество байтов, начиная с s , которые составляют представление кодовой точки. Любые оставшиеся байты до e, но после тех, которые необходимы для формирования первой кодовой точки в s, не проверяются.

Наибольшая допустимая кодовая точка — максимальное значение Юникода 0x10FFFF. Это отличается от "isSTRICT_UTF8_CHAR" только тем, что принимает несимвольные кодовые точки. Это соответствует Поправке #9 к Юникоду, которая указала, что несимвольные кодовые точки просто нежелательны, а не полностью запрещены в открытом обмене. См. "Несимвольные кодовые точки" в perlunicode.

Используйте "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen" для проверки целых строк.

STRLEN  isC9_STRICT_UTF8_CHAR(const U8 *s, const U8 *e)

is_invariant_string

Это несколько вводящее в заблуждение синоним для "is_utf8_invariant_string". is_utf8_invariant_string предпочтительнее, поскольку он указывает условия, при которых строка является инвариантной.

bool    is_invariant_string(const U8* const s,
                            STRLEN len)

isSTRICT_UTF8_CHAR

Принимает ненулевое значение, если первые несколько байтов строки, начиная с s и не выходя за пределы e - 1, являются корректным кодированием UTF-8, представляющим какой-либо символ Юникода, полностью приемлемый для обмена между всеми приложениями; в противном случае возвращает 0. Если ненулевое, значение показывает, сколько байтов, начиная с s , составляют представление символа. Любые байты, оставшиеся перед e, но за пределами необходимых для формирования первого символа в s, не проверяются.

Наибольший допустимый символ Юникода — максимальное значение 0x10FFFF, и он не должен быть суррогатным или недопустимым символом. Таким образом, это исключает любой символ из расширенного UTF-8 Perl.

Это используется для эффективного определения, являются ли следующие несколько байтов в s допустимым Юникод-совместимым UTF-8 для одного символа.

Используйте "isC9_STRICT_UTF8_CHAR" для использования определения допустимых символов Юникода из Unicode Corrigendum #9; "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_strict_utf8_string", "is_strict_utf8_string_loc", и "is_strict_utf8_string_loclen" для проверки целых строк.

Size_t  isSTRICT_UTF8_CHAR(const U8 * const s0,
                           const U8 * const e)

is_strict_utf8_string

Возвращает TRUE, если первые len байта строки s образуют корректную строку UTF-8, полностью совместимую с любым приложением, использующим правила Юникода; в противном случае возвращает FALSE. Если len равно 0, оно вычисляется с использованием strlen(s) (что означает, что если вы используете этот параметр, s не может содержать вложенные NUL символы и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «корректную строку UTF-8».

Эта функция возвращает FALSE для строк, содержащих любые символы Юникода выше максимального значения 0x10FFFF, суррогатных символов или недопустимых символов.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_strict_utf8_string(const U8 *s, STRLEN len)

is_strict_utf8_string_loc

Аналогично "is_strict_utf8_string", но сохраняет положение ошибки (в случае «несоответствия UTF-8») или положение s+len (в случае «успеха UTF-8») в указателе ep.

См. также "is_strict_utf8_string_loclen".

bool    is_strict_utf8_string_loc(const U8 *s,
                                  STRLEN len,
                                  const U8 **ep)

is_strict_utf8_string_loclen

Аналогично "is_strict_utf8_string", но сохраняет положение ошибки (в случае «несоответствия UTF-8») или положение s+len (в случае «успеха UTF-8») в указателе ep, и количество кодированных символов UTF-8 в указателе el.

См. также "is_strict_utf8_string_loc".

bool    is_strict_utf8_string_loclen(const U8 *s,
                                     STRLEN len,
                                     const U8 **ep,
                                     STRLEN *el)

is_utf8_fixed_width_buf_flags

Возвращает TRUE, если фиксированный буфер, начиная с s и длиной len полностью соответствует UTF-8, с учетом ограничений, заданных flags; в противном случае возвращает FALSE.

Если flags равно 0, любой корректный UTF-8, расширенный Perl, принимается без ограничений. Если последние несколько байтов буфера не образуют полный символ, это всё равно вернёт TRUE, при условии, что "is_utf8_valid_partial_char_flags" возвращает TRUE для них.

Если flags отлично от нуля, это может быть любое сочетание флагов UTF8_DISALLOW_foo , принятых "utf8n_to_uvchr", с тем же значением.

Эта функция отличается от "is_utf8_string_flags" только тем, что последняя возвращает FALSE, если последние несколько байтов строки не образуют полный символ.

bool    is_utf8_fixed_width_buf_flags(
            const U8 * const s, STRLEN len,
            const U32 flags
        )

is_utf8_fixed_width_buf_loclen_flags

Аналогично "is_utf8_fixed_width_buf_loc_flags" , но хранит количество полных, допустимых символов в указателе el.

bool    is_utf8_fixed_width_buf_loclen_flags(
            const U8 * const s, STRLEN len,
            const U8 **ep, STRLEN *el, const U32 flags
        )

is_utf8_fixed_width_buf_loc_flags

Аналогично "is_utf8_fixed_width_buf_flags" , но хранит местоположение ошибки в указателе ep . Если функция возвращает TRUE, *ep будет указывать на начало любого частичного символа в конце буфера; если частичного символа нет, *ep будет содержать s+len.

См. также "is_utf8_fixed_width_buf_loclen_flags".

bool    is_utf8_fixed_width_buf_loc_flags(
            const U8 * const s, STRLEN len,
            const U8 **ep, const U32 flags
        )

is_utf8_invariant_string

Возвращает TRUE, если первые len байта строки s одинаковы независимо от кодировки UTF-8 строки (или кодировки UTF-EBCDIC на EBCDIC-машинах); в противном случае возвращает FALSE. То есть, возвращает TRUE, если они инвариантны к UTF-8. На машинах ASCII-подобного типа все и только ASCII-символы подходят под это определение. На EBCDIC-машинах символы диапазона ASCII инвариантны, но также инвариантны и управляющие символы C1.

Если len равно 0, оно будет вычислено с использованием strlen(s), (что означает, что если вы используете этот параметр, s не может содержать вложенные NUL символы и должен иметь завершающий NUL байт).

См. также "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_utf8_invariant_string(const U8* const s,
                                 STRLEN len)

is_utf8_invariant_string_loc

Аналогично "is_utf8_invariant_string" , но при ошибке сохраняет позицию первого символа, неинвариантного к UTF-8, в указателе ep; если все символы инвариантны к UTF-8, эта функция не изменяет содержимое *ep.

bool    is_utf8_invariant_string_loc(const U8* const s,
                                     STRLEN len,
                                     const U8 ** ep)

is_utf8_string

Возвращает TRUE, если первые len байта строки s образуют корректную строку расширенного UTF-8 Perl; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с использованием strlen(s) (что означает, что если вы используете этот параметр, s не может содержать вложенные NUL символы и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «корректную строку UTF-8».

Эта функция считает расширенный UTF-8 Perl допустимым. Это означает, что символы Юникода выше максимального значения, суррогатные символы и недопустимые символы считаются допустимыми этой функцией. Используйте "is_strict_utf8_string", "is_c9strict_utf8_string", или "is_utf8_string_flags" для ограничения допустимых символов.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string_loc", "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags".

bool    is_utf8_string(const U8 *s, STRLEN len)

is_utf8_string_flags

Возвращает TRUE, если первые len байта строки s образуют корректную строку UTF-8, с учетом ограничений, заданных flags; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с использованием strlen(s) (что означает, что если вы используете этот параметр, s не может содержать вложенные NUL символы и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «корректную строку UTF-8».

Если flags равно 0, это даёт те же результаты, что и "is_utf8_string"; если flags равно UTF8_DISALLOW_ILLEGAL_INTERCHANGE, это даёт те же результаты, что и "is_strict_utf8_string"; и если flags равно UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE, это даёт те же результаты, что и "is_c9strict_utf8_string". В противном случае flags может быть любым сочетанием флагов UTF8_DISALLOW_foo , понимаемых "utf8n_to_uvchr", с тем же значением.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_utf8_string_flags(const U8 *s, STRLEN len,
                             const U32 flags)

is_utf8_string_loc

Аналогично "is_utf8_string" , но хранит положение ошибки (в случае «несоответствия UTF-8») или положение s+len (в случае «успеха UTF-8») в указателе ep.

См. также "is_utf8_string_loclen".

bool    is_utf8_string_loc(const U8 *s,
                           const STRLEN len,
                           const U8 **ep)

is_utf8_string_loclen

Аналогично "is_utf8_string" , но хранит положение ошибки (в случае «несоответствия UTF-8») или положение s+len (в случае «успеха UTF-8») в указателе ep, и количество кодированных символов UTF-8 в указателе el.

См. также "is_utf8_string_loc".

bool    is_utf8_string_loclen(const U8 *s, STRLEN len,
                              const U8 **ep, STRLEN *el)

is_utf8_string_loclen_flags

Аналогично "is_utf8_string_flags" , но сохраняет позицию ошибки (в случае «несоответствия UTF-8») или позицию s+len (в случае «успеха UTF-8») в указателе ep, и количество кодированных символов UTF-8 в указателе el.

См. также "is_utf8_string_loc_flags".

bool    is_utf8_string_loclen_flags(const U8 *s,
                                    STRLEN len,
                                    const U8 **ep,
                                    STRLEN *el,
                                    const U32 flags)

is_utf8_string_loc_flags

Аналогично "is_utf8_string_flags" , но сохраняет позицию ошибки (в случае «несоответствия UTF-8») или позицию s+len (в случае «успеха UTF-8») в указателе ep.

См. также "is_utf8_string_loclen_flags".

bool    is_utf8_string_loc_flags(const U8 *s,
                                 STRLEN len,
                                 const U8 **ep,
                                 const U32 flags)

is_utf8_valid_partial_char

Возвращает 0, если последовательность байтов, начинающаяся в s и не заходящая дальше e - 1, соответствует кодировке UTF-8, расширенной Perl, для одного или нескольких кодовых точек. В противном случае возвращает 1, если существует по крайней мере одна непустая последовательность байтов, которая, при добавлении к последовательности s, начиная с позиции e, превращает всю последовательность в корректное UTF-8 представление некоторой кодовой точки; в противном случае возвращает 0.

Другими словами, это возвращает ИСТИНА, если s указывает на частичную UTF-8 кодировку кодовой точки.

Это полезно, когда буфер фиксированной длины проверяется на корректность UTF-8, но последние несколько байтов не образуют полный символ; то есть он разбит где-то посередине конечного UTF-8 представления последней кодовой точки. (Предположительно, когда буфер обновляется следующей частью данных, новые начальные байты завершат частичную кодовую точку). Эта функция используется для проверки, действительно ли последние байты текущего буфера являются законным началом какой-либо кодовой точки, так что если они таковыми не являются, ошибка может быть сигнализирована без ожидания следующего чтения.

bool    is_utf8_valid_partial_char(const U8 * const s,
                                   const U8 * const e)

is_utf8_valid_partial_char_flags

Как и "is_utf8_valid_partial_char", она возвращает логическое значение, указывающее, является ли входной данные частичным символом UTF-8, но принимает дополнительный параметр, flags, который может дополнительно ограничить допустимые кодовые точки.

Если flags равно 0, она ведет себя идентично "is_utf8_valid_partial_char". В противном случае flags может быть любой комбинацией флагов UTF8_DISALLOW_foo , принятых "utf8n_to_uvchr". Если существует любая последовательность байтов, которая может завершить частичный символ ввода таким образом, что образуется не запрещённая кодовая точка, функция возвращает ИСТИНА; в противном случае ЛОЖЬ. Кодовые точки, не являющиеся символами, не могут быть определены на основе частичного ввода символов. Однако многие другие возможные исключённые типы могут быть определены только по первым одному или двум байтам.

bool    is_utf8_valid_partial_char_flags(
            const U8 * const s, const U8 * const e,
            const U32 flags
        )

isUTF8_CHAR

Принимает ненулевое значение, если первые несколько байтов строки, начиная с s и не выходя за пределы e - 1, являются корректной UTF-8 последовательностью, расширенной Perl, представляющей некоторую кодовую точку; в противном случае принимает значение 0. Если ненулевое, значение указывает, сколько байтов, начиная с s , составляют представление кодовой точки. Любые оставшиеся байты до e, но после необходимых для формирования первой кодовой точки в s, не проверяются.

Кодовая точка может быть любой, которая поместится в IV на этой машине, используя расширение Perl для официального UTF-8 для представления тех, которые выше максимального значения Unicode 0x10FFFF. Это означает, что этот макрос используется для эффективного определения, являются ли следующие несколько байтов в s допустимым UTF-8 для одного символа.

Используйте "isSTRICT_UTF8_CHAR" для ограничения допустимых кодовых точек теми, которые определены Unicode, как полностью взаимозаменяемые во всех приложениях; "isC9_STRICT_UTF8_CHAR" для использования определения допустимых кодовых точек согласно Исправлению Unicode № 9; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_utf8_string", "is_utf8_string_loc", и "is_utf8_string_loclen" для проверки целых строк.

Обратите также внимание, что UTF-8 "инвариантный" символ (т.е. ASCII на машинах, не EBCDIC) является допустимым UTF-8 символом.

STRLEN  isUTF8_CHAR(const U8 *s, const U8 *e)

isUTF8_CHAR_flags

Принимает ненулевое значение, если первые несколько байтов строки, начиная с s и не выходя за пределы e - 1, являются корректной UTF-8 последовательностью, расширенной Perl, представляющей некоторую кодовую точку, с учётом ограничений, заданных flags; в противном случае принимает значение 0. Если ненулевое, значение указывает, сколько байтов, начиная с s , составляют представление кодовой точки. Любые оставшиеся байты до e, но после необходимых для формирования первой кодовой точки в s, не проверяются.

Если flags равно 0, это даёт те же результаты, что и "isUTF8_CHAR"; если flags равно UTF8_DISALLOW_ILLEGAL_INTERCHANGE, это даёт те же результаты, что и "isSTRICT_UTF8_CHAR"; а если flags равно UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE, это даёт те же результаты, что и "isC9_STRICT_UTF8_CHAR". В противном случае flags может быть любой комбинацией флагов UTF8_DISALLOW_foo , понимаемых "utf8n_to_uvchr", с теми же значениями.

Эти три альтернативных макроса предназначены для наиболее часто используемых проверок; они, вероятно, будут работать несколько быстрее, чем этот более общий макрос, так как они могут быть встроены в ваш код.

Используйте "is_utf8_string_flags", "is_utf8_string_loc_flags", и "is_utf8_string_loclen_flags" для проверки целых строк.

STRLEN  isUTF8_CHAR_flags(const U8 *s, const U8 *e,
                           const U32 flags)

pv_uni_display

Создаёт в скаляре dsv отображаемую версию строки spv, длины len, при этом отображаемая версия не должна превышать pvlim байт (если она длиннее, остальная часть усекается, и к ней добавляется "...").

Аргумент flags может иметь UNI_DISPLAY_ISPRINT установленным для отображения isPRINT() символов как таковых, UNI_DISPLAY_BACKSLASH для отображения \\[nrfta\\] как обрамлённых обратным слешем (например, "\n") (UNI_DISPLAY_BACKSLASH предпочтительнее UNI_DISPLAY_ISPRINT для "\\"). UNI_DISPLAY_QQ (и его псевдоним UNI_DISPLAY_REGEX) оба включают UNI_DISPLAY_BACKSLASH и UNI_DISPLAY_ISPRINT.

Возвращается указатель на PV dsv.

См. также "sv_uni_display".

char*   pv_uni_display(SV *dsv, const U8 *spv,
                       STRLEN len, STRLEN pvlim,
                       UV flags)

REPLACEMENT_CHARACTER_UTF8

Это макрос, который вычисляет строковую константу UTF-8 байтов, определяющих символ ЗАМЕЩЕНИЯ Unicode (U+FFFD) для платформы, на которой скомпилирован Perl. Это позволяет коду использовать мнемоническое обозначение этого символа, которое работает как на платформах ASCII, так и на платформах EBCDIC. sizeof(REPLACEMENT_CHARACTER_UTF8) - 1 можно использовать для получения его длины в байтах.

sv_cat_decode

encoding предполагается, что это объект Encode, PV ssv предполагается, что это октеты в этой кодировке, и декодирование ввода начинается с позиции, на которую указывал (PV + *offset). dsv будет конкатенирован с декодированной UTF-8 строкой из ssv. Декодирование завершится, когда в выходных данных декодирования появится строка tstr или ввод завершится на PV ssv. Значение, на которое указывает offset, будет изменено на последнюю позицию ввода в ssv.

Возвращает ИСТИНА, если терминатор был найден, в противном случае возвращает ЛОЖЬ.

bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
                      int *offset, char* tstr, int tlen)

sv_recode_to_utf8

encoding предполагается, что это объект Encode, на входе PV sv предполагается, что это октеты в этой кодировке, а sv будет преобразовано в Unicode (и UTF-8).

Если sv уже является UTF-8 (или если это не POK) или если encoding не является ссылкой, ничего не делается с sv. Если encoding не является объектом кодирования Encode::XS, произойдут неприятности. (См. cpan/Encode/encoding.pm и Encode.)

Возвращается PV sv.

char*   sv_recode_to_utf8(SV* sv, SV *encoding)

sv_uni_display

Создаёт в скаляре dsv отображаемую версию скаляра sv, при этом отображаемая версия не должна превышать pvlim байт (если она длиннее, остальная часть усекается и добавляется "...").

Аргумент flags такой же, как в "pv_uni_display"().

Возвращается указатель на PV dsv.

char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
                       UV flags)

to_utf8_fold

УСТАРЕЛО! Планируется удалить эту функцию из будущей версии Perl. Не используйте её в новом коде; удалите её из существующего кода.

Вместо этого используйте "toFOLD_utf8_safe".

UV      to_utf8_fold(const U8 *p, U8* ustrp,
                     STRLEN *lenp)

to_utf8_lower

Вместо этого используйте "toLOWER_utf8_safe".

UV      to_utf8_lower(const U8 *p, U8* ustrp,
                      STRLEN *lenp)

to_utf8_title

Вместо этого используйте "toTITLE_utf8_safe".

UV      to_utf8_title(const U8 *p, U8* ustrp,
                      STRLEN *lenp)

to_utf8_upper

Вместо этого используйте "toUPPER_utf8_safe".

UV      to_utf8_upper(const U8 *p, U8* ustrp,
                      STRLEN *lenp)

utf8n_to_uvchr

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. В большинстве случаев следует использовать "utf8_to_uvchr_buf"() вместо непосредственного вызова этой функции.

Функция низкого уровня для декодирования UTF-8. Возвращает значение кода первого символа в строке s, которая предполагается закодированной в UTF-8 (или UTF-EBCDIC), и длина которой не превышает curlen байт; *retlen (если retlen не равно NULL) будет установлено в длину этого символа в байтах.

Значение flags определяет поведение при обнаружении в s некорректного символа UTF-8. Если flags равно 0, обнаружение некорректного символа приводит к возвращению нуля и установке *retlen, так что (s + *retlen) становится следующей возможной позицией в s, которая могла бы начинать корректный символ. Также, если предупреждения UTF-8 не отключены лексически, выводится предупреждение. Некоторые последовательности ввода UTF-8 могут содержать несколько ошибок. Эта функция пытается найти все возможные ошибки в каждом вызове, поэтому могут быть выведены несколько предупреждений для одной и той же последовательности.

Различные флаги ALLOW могут быть установлены в flags для разрешения (и предотвращения вывода предупреждений) отдельных типов ошибок, таких как избыточная длина последовательности (то есть, когда существует более короткая последовательность, которая может выразить тот же код символа; избыточные последовательности прямо запрещены в стандарте UTF-8 из-за потенциальных проблем безопасности). Другой пример ошибки — первый байт символа, который не является допустимым начальным байтом. Список таких флагов см. в файле utf8.h. Даже если ошибка разрешена, эта функция обычно возвращает заменяющий символ Юникода при обнаружении ошибки. В файле utf8.h есть флаги, которые переопределяют это поведение для избыточных ошибок, но использовать их следует только в очень специализированных целях.

Флаг UTF8_CHECK_ONLY переопределяет поведение при обнаружении недопустимой (по другим флагам) ошибки. Если этот флаг установлен, процедура предполагает, что вызывающая сторона будет выводить предупреждение, и эта функция незаметно установит retlen на значение -1 (приведенное к типу STRLEN) и вернет ноль.

Обратите внимание, что этот API требует различения успешного декодирования символа NUL, и возврата ошибки (если не установлен флаг UTF8_CHECK_ONLY), так как в обоих случаях возвращается 0, и в зависимости от ошибки, retlen может быть установлено в 1. Чтобы отличить случаи, после возвращения нуля, проверьте, равен ли первый байт s нулю. Если да, то на входе был символ NUL; если нет, на входе была ошибка. Или вы можете использовать "utf8n_to_uvchr_error".

Некоторые коды символов считаются проблемными. К ним относятся суррогаты Юникода, незначащие символы Юникода и коды символов, превышающие максимальное значение Юникода 0x10FFFF. По умолчанию они обрабатываются как обычные символы, но в определенных ситуациях требуется специальная обработка, которую можно указать с помощью параметра flags. Если flags содержит UTF8_DISALLOW_ILLEGAL_INTERCHANGE, все три класса обрабатываются как ошибки и обрабатываются как таковые. Флаги UTF8_DISALLOW_SURROGATE, UTF8_DISALLOW_NONCHAR, и UTF8_DISALLOW_SUPER (для значений, превышающих максимальное допустимое значение Юникода) могут быть установлены для запрещения этих категорий индивидуально. UTF8_DISALLOW_ILLEGAL_INTERCHANGE ограничивает допустимые входы строго определенными символами UTF-8, традиционно определенными Юникодом. Используйте UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE для использования определения строгости, заданного в Поправке к стандарту Юникода №9. Разница между традиционной строгими требованиями и требованиями C9 заключается в том, что последние не запрещают незначащие символы. (Тем не менее, они по-прежнему не рекомендуются.) Более подробная информация в разделе "Незначащие символы" в perlunicode.

Флаги UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_ILLEGAL_C9_INTERCHANGE, UTF8_WARN_SURROGATE, UTF8_WARN_NONCHAR, и UTF8_WARN_SUPER вызовут сообщения об ошибках для соответствующих категорий, но при этом сами символы будут считаться допустимыми (не ошибочными). Чтобы категория обрабатывалась как ошибка и выводилось предупреждение, задайте оба флага WARN и DISALLOW. (Однако обратите внимание, что предупреждения не выводятся, если они лексически отключены или если также задан флаг UTF8_CHECK_ONLY.)

Чрезвычайно большие коды символов никогда не были определены в каком-либо стандарте и требуют расширения UTF-8 для выражения, что Perl делает. Вероятно, программы, написанные на других языках, кроме Perl, не смогут читать файлы, содержащие эти символы; также Perl не сможет понять файлы, записанные с помощью другого расширения. По этим причинам существует отдельный набор флагов, которые могут выводить предупреждения и/или запрещать эти чрезвычайно большие коды символов, даже если другие коды символов, превышающие значения Юникода, принимаются. Это флаги UTF8_WARN_PERL_EXTENDED и UTF8_DISALLOW_PERL_EXTENDED . Более подробная информация в разделе "UTF8_GOT_PERL_EXTENDED". Конечно, UTF8_DISALLOW_SUPER будет обрабатывать все коды символов, превышающие Юникод, включая эти, как ошибки. (Обратите внимание, что стандарт Юникода считает всё, что выше 0x10FFFF, недействительным, но существуют стандарты, предшествующие ему, которые допускают значения до 0x7FFF_FFFF (2**31 - 1))

Для обратной совместимости сохраняется несколько неоднозначно названный синоним для UTF8_WARN_PERL_EXTENDED: UTF8_WARN_ABOVE_31_BIT. Аналогично, UTF8_DISALLOW_ABOVE_31_BIT можно использовать вместо более точного наименования UTF8_DISALLOW_PERL_EXTENDED. Названия являются вводящими в заблуждение, потому что эти флаги могут применяться к символам, которые фактически помещаются в 31 бит. Это происходит на платформах EBCDIC и иногда, когда также присутствует ошибка избыточной длины. Новые имена точно отражают ситуацию во всех случаях.

Все остальные коды символов, соответствующие символам Юникода, включая символы частного использования и те, которые ещё не назначены, никогда не считаются ошибочными и никогда не вызывают предупреждения.

UV      utf8n_to_uvchr(const U8 *s, STRLEN curlen,
                       STRLEN *retlen, const U32 flags)

utf8n_to_uvchr_error

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Большинство кодов должно использовать "utf8_to_uvchr_buf"() вместо прямого вызова данной функции.

Эта функция предназначена для кодов, которым требуется узнать точное(ые) искажение(ия) при обнаружении ошибки. Если вам также нужно узнать сгенерированные сообщения об ошибках, используйте "utf8n_to_uvchr_msgs"() вместо этого.

Она похожа на "utf8n_to_uvchr", но принимает дополнительный параметр, помещаемый после всех остальных, errors. Если этот параметр равен 0, эта функция ведет себя идентично "utf8n_to_uvchr". В противном случае, errors должен указывать на переменную U32, которую эта функция устанавливает для указания любых обнаруженных ошибок. По возвращении, если *errors равно 0, ошибок не найдено. В противном случае, *errors является побитовым OR битов, описанных в списке ниже. Некоторые из этих битов будут установлены, если обнаружено искажение, даже если входной flags параметр указывает, что данное искажение разрешено; эти исключения отмечены:

UTF8_GOT_PERL_EXTENDED

Последовательность ввода не является стандартным UTF-8, а является расширением Perl. Этот бит устанавливается только в том случае, если входной flags параметр содержит либо флаги UTF8_DISALLOW_PERL_EXTENDED, либо UTF8_WARN_PERL_EXTENDED.

Кодовые точки выше 0x7FFF_FFFF (2**31 - 1) никогда не были определены в каком-либо стандарте, поэтому для их выражения необходимо использовать какое-то расширение. Perl использует естественное расширение UTF-8 для представления значений до 2**36-1 и придумал дополнительное расширение для представления ещё больших значений, так что любая кодовая точка, помещающаяся в 64-битное слово, может быть представлена. Текст, использующий эти расширения, вряд ли будет переносимым для кода, не являющегося кодом Perl. Мы объединяем оба эти расширения и называем их расширенным UTF-8 Perl. Существуют и другие расширения, придуманные людьми, несовместимые с расширениями Perl.

На платформах EBCDIC, начиная с Perl v5.24, расширение Perl для представления чрезвычайно высоких кодовых точек начинает действовать при 0x3FFF_FFFF (2**30 -1), что ниже, чем на ASCII. До этого кодовые точки 2**31 и выше просто не могли быть представлены, и использовался другой, несовместимый метод для представления кодовых точек между 2**30 и 2**31 - 1.

На обеих платформах, ASCII и EBCDIC, UTF8_GOT_PERL_EXTENDED устанавливается, если используется расширенный UTF-8 Perl.

В более ранних версиях Perl этот бит назывался UTF8_GOT_ABOVE_31_BIT, которое вы по-прежнему можете использовать для обратной совместимости. Это название вводит в заблуждение, так как этот флаг может быть установлен, когда кодовая точка фактически помещается в 31 бит. Это происходит на платформах EBCDIC и иногда, когда также присутствует искажение неполного представления. Новое имя точно описывает ситуацию во всех случаях.

UTF8_GOT_CONTINUATION

Последовательность ввода была искажена, так как первый байт был байтом продолжения UTF-8.

UTF8_GOT_EMPTY

Входящий curlen параметр был равен 0.

UTF8_GOT_LONG

Последовательность ввода была искажена, так как существует другая последовательность, которая оценивается как та же кодовая точка, но эта последовательность короче.

До Unicode 3.1 программы могли принимать это искажение, но было обнаружено, что это создает проблемы безопасности.

UTF8_GOT_NONCHAR

Кодовая точка, представленная последовательностью ввода UTF-8, соответствует кодовой точке не-символа Unicode. Этот бит устанавливается только в том случае, если входной flags параметр содержит либо флаги UTF8_DISALLOW_NONCHAR, либо UTF8_WARN_NONCHAR.

UTF8_GOT_NON_CONTINUATION

Последовательность ввода была искажена, так как в позиции, где должен быть байт продолжения, был найден байт не-продолжения. См. также "UTF8_GOT_SHORT".

UTF8_GOT_OVERFLOW

Последовательность ввода была искажена, так как она соответствует кодовой точке, которая не может быть представлена в количестве битов, доступных в IV на текущей платформе.

UTF8_GOT_SHORT

Последовательность ввода была искажена, так как curlen меньше, чем требуется для полной последовательности. Другими словами, ввод относится к частичной последовательности символов.

UTF8_GOT_SHORT и UTF8_GOT_NON_CONTINUATION оба указывают на слишком короткую последовательность. Разница в том, что UTF8_GOT_NON_CONTINUATION всегда указывает на ошибку, а UTF8_GOT_SHORT означает, что была просмотрена неполная последовательность. Если другие флаги отсутствуют, это означает, что последовательность была валидна до той части, которая была просмотрена. В зависимости от приложения, это может означать одно из трех:

Параметр длины curlen был слишком маленьким, и функция не смогла проверить все необходимые байты.
Буфер, на который просматривается информация, основан на чтении данных, а полученные данные остановились посередине символа, так что следующее чтение прочитает оставшуюся часть этого символа. (От вызывающей функции зависит, как обрабатывать разделенные байты).
Это реальная ошибка, и частичная последовательность — всё, что мы получим.

UTF8_GOT_SUPER

Последовательность ввода была искажена, так как она соответствует кодовой точке, не являющейся кодовой точкой Unicode; то есть, выше допустимого максимального значения Unicode. Этот бит устанавливается только в том случае, если входной flags параметр содержит либо флаги UTF8_DISALLOW_SUPER, либо UTF8_WARN_SUPER.

UTF8_GOT_SURROGATE

Последовательность ввода была искажена, так как она соответствует кодовой точке-суффиксату UTF-16. Этот бит устанавливается только в том случае, если входной flags параметр содержит либо флаги UTF8_DISALLOW_SURROGATE, либо UTF8_WARN_SURROGATE.

Для самостоятельной обработки ошибок вызовите эту функцию с флагом UTF8_CHECK_ONLY для подавления любых предупреждений, а затем проверьте возвращаемое значение *errors.

UV      utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
                             STRLEN *retlen,
                             const U32 flags,
                             U32 * errors)

utf8n_to_uvchr_msgs

Эта функция предназначена для кодов, которым требуется узнать точное(ые) искажение(ия) при обнаружении ошибки и получить соответствующие сообщения об ошибках или предупреждениях, а не отображать их. Все сообщения, которые были бы отображены, если бы все лексические предупреждения были включены, будут возвращены.

Она точно такая же, как "utf8n_to_uvchr_error", но принимает дополнительный параметр, помещаемый после всех остальных, msgs. Если этот параметр равен 0, эта функция ведет себя идентично "utf8n_to_uvchr_error". В противном случае, msgs должен указывать на переменную AV *, в которой эта функция создает новый массив (AV) для хранения любых соответствующих сообщений. Элементы массива упорядочены так, что первое сообщение, которое должно было быть отображено, находится в элементе 0 и так далее. Каждый элемент является хэш-таблицей с тремя парами ключ-значение, как указано ниже:

text: Текст сообщения как SVpv.
warn_categories: Категория (или категории) предупреждения, упакованные в SVuv.
flag: Один одиночный битовый флаг, связанный с этим сообщением, в SVuv. Бит соответствует одному биту в возвращаемом значении *errors, например, UTF8_GOT_LONG.

Важно отметить, что указание этого параметра как не-null приведет к подавлению любых предупреждений, которые эта функция могла бы сгенерировать, и они вместо этого будут помещены в *msgs. Вызывающая функция может проверять состояние лексических предупреждений (или не проверять), выбирая, что делать с возвращаемыми сообщениями.

Если флаг UTF8_CHECK_ONLY передан, никакие предупреждения не генерируются, и, следовательно, AV не создается.

Конечно, вызывающая функция несет ответственность за освобождение возвращаемого AV.

UV      utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
                            STRLEN *retlen,
                            const U32 flags,
                            U32 * errors, AV ** msgs)

utf8n_to_uvuni

Используйте вместо этого "utf8_to_uvchr_buf" или в редких случаях "utf8n_to_uvchr".

Эта функция была полезна для кода, который хотел обработать и EBCDIC, и ASCII платформы с свойствами Unicode, но начиная с Perl v5.20, различия между платформами в основном стали незаметными для большинства кодов, поэтому эта функция вряд ли вам нужна. Если вам действительно нужна именно эта функциональность, используйте вместо этого NATIVE_TO_UNI(utf8_to_uvchr_buf(...)) или NATIVE_TO_UNI(utf8n_to_uvchr(...)).

UV      utf8n_to_uvuni(const U8 *s, STRLEN curlen,
                       STRLEN *retlen, U32 flags)

UTF8SKIP

возвращает количество байтов в символе UTF-8, первый (возможно, единственный) байт которого указан с помощью s.

STRLEN  UTF8SKIP(char* s)

utf8_distance

Возвращает количество символов UTF-8 между указателями UTF-8 a и b.

ПРЕДУПРЕЖДЕНИЕ: используйте только в том случае, если вы *уверены*, что указатели указывают внутри одного и того же буфера UTF-8.

IV      utf8_distance(const U8 *a, const U8 *b)

utf8_hop

Возвращает указатель UTF-8 s, смещенный на off символов вперёд или назад.

ПРЕДУПРЕЖДЕНИЕ: не используйте следующее, если вы *уверены*, что off находится внутри данных UTF-8, на которые указывает s *и* что при входе s выровнен на первом байте символа или сразу после последнего байта символа.

U8*     utf8_hop(const U8 *s, SSize_t off)

utf8_hop_back

Возвращает указатель UTF-8 s смещённый на не более чем off символов назад.

off должно быть неположительным.

s должен быть равен или стоять после start.

При перемещении назад не будет перемещаться перед start.

Не превысит этот предел даже если строка не является корректным UTF-8.

U8*     utf8_hop_back(const U8 *s, SSize_t off,
                      const U8 *start)

utf8_hop_forward

Возвращает указатель UTF-8 s смещённый на не более чем off символов вперёд.

off должно быть неотрицательным.

s должен быть равен или стоять перед end.

При перемещении вперёд не будет перемещаться за пределы end.

Не превысит этот предел даже если строка не является корректным UTF-8.

U8*     utf8_hop_forward(const U8 *s, SSize_t off,
                         const U8 *end)

utf8_hop_safe

Возвращает указатель на UTF-8 последовательность, смещенную на максимум на off символов вперёд или назад.

При движении назад не перемещается до start.

При движении вперёд не перемещается дальше end.

Превышение этих пределов не произойдёт, даже если строка не является корректной UTF-8 последовательностью.

U8*     utf8_hop_safe(const U8 *s, SSize_t off,
                      const U8 *start, const U8 *end)

UTF8_IS_INVARIANT

Возвращает 1, если байт c представляет тот же символ в UTF-8 кодировке, что и без кодирования; иначе возвращает 0. UTF-8 инвариантные символы могут быть скопированы без изменений при преобразовании в/из UTF-8, что экономит время.

Несмотря на название, эта макрос даёт правильный результат, если входная строка, из которой c берется, не закодирована в UTF-8.

См. "UVCHR_IS_INVARIANT" для проверки, является ли UV инвариантным.

bool    UTF8_IS_INVARIANT(char c)

UTF8_IS_NONCHAR

Возвращает ненулевое значение, если первые байты строки, начиная с s и не дальше, чем e - 1, являются корректной UTF-8 последовательностью, представляющей один из символов Юникода, не являющихся символами; в противном случае возвращает 0. Если ненулевое значение, то оно показывает, сколько байтов, начиная с s составляют представление этого символа.

bool    UTF8_IS_NONCHAR(const U8 *s, const U8 *e)

UTF8_IS_SUPER

Напомним, что Perl поддерживает расширение UTF-8, которое может кодировать символы с кодовыми точками, большие, чем определенные Юникодом, которые находятся в диапазоне 0..0x10FFFF.

Эта макрос возвращает ненулевое значение, если первые байты строки, начиная с s и не дальше, чем e - 1, относятся к этому расширению UTF-8; в противном случае возвращает 0. Если ненулевое значение, то оно показывает, сколько байтов, начиная с s составляют представление этого символа.

0 возвращается, если байты не являются корректной расширенной UTF-8 последовательностью или если они представляют символ, который не может быть сохранён в UV на текущей платформе. Таким образом, эта макрос может возвращать разные результаты на 64-битной и 32-битной платформах.

Обратите внимание, что символы с кодовыми точками, больше, чем может храниться в IV на текущей машине, являются недопустимыми.

bool    UTF8_IS_SUPER(const U8 *s, const U8 *e)

UTF8_IS_SURROGATE

Возвращает ненулевое значение, если первые байты строки, начиная с s и не дальше, чем e - 1, являются корректной UTF-8 последовательностью, представляющей один из суррогатных символов Юникода; в противном случае возвращает 0. Если ненулевое значение, то оно показывает, сколько байтов, начиная с s составляют представление этого символа.

bool    UTF8_IS_SURROGATE(const U8 *s, const U8 *e)

utf8_length

Возвращает количество символов в последовательности UTF-8 кодированных байтов, начиная с s и заканчивая байтом перед e. Если <s> и <e> указывают на одно и то же место, возвращает 0 без вывода предупреждения.

Если e < s или если сканирование выйдет за пределы e, генерируется предупреждение UTF8 и возвращается количество корректных символов.

STRLEN  utf8_length(const U8* s, const U8 *e)

UTF8_SAFE_SKIP

возвращает 0, если s >= e; в противном случае возвращает количество байтов в UTF-8 кодированном символе, первый байт которого указан в s. Но никогда не возвращает значение больше e. В сборках DEBUG, оно проверяет, что s <= e.

STRLEN  UTF8_SAFE_SKIP(char* s, char* e)

utf8_to_bytes

Преобразует строку "s" длиной *lenp из UTF-8 в кодировку нативных байтов. В отличие от "bytes_to_utf8", эта функция перезаписывает исходную строку и обновляет *lenp, чтобы содержать новую длину. Возвращает ноль при ошибке (оставляя "s" без изменений) и устанавливает *lenp в -1.

После успешного возврата количество вариантов в строке можно вычислить, сохранив значение *lenp до вызова и вычитав значение *lenp после вызова.

Если вам нужна копия строки, см. "bytes_from_utf8".

U8*     utf8_to_bytes(U8 *s, STRLEN *lenp)

utf8_to_uvchr

УСТАРЕВШАЯ функция! Планируется удалить эту функцию в будущих версиях Perl. Не используйте её в новом коде; удалите её из существующего кода.

Возвращает кодовую точку первого символа в строке s, которая предполагается как закодированная в UTF-8; retlen будет установлен как длина этого символа в байтах.

Не все, но некоторые, неправильно сформированные UTF-8 последовательности обнаруживаются, и, фактически, некоторые неправильно сформированные входные данные могут привести к чтению за пределы буфера ввода, поэтому эта функция устарела. Используйте "utf8_to_uvchr_buf" вместо неё.

Если s указывает на одну из обнаруженных неправильно сформированных последовательностей, и предупреждения UTF8 включены, возвращается ноль, и *retlen устанавливается (если retlen не равно NULL) в -1. Если эти предупреждения выключены, вычисленное значение, если оно определено (или заменяющий символ Юникода, если нет), возвращается неявно, и *retlen устанавливается (если retlen не равно NULL), так что (s + *retlen) - это следующее возможное положение в s, которое может начать корректно сформированный символ. См. "utf8n_to_uvchr" для получения подробностей о том, когда возвращается заменяющий символ.

UV      utf8_to_uvchr(const U8 *s, STRLEN *retlen)

utf8_to_uvchr_buf

Возвращает кодовую точку первого символа в строке s, которая предполагается как закодированная в UTF-8; send указывает на 1 позицию после конца s. *retlen будет установлен как длина этого символа в байтах.

Если s не указывает на корректно сформированный UTF-8 символ и предупреждения UTF8 включены, возвращается ноль и *retlen устанавливается (если retlen не равно NULL) в -1. Если эти предупреждения выключены, вычисленное значение, если оно определено (или заменяющий символ Юникода, если нет), возвращается неявно, и *retlen устанавливается (если retlen не равно NULL) так, что (s + *retlen) - это следующее возможное положение в s, которое может начать корректно сформированный символ. См. "utf8n_to_uvchr" для получения подробностей о том, когда возвращается заменяющий символ.

UV      utf8_to_uvchr_buf(const U8 *s, const U8 *send,
                          STRLEN *retlen)

utf8_to_uvuni_buf

Только в очень редких случаях код должен работать с кодовыми точками Юникода (по сравнению с нативными). В этих редких случаях используйте NATIVE_TO_UNI(utf8_to_uvchr_buf(...)) вместо. Если вы не уверены, что это один из таких случаев, то предположите, что это не так, и используйте обычный utf8_to_uvchr_buf.

Возвращает кодовую точку Юникода (не нативного) первого символа в строке s, которая предполагается как закодированная в UTF-8; send указывает на 1 позицию после конца s. retlen будет установлен как длина этого символа в байтах.

Если s не указывает на корректно сформированный UTF-8 символ и предупреждения UTF8 включены, возвращается ноль и *retlen устанавливается (если retlen не равно NULL) в -1. Если эти предупреждения выключены, вычисленное значение, если оно определено (или заменяющий символ Юникода, если нет), возвращается неявно, и *retlen устанавливается (если retlen не равно NULL), так что (s + *retlen) - это следующее возможное положение в s, которое может начать корректно сформированный символ. См. "utf8n_to_uvchr" для получения подробностей о том, когда возвращается заменяющий символ.

UV      utf8_to_uvuni_buf(const U8 *s, const U8 *send,
                          STRLEN *retlen)

UVCHR_IS_INVARIANT

Возвращает 1, если представление кодовой точки cp одинаково при кодировании в UTF-8 и без кодирования; в противном случае возвращает 0. UTF-8 инвариантные символы могут быть скопированы без изменений при преобразовании в/из UTF-8, что экономит время. cp является кодовой точкой Юникода, если выше 255; в противном случае является нативной кодовой точкой платформы.

bool    UVCHR_IS_INVARIANT(UV cp)

UVCHR_SKIP

возвращает количество байтов, необходимое для представления кодовой точки cp при кодировании в UTF-8. cp - это нативная (ASCII или EBCDIC) кодовая точка, если меньше 255; кодовая точка Юникода в противном случае.

STRLEN  UVCHR_SKIP(UV cp)

uvchr_to_utf8

Добавляет UTF-8 представление нативной кодовой точки uv в конец строки d; d должен иметь как минимум UVCHR_SKIP(uv)+1 (до UTF8_MAXBYTES+1 свободных) байтов. Значение возврата - указатель на байт после конца нового символа. Другими словами,

d = uvchr_to_utf8(d, uv);

является рекомендуемым способом работы с широкими кодовыми точками нативных символов

*(d++) = uv;

Эта функция принимает любую кодовую точку от 0 до IV_MAX. IV_MAX обычно равно 0x7FFF_FFFF в 32-битной системе.

Можно запретить или выводить предупреждения о кодовых точках, не являющихся кодовыми точками Юникода или проблематичных кодовых точках, используя "uvchr_to_utf8_flags".

U8*     uvchr_to_utf8(U8 *d, UV uv)

uvchr_to_utf8_flags

Добавляет UTF-8 представление кодового пункта нативного кода uv в конец строки d; d должно иметь как минимум UVCHR_SKIP(uv)+1 (до UTF8_MAXBYTES+1) свободных байтов. Значение возврата — указатель на байт после конца нового символа. Другими словами,

d = uvchr_to_utf8_flags(d, uv, flags);

или, в большинстве случаев,

d = uvchr_to_utf8_flags(d, uv, 0);

Это осознанный Unicode способ сказать

*(d++) = uv;

Если flags равно 0, эта функция принимает любой кодовый пункт от 0 до IV_MAX в качестве входных данных. IV_MAX обычно равно 0x7FFF_FFFF в 32-битном слове.

Указание flags может дополнительно ограничить то, что разрешено, и то, что не должно вызывать предупреждение, как указано ниже:

Если uv — это суррогат Unicode кодового пункта, и UNICODE_WARN_SURROGATE установлено, функция выведет предупреждение, если включены предупреждения UTF8. Если вместо этого UNICODE_DISALLOW_SURROGATE установлено, функция завершится ошибкой и вернёт NULL. Если оба флага установлены, функция выведет предупреждение и вернёт NULL.

Аналогично, флаги UNICODE_WARN_NONCHAR и UNICODE_DISALLOW_NONCHAR влияют на то, как функция обрабатывает несимвольный Unicode кодовый пункт.

И аналогичным образом, флаги UNICODE_WARN_SUPER и UNICODE_DISALLOW_SUPER влияют на обработку кодовых пунктов, превышающих максимальное значение Unicode 0x10FFFF. Языки, отличные от Perl, могут не справиться с файлами, содержащими эти пункты.

Флаг UNICODE_WARN_ILLEGAL_INTERCHANGE выбирает все три вышеупомянутых флага предупреждения; и UNICODE_DISALLOW_ILLEGAL_INTERCHANGE выбирает все три флага запрета. UNICODE_DISALLOW_ILLEGAL_INTERCHANGE ограничивает допустимые входные данные строгим UTF-8, традиционно определенным Unicode. Аналогично, UNICODE_WARN_ILLEGAL_C9_INTERCHANGE и UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE являются сокращениями для выбора вышеупомянутых флагов Unicode и суррогатов, но не флагов несимвольных кодовых пунктов, как определено в Unicode Corrigendum #9. См. "Несимвольные кодовые пункты" в perlunicode.

Чрезвычайно высокие кодовые пункты никогда не были указаны в каком-либо стандарте и требуют расширения UTF-8 для выражения, которое Perl делает. Вероятно, программы, написанные на чём-то другом, кроме Perl, не смогут прочитать файлы, содержащие эти пункты; также Perl не поймёт файлы, написанные чем-то, что использует другое расширение. По этим причинам существует отдельный набор флагов, которые могут предупреждать и/или запрещать эти чрезвычайно высокие кодовые пункты, даже если другие пункты выше Unicode принимаются. Это флаги UNICODE_WARN_PERL_EXTENDED и UNICODE_DISALLOW_PERL_EXTENDED. Для получения дополнительной информации см. "UTF8_GOT_PERL_EXTENDED". Конечно, UNICODE_DISALLOW_SUPER будет обрабатывать все кодовые пункты выше Unicode, включая эти, как некорректные. (Обратите внимание, что стандарт Unicode считает всё, что выше 0x10FFFF, незаконным, но существуют стандарты, предшествующие ему, которые позволяют до 0x7FFF_FFFF (2**31 -1)).

Несколько вводящий в заблуждение синоним для UNICODE_WARN_PERL_EXTENDED сохранён для обратной совместимости: UNICODE_WARN_ABOVE_31_BIT. Аналогично, UNICODE_DISALLOW_ABOVE_31_BIT можно использовать вместо более точного названия UNICODE_DISALLOW_PERL_EXTENDED. Названия вводят в заблуждение, потому что на платформах EBCDIC эти флаги могут применяться к кодовым пунктам, которые фактически подходят в 31 бит. Новые имена точно описывают ситуацию во всех случаях.

U8*     uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)

uvchr_to_utf8_flags_msgs

ЭТУ ФУНКЦИЮ НЕОБХОДИМО ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ.

Большинство кода должно использовать "uvchr_to_utf8_flags"() вместо прямого вызова.

Эта функция предназначена для кода, который хочет, чтобы любые предупреждения и/или сообщения об ошибках возвращались вызывающему методу, а не отображались. Все сообщения, которые были бы отображены, если бы все лексические предупреждения были включены, будут возвращены.

Она похожа на "uvchr_to_utf8_flags", но принимает дополнительный параметр после всех остальных, msgs. Если этот параметр равен 0, эта функция ведёт себя так же, как "uvchr_to_utf8_flags". В противном случае, msgs должен быть указателем на переменную HV *, в которую эта функция создаёт новый HV для хранения соответствующих сообщений. Хэш имеет три пары ключ-значение, как указано ниже:

text: Текст сообщения в виде SVpv.
warn_categories: Категория(и) предупреждения(ий), упакованная(ые) в SVuv.
flag: Единый флаг, связанный с этим сообщением, в виде SVuv. Этот бит соответствует некоторому биту в возвращаемом значении *errors , например, UNICODE_GOT_SURROGATE.

Важно отметить, что указание этого параметра как не-NULL приведёт к подавлению любых предупреждений, которые эта функция могла бы иначе сгенерировать, и вместо этого они будут помещены в *msgs. Вызывающий метод может проверить состояние лексических предупреждений (или нет) при выборе того, что делать с возвращёнными сообщениями.

Конечно, вызывающий метод отвечает за освобождение возвращённого HV.

U8*     uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags,
                                 HV ** msgs)

uvoffuni_to_utf8_flags

ЭТУ ФУНКЦИЮ НЕОБХОДИМО ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Вместо этого почти весь код должен использовать "uvchr_to_utf8" или "uvchr_to_utf8_flags".

Эта функция похожа на них, но входные данные — строгий Unicode (в отличие от нативного) кодовый пункт. Только в очень редких случаях код не должен использовать нативный кодовый пункт.

Для получения подробностей см. описание "uvchr_to_utf8_flags".

U8*     uvoffuni_to_utf8_flags(U8 *d, UV uv,
                               const UV flags)

uvuni_to_utf8_flags

Вместо этого вы почти наверняка захотите использовать "uvchr_to_utf8" или "uvchr_to_utf8_flags".

Эта функция — устаревший синоним для "uvoffuni_to_utf8_flags", которая сама по себе, хотя и не устаревшая, должна использоваться только в отдельных случаях. Эти функции были полезны для кода, который хотел обрабатывать как EBCDIC, так и ASCII платформы с Unicode свойствами, но начиная с Perl v5.20, различия между платформами в основном сделаны невидимыми для большинства кода, поэтому эта функция вряд ли то, что вам нужно.

U8*     uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)

valid_utf8_to_uvchr

Как "utf8_to_uvchr_buf", но вызывать её следует только тогда, когда известно, что следующий символ в строке UTF-8 s имеет правильную форму (например, он проходит "isUTF8_CHAR". Разрешён суррогаты, несимвольные кодовые пункты и не-Unicode кодовые пункты.

UV      valid_utf8_to_uvchr(const U8 *s, STRLEN *retlen)

Переменные, созданные `xsubpp` и внутренними функциями `xsubpp`

newXSproto

Используется xsubpp для подключения XSUB как подпрограмм Perl. Добавляет прототипы Perl к подпрограммам.

XS_APIVERSION_BOOTCHECK

Макрос для проверки того, что версия API Perl, с которой был скомпилирован модуль XS, совпадает с версией API интерпретатора Perl, в который он загружается.

XS_APIVERSION_BOOTCHECK;

XS_VERSION

Идентификатор версии модуля XS. Обычно обрабатывается автоматически ExtUtils::MakeMaker. См. "XS_VERSION_BOOTCHECK".

XS_VERSION_BOOTCHECK

Макрос для проверки того, что переменная $VERSION модуля PM совпадает с переменной XS_VERSION модуля XS. Обычно обрабатывается автоматически xsubpp. См. "Ключевое слово VERSIONCHECK: в perlxs".

XS_VERSION_BOOTCHECK;

Предупреждения и завершение работы

ckWARN

Возвращает логическое значение, указывающее, включены ли предупреждения для категории предупреждений w. Если категория по умолчанию включена, даже если она не находится в области действия use warnings, используйте вместо этого макрос "ckWARN_d".

bool    ckWARN(U32 w)

ckWARN2

Аналогично "ckWARN", но принимает две категории предупреждений в качестве входных данных и возвращает ИСТИНУ, если хотя бы одна из них включена. Если какая-либо категория по умолчанию включена, даже если она не находится в области действия use warnings, используйте вместо этого макрос "ckWARN2_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN2(U32 w1, U32 w2)

ckWARN3

Аналогично "ckWARN2", но принимает три категории предупреждений в качестве входных данных и возвращает ИСТИНУ, если хотя бы одна из них включена. Если какая-либо из категорий по умолчанию включена, даже если она не находится в области действия use warnings, используйте вместо этого макрос "ckWARN3_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN3(U32 w1, U32 w2, U32 w3)

ckWARN4

Аналогично "ckWARN3", но принимает четыре категории предупреждений в качестве входных данных и возвращает ИСТИНУ, если хотя бы одна из них включена. Если какая-либо из категорий по умолчанию включена, даже если она не находится в области действия use warnings, используйте вместо этого макрос "ckWARN4_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)

ckWARN_d

Аналогично "ckWARN", но предназначено для использования только в том случае, если категория предупреждения по умолчанию включена, даже если она не находится в области действия use warnings.

bool    ckWARN_d(U32 w)

ckWARN2_d

Аналогично "ckWARN2", но предназначено для использования только в том случае, если хотя бы одна из категорий предупреждений по умолчанию включена, даже если она не находится в области действия use warnings.

bool    ckWARN2_d(U32 w1, U32 w2)

ckWARN3_d

Аналогично "ckWARN3", но предназначено для использования только в том случае, если хотя бы одна из категорий предупреждений по умолчанию включена, даже если она не находится в области действия use warnings.

bool    ckWARN3_d(U32 w1, U32 w2, U32 w3)

ckWARN4_d

Аналогично "ckWARN4", но предназначено для использования только в том случае, если хотя бы одна из категорий предупреждений по умолчанию включена, даже если она не находится в области действия use warnings.

bool    ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)

croak

Это интерфейс XS для функции Perl's die.

Принимает шаблон форматирования в стиле sprintf и список аргументов. Они используются для генерации строкового сообщения. Если сообщение не заканчивается символом новой строки, оно будет дополнено некоторыми указаниями текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке будет использоваться как исключение, по умолчанию возвращая управление ближайшему вложенному eval, но может быть изменено обработчиком $SIG{__DIE__}. В любом случае функция croak никогда не возвращается нормально.

По историческим причинам, если pat равно null, содержимое ERRSV ($@) будет использоваться как сообщение об ошибке или объект вместо построения сообщения об ошибке из аргументов. Если вы хотите выбросить объект, не являющийся строкой, или построить сообщение об ошибке в SV самостоятельно, предпочтительнее использовать функцию "croak_sv", которая не включает перезапись ERRSV.

void    croak(const char *pat, ...)

croak_no_modify

Точно эквивалентно Perl_croak(aTHX_ "%s", PL_no_modify), но генерирует более компактный объектный код, чем при использовании Perl_croak. Меньше кода в путях обработки исключений снижает давление на кэш процессора.

void    croak_no_modify()

croak_sv

Это интерфейс XS для функции Perl's die.

baseex — это сообщение об ошибке или объект. Если это ссылка, она будет использоваться как есть. В противном случае она используется как строка, и если она не заканчивается символом новой строки, она будет дополнена некоторыми указаниями текущего местоположения в коде, как описано для "mess_sv".

Сообщение об ошибке или объект будет использоваться как исключение, по умолчанию возвращая управление ближайшему вложенному eval, но может быть изменено обработчиком $SIG{__DIE__}. В любом случае функция croak_sv никогда не возвращается нормально.

Для завершения работы с простым строковым сообщением может быть удобнее использовать функцию "croak".

void    croak_sv(SV *baseex)

die

Ведет себя так же, как "croak", за исключением типа возвращаемого значения. Ее следует использовать только там, где требуется тип возвращаемого значения OP *. Функция никогда фактически не возвращает значение.

OP *    die(const char *pat, ...)

die_sv

Ведет себя так же, как "croak_sv", за исключением типа возвращаемого значения. Ее следует использовать только там, где требуется тип возвращаемого значения OP *. Функция никогда фактически не возвращает значение.

OP *    die_sv(SV *baseex)

vcroak

Это интерфейс XS для функции Perl's die.

pat и args представляют собой шаблон форматирования в стиле sprintf и заключенный список аргументов. Они используются для генерации строкового сообщения. Если сообщение не заканчивается символом новой строки, оно будет дополнено некоторыми указаниями текущего местоположения в коде, как описано для "mess_sv".

void    vcroak(const char *pat, va_list *args)

vwarn

Это интерфейс XS для функции Perl's warn.

Сообщение об ошибке или объект по умолчанию будет выведен в стандартный поток ошибок, но это может быть изменено обработчиком $SIG{__WARN__}.

В отличие от "vcroak", pat не может быть null.

void    vwarn(const char *pat, va_list *args)

warn

Это интерфейс XS для функции Perl's warn.

В отличие от "croak", pat не может быть null.

void    warn(const char *pat, ...)

warn_sv

Это интерфейс XS для функции Perl's warn.

Для вывода предупреждения с простым строковым сообщением может быть удобнее использовать функцию "warn".

void    warn_sv(SV *baseex)

Функции без документации

Следующие функции помечены как часть публичного API, но в настоящее время не документированы. Используйте их на свой страх и риск, так как интерфейсы могут быть изменены. Функции, которые не указаны в этом документе, не предназначены для использования в публичном доступе и НЕ должны использоваться ни при каких обстоятельствах.

Если вы считаете, что вам нужно использовать одну из этих функций, сначала отправьте электронное письмо по адресу perl5-porters@perl.org. Возможно, есть веская причина, по которой функция не документирована, и ее следует удалить из этого списка; или, возможно, просто никто еще не добрался до ее документации. В последнем случае вас попросят отправить исправление для документации функции. После принятия вашего исправления интерфейс будет считаться стабильным (если не указано иное) и пригодным для использования.

GetVars
Gv_AMupdate
PerlIO_clearerr
PerlIO_close
PerlIO_context_layers
PerlIO_eof
PerlIO_error
PerlIO_fileno
PerlIO_fill
PerlIO_flush
PerlIO_get_base
PerlIO_get_bufsiz
PerlIO_get_cnt
PerlIO_get_ptr
PerlIO_read
PerlIO_seek
PerlIO_set_cnt
PerlIO_set_ptrcnt
PerlIO_setlinebuf
PerlIO_stderr
PerlIO_stdin
PerlIO_stdout
PerlIO_tell
PerlIO_unread
PerlIO_write
_variant_byte_number
amagic_call
amagic_deref_call
any_dup
atfork_lock
atfork_unlock
av_arylen_p
av_iter_p
block_gimme
call_atexit
call_list
calloc
cast_i32
cast_iv
cast_ulong
cast_uv
ck_warner
ck_warner_d
ckwarn
ckwarn_d
clear_defarray
clone_params_del
clone_params_new
croak_memory_wrap
croak_nocontext
csighandler
cx_dump
cx_dup
cxinc
deb
deb_nocontext
debop
debprofdump
debstack
debstackptrs
delimcpy
despatch_signals
die_nocontext
dirp_dup
do_aspawn
do_binmode
do_close
do_gv_dump
do_gvgv_dump
do_hv_dump
do_join
do_magic_dump
do_op_dump
do_open
do_open9
do_openn
do_pmop_dump
do_spawn
do_spawn_nowait
do_sprintf
do_sv_dump
doing_taint
doref
dounwind
dowantarray
dump_eval
dump_form
dump_indent
dump_mstats
dump_sub
dump_vindent
filter_add
filter_del
filter_read
foldEQ_latin1
form_nocontext
fp_dup
fprintf_nocontext
free_global_struct
free_tmps
get_context
get_mstats
get_op_descs
get_op_names
get_ppaddr
get_vtbl
gp_dup
gp_free
gp_ref
gv_AVadd
gv_HVadd
gv_IOadd
gv_SVadd
gv_add_by_type
gv_autoload4
gv_autoload_pv
gv_autoload_pvn
gv_autoload_sv
gv_check
gv_dump
gv_efullname
gv_efullname3
gv_efullname4
gv_fetchfile
gv_fetchfile_flags
gv_fetchpv
gv_fetchpvn_flags
gv_fetchsv
gv_fullname
gv_fullname3
gv_fullname4
gv_handler
gv_name_set
he_dup
hek_dup
hv_common
hv_common_key_len
hv_delayfree_ent
hv_eiter_p
hv_eiter_set
hv_free_ent
hv_ksplit
hv_name_set
hv_placeholders_get
hv_placeholders_set
hv_rand_set
hv_riter_p
hv_riter_set
ibcmp_utf8
init_global_struct
init_stacks
init_tm
instr
is_lvalue_sub
leave_scope
load_module_nocontext
magic_dump
malloc
markstack_grow
mess_nocontext
mfree
mg_dup
mg_size
mini_mktime
moreswitches
mro_get_from_name
mro_get_private_data
mro_set_mro
mro_set_private_data
my_atof
my_atof2
my_atof3
my_chsize
my_cxt_index
my_cxt_init
my_dirfd
my_exit
my_failure_exit
my_fflush_all
my_fork
my_lstat
my_pclose
my_popen
my_popen_list
my_setenv
my_socketpair
my_stat
my_strftime
newANONATTRSUB
newANONHASH
newANONLIST
newANONSUB
newATTRSUB
newAVREF
newCVREF
newFORM
newGVREF
newGVgen
newGVgen_flags
newHVREF
newHVhv
newIO
newMYSUB
newPROG
newRV
newSUB
newSVREF
newSVpvf_nocontext
newSVsv_flags
new_stackinfo
op_refcnt_lock
op_refcnt_unlock
parser_dup
perl_alloc_using
perl_clone_using
pmop_dump
pop_scope
pregcomp
pregexec
pregfree
pregfree2
printf_nocontext
ptr_table_fetch
ptr_table_free
ptr_table_new
ptr_table_split
ptr_table_store
push_scope
re_compile
re_dup_guts
re_intuit_start
re_intuit_string
realloc
reentrant_free
reentrant_init
reentrant_retry
reentrant_size
ref
reg_named_buff_all
reg_named_buff_exists
reg_named_buff_fetch
reg_named_buff_firstkey
reg_named_buff_nextkey
reg_named_buff_scalar
regdump
regdupe_internal
regexec_flags
regfree_internal
reginitcolors
regnext
repeatcpy
rsignal
rsignal_state
runops_debug
runops_standard
rvpv_dup
safesyscalloc
safesysfree
safesysmalloc
safesysrealloc
save_I16
save_I32
save_I8
save_adelete
save_aelem
save_aelem_flags
save_alloc
save_aptr
save_ary
save_bool
save_clearsv
save_delete
save_destructor
save_destructor_x
save_freeop
save_freepv
save_freesv
save_generic_pvref
save_generic_svref
save_hash
save_hdelete
save_helem
save_helem_flags
save_hints
save_hptr
save_int
save_item
save_iv
save_list
save_long
save_mortalizesv
save_nogv
save_op
save_padsv_and_mortalize
save_pptr
save_pushi32ptr
save_pushptr
save_pushptrptr
save_re_context
save_scalar
save_set_svflags
save_shared_pvref

END_OF_DOCUMENT_MARKER

save_sptr
save_svref
save_vptr
savestack_grow
savestack_grow_cnt
scan_num
scan_vstring
seed
set_context
share_hek
si_dup
ss_dup
stack_grow
start_subparse
str_to_version
sv_2iv
sv_2pv
sv_2uv
sv_catpvf_mg_nocontext
sv_catpvf_nocontext
sv_dup
sv_dup_inc
sv_peek
sv_pvn_nomg
sv_setpvf_mg_nocontext
sv_setpvf_nocontext
sys_init
sys_init3
sys_intern_clear
sys_intern_dup
sys_intern_init
sys_term
taint_env
taint_proper
unlnk
unsharepvn
uvuni_to_utf8
vdeb
vform
vload_module
vnewSVpvf
vwarner
warn_nocontext
warner
warner_nocontext
whichsig
whichsig_pv
whichsig_pvn
whichsig_sv

АВТОРЫ

До мая 1997 года этот документ поддерживался Джеффом Окамото <okamoto@corp.hp.com>. Сейчас он поддерживается как часть самого Perl.

С большой помощью и предложениями от Дина Роэриха, Малкольма Бити, Андреаса Кёнига, Пола Хадсона, Ильи Захаревича, Пола Маркесса, Нила Боуэрса, Мэтью Грина, Тима Банса, Спайдер Боардмана, Ульриха Пфайфера, Стивена МакКэманта и Гурусами Сарати.

Список API первоначально был составлен Дином Роэрихом <roehrich@cray.com>.

Обновлено для автоматической генерации из комментариев в исходном коде Бенедиктом Штулем.

СМОТРИТЕ ТАКЖЕ

perlguts, perlxs, perlxstut, perlintern

© 1993–2020 Larry Wall and others
Licensed under the GNU General Public License version 1 or later, or the Artistic License.
The Perl logo is a trademark of the Perl Foundation.
https://perldoc.perl.org/5.30.3/perlapi

perlapi

СОДЕРЖАНИЕ

НАЗВАНИЕ

ОПИСАНИЕ

Функции работы с массивами

Функции обратного вызова

Изменение регистра символов

Классификация символов

Клонирование интерпретатора

Временные метки области видимости во время компиляции

Хэши подсказок COP

Чтение подсказок COP

Операторы пользовательского определения

Функции манипулирования CV

xsubpp переменные и внутренние функции

Средства отладки

Функции отображения и вывода

Функции встраивания

Обработка исключений (простые) Макросы

Функции в файле pp_sort.c

Функции в файле scope.c

Функции в файле vutil.c

"Gimme" Значения

Глобальные переменные

Функции GV

Полезные значения

Функции манипуляции хэш-таблицами

Управление крючками

Интерфейс лексического анализатора

Функции и макросы, связанные с локалями

Магические функции

Управление памятью

Дополнительные функции

Функции MRO

Функции Multicall

Функции чисел

Функции устаревшей обратной совместимости

Дерево обработки опций

Функции обработки деревьев операций

Упаковщики и распаковщики

Структуры данных Pad

Переменные интерпретатора

Функции REGEXP

Макросы управления стеком

Флаги SV

Функции манипулирования SV

Поддержка Unicode

Переменные, созданные xsubpp и внутренними функциями xsubpp

Предупреждения и завершение работы

Функции без документации

АВТОРЫ

СМОТРИТЕ ТАКЖЕ

`xsubpp` переменные и внутренние функции

Переменные, созданные `xsubpp` и внутренними функциями `xsubpp`