perlapi

СОДЕРЖАНИЕ

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

Символы с кодами ниже 256, отличные от ASCII, могут иметь различные значения в зависимости от различных факторов. (См., в частности, perllocale.) Но обычно весь диапазон можно обозначить как ISO-8859-1. Часто термин «Latin-1» (или «Latin1») используется как эквивалент ISO-8859-1. Однако некоторые люди считают «Latin1» относящимся только к символам в диапазоне от 128 до 255 или иногда от 160 до 255. В этой документации «Latin-1» и «Latin1» используются для обозначения всех 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 равно true, вы гарантированно получите реальный SV (в случае, если он не был реальным ранее), который можно затем изменить. Проверьте, что возвращаемое значение не null, перед обращением к нему как к SV*.

См. "Understanding the Magic of Tied Hashes and Arrays" в 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 выполнить данную строку в скалярном контексте и вернуть результат в виде SV*.

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

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

eval_sv

Инструктирует Perl выполнить строку в 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. Это означает, что преобразование одного символа в другой регистр может привести к последовательности более чем одного символа. Например, заглавная буква символа ß (маленькая латинская буква с острым) — это последовательность из двух символов 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; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает 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; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает 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; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает 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; в противном случае как Юникод. Обратите внимание, что буфер, на который указывает 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-символом в указанном классе на основе платформы, Юникода и правил 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, правила Юникода используются для определения, входит ли она в класс символов. Например, isWORDCHAR_uvchr(0x100) возвращает TRUE, так как 0x100 — это ЗАГЛАВНАЯ ЛАТИНСКАЯ БУКВА A С ДИАРЕЗИСОМ в Юникоде и является символом слова.

Вариант 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 из каждой точки вызова в программе вызовет предупреждение о прекращении поддержки, включенное по умолчанию. Вы можете преобразовать свою программу сейчас, чтобы использовать isFOO_utf8_safe, избежать предупреждений и получить дополнительную защиту или подождать до версии v5.30, когда вам придется добавить параметр e.

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

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

Вариант 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 из каждой точки вызова в программе вызовет предупреждение о прекращении поддержки, включенное по умолчанию. Вы можете преобразовать свою программу сейчас, чтобы использовать 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 системах возвращает TRUE, если этот символ соответствует символу 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" in 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 готов к запуску в точно той же точке, что и предыдущий. Псевдо-код вилки использует 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", если вам нужны оба хеша.

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

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. Хранилище — это хеш таблицы символов, содержащий переменные пакета, относящиеся к пакету, в котором была определена подпрограмма. Для получения дополнительной информации, см. perlguts.

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

HV*     CvSTASH(CV* cv)

find_runcv

Находит CV, соответствующий текущей выполняемой подпрограмме или eval. Если db_seqp не равно нулю, пропускаются 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, будет вычислено.

Если флаг flags содержит 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 — это побитовое ИЛИ-соединение любых флагов PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, или PERL_LOADMOD_IMPORT_OPS (или 0 для отсутствия флагов).

Если PERL_LOADMOD_NOIMPORT установлен, модуль загружается как будто с пустым списком импорта, как в use Foo::Bar (); это единственный случай, когда дополнительные аргументы можно опустить. В противном случае, если PERL_LOADMOD_IMPORT_OPS установлен, дополнительные аргументы должны состоять из ровно одного 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 не равен null, имя относится к типизированной лексической переменной, и это идентифицирует тип. Если ourstash не равен null, это лексическая ссылка на переменную пакета, и это идентифицирует пакет. Следующие флаги можно объединять операцией ИЛИ:

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

Завершает работу интерпретатора 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

Вводит блок обработки исключений. См. "Обработка исключений" в 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

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

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 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

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

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

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

PL_keyword_plugin

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

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

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

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

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

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

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

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

Функции GV

GV — это структура, соответствующая Perl typeglob, например *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, но не имеет параметра флагов.

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, которая не имеет параметра флагов.

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, так как не имеет параметра флагов. Если параметр 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 * и длина.

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

gv_init_pvn

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

gv — это скаляр, который нужно преобразовать.

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

name и len задают имя. Имя должно быть неквалифицированным; то есть оно не должно включать имя пакета. Если gv является элементом стека, ответственность за соответствие имени, переданного этой функции, имени элемента, лежит на вызывающей стороне. Если они не совпадают, внутренние учетные записи 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 * и длина. flags в настоящее время не используется.

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

gv_stashpv

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

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

gv_stashpvn

Возвращает указатель на стека для заданного пакета. Параметр 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

Возвращает указатель на стека для заданного пакета. Смотрите "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

Указатель на нулевой AV.

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

Nullch

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

Nullcv

Указатель на нулевой CV.

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

Nullhv

Указатель на нулевой HV.

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

Nullsv

Указатель на нулевой 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 Unicode. Значение 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 Unicode.

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 Unicode. Если lval установлено, то запрос будет частью сохранения. Это означает, что если в хэше нет значения, связанного с данным ключом, то оно создаётся, и возвращается указатель на него. На SV* к которому он указывает, можно назначить значение. Но всегда проверяйте, что возвращаемое значение не нулевое, прежде чем выполнять обращение к нему как к SV*.

См. "Понимание магии привязанных хэшей и массивов" в 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 установлено, запрос будет частью сохранения. Убедитесь, что возвращаемое значение не нулевое, прежде чем обращаться к нему. Возвращаемое значение, когда 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 полностью лежит на ответственности вызывающего кода. 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

Удаляет хеш. Эквивалент XS функции undef(%hash).

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

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

void    hv_undef(HV *hv)

newHV

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

HV*     newHV()

Управление хуками

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

wrap_op_checker

Добавляет C-функцию в цепочку функций проверки для указанного типа оператора. Это предпочтительный способ управления массивом "PL_check". opcode указывает, какой тип оператора должен быть затронут. new_checker — указатель на C-функцию, которая должна быть добавлена в цепочку проверки для данного кода операции, а new_checker указывает на место хранения указателя на следующую функцию в цепочке. Значение 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, если в силе pragma use utf8. Однако при выполнении string eval скаляр может иметь флаг SvUTF8, и в этом случае его байты должны интерпретироваться как UTF-8, если не в силе pragma 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, если не null, предоставляет строку (в виде SV) содержащую код, который нужно разобрать. Создается копия строки, поэтому последующее изменение line не повлияет на разбор. rsfp, если не null, предоставляет поток ввода, из которого будет читаться код для разбора. Если оба не null, код в 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

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

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

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

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

OP *    parse_stmtseq(U32 flags)

parse_termexpr

Разбор Perl-выражения типа терм. Оно может содержать операторы с приоритетом вплоть до операторов присваивания. Выражение должно быть после (и таким образом завершаться) либо запятой, либо оператором с более низким приоритетом, либо чем-то, что обычно завершает выражение, например, точкой с запятой. Если 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 параметры и возвращающей ту же информацию. Но она более потокобезопасна, чем обычная nl_langinfo(), скрывает особенности обработки локалей 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() было то, чтобы код, которому необходимо узнать текущий символ валюты, разделитель десятичных знаков чисел с плавающей точкой или разделитель групп цифр, мог использовать более простой и потокобезопасный API nl_langinfo вместо 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), но можно обойти последние два пункта, используя функции Windows API 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 в байтах, вызывая магические функции 'length', если они доступны, но не устанавливает флаг 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 локали (обычно генерируя английское сообщение), и из выбранной локали, когда находится в области действия use locale pragma. Предпринимается попытка декодировать сообщение из кодировки символов локали, но оно будет декодировано только как 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)

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

Copy

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

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

CopyD

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

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

Move

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

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

MoveD

Аналогично 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)

Poison

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

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

PoisonFree

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

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

PoisonNew

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

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

PoisonWith

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

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

Renew

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

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

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

Renewc

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

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

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

Safefree

Интерфейс 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)

StructCopy

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

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

Zero

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

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

ZeroD

Аналогично 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 20.

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

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

Поля разделены табуляцией. Первый столбец — глубина (нулевой — самый внутренний не пропущенный кадр). В hex:offset, hex — положение счётчика команд в S_parse_body, а :offset (может отсутствовать) — смещение внутри 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 равно true, функция может (но не обязана) изменить и вернуть 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.

Функция возвращает NULL, если вхождение little в big отсутствует. Если little — пустая строка, возвращается big.

Поскольку эта функция работает на уровне байтов и из-за свойств UTF-8 (или UTF-EBCDIC), она будет работать правильно, если и иголка, и стог сена — строки с одинаковым типом кодирования 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. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

dMULTICALL;

MULTICALL

Создаёт лёгкий обратный вызов. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

MULTICALL;

POP_MULTICALL

Закрывающая скобка для лёгкого обратного вызова. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

POP_MULTICALL;

PUSH_MULTICALL

Открывающая скобка для лёгкого обратного вызова. См. "LIGHTWEIGHT CALLBACKS" в 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

Сканирование и пропуск числового десятичного разделителя (радикса).

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)

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

Возвращает код Юникода первого символа в строке s, которая предполагается в кодировке UTF-8; retlen будет установлено в длину этого символа в байтах.

Некоторые, но не все, ошибки UTF-8 обнаруживаются, и, фактически, некоторые ошибки ввода могут привести к чтению за пределами буфера ввода, что является одной из причин устаревания этой функции. Другая причина в том, что только в крайне ограниченных случаях код Юникода по сравнению с кодом исходной кодировки должен вас интересовать. См. "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)

Дерево построения Optree

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, чтобы принудительно поместить тело цикла в свой собственный блок.

OP *    newWHILEOP(I32 flags, I32 debuggable,
                   LOOP *loop, OP *expr, OP *block,
                   OP *cont, I32 has_my)

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

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". Вы можете принудительно заставить Perl передать 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 имеет брата

bool    OpHAS_SIBLING(OP *o)

OpLASTSIB_set

Помечает o как не имеющую последующих братьев. В сборках PERL_OP_PARENT помечает 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

Устанавливает брата операции 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. Эта функция доступна только в сборках Perl с -DPERL_OP_PARENT.

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_sibling/op_sibparent или op_moresib соответственно.

Обратите внимание, что op_next не изменяется, и узлы не освобождаются; это ответственность вызывающей стороны. Также не будет создан новый список оп для пустого списка и т. д.; для этого используйте функции более высокого уровня, такие как op_append_elem().

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

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

Двигатель, реализующий функцию Perl pack().

void    packlist(SV *cat, const char *pat,
                 const char *patend, SV **beglist,
                 SV **endlist)

unpackstring

Двигатель, реализующий функцию Perl unpack().

Используя шаблон 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)

Структуры данных заполнителя

CvPADLIST

CV могут иметь CvPADLIST(cv) установленным на указатель на PADLIST. Это рабочая область CV, которая хранит лексические переменные и временные значения кода, а также значения для каждого потока.

Для этих целей «форматы» являются разновидностью CV; eval"" тоже (кроме того, что они не вызываемы по желанию и всегда удаляются после завершения выполнения eval""). Требуемые файлы — это просто eval без внешней лексической области.

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 — это ссылающаяся ссылка с REFCNT на лексическую переменную из «вне». Такие записи иногда называют «поддельными». В этом случае имя не использует «low» и «high» для хранения диапазона cop_seq, поскольку оно находится в области действия на всём протяжении. Вместо этого «high» хранит некоторые флаги, содержащие информацию о реальной лексической переменной (объявлена ли она в анонимной функции и может ли она быть создана несколько раз?), а для поддельных анонимных функций «low» содержит индекс в блоке родителя, где хранится значение лексической переменной, чтобы ускорить клонирование.

Если «имя» равно &, соответствующий элемент в блоке — это CV, представляющий возможный замыкание.

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

Флаг SVs_PADSTALE сбрасывается для лексических переменных каждый раз при выполнении my(), и устанавливается при выходе из области видимости. Это позволяет генерировать предупреждение "Variable $x is not available" в eval, например:

{ 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 списка блоков, содержащий блоки. Индексируйте его только числами ≥ 1, так как нулевой элемент не гарантируется останется пригодным к использованию.

PAD **  PadlistARRAY(PADLIST padlist)

PadlistMAX

Индекс последнего выделенного места в списке блоков. Обратите внимание, что последний блок может быть в более раннем слоте. Любые записи после него будут NULL в этом случае.

SSize_t PadlistMAX(PADLIST padlist)

PadlistNAMES

Имена, связанные с записями блока.

PADNAMELIST * PadlistNAMES(PADLIST padlist)

PadlistNAMESARRAY

Массив C имён блоков.

PADNAME ** PadlistNAMESARRAY(PADLIST padlist)

PadlistNAMESMAX

Индекс последнего имени блока.

SSize_t PadlistNAMESMAX(PADLIST padlist)

PadlistREFCNT

Счётчик ссылок списка блоков. В настоящее время он всегда равен 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

Создаёт новый список блоков, обновляя глобальные переменные, указывающие на текущий список блоков компиляции, на новый список блоков. Следующие флаги можно объединить с помощью операции OR:

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) для выполнения исправлений некоторых операций и небольших оптимизаций. Функция вызывается один раз для каждой компилируемой подпрограммы и получает в качестве единственного параметра указатель на оператор, являющийся точкой входа в подпрограмму. Она изменяет дерево операторов непосредственно.

Оптимизатор песочницы никогда не следует полностью заменять. Вместо этого добавьте код в него, обернув существующий оптимизатор. Основной способ сделать это показан в "Compile pass 3: peephole optimization" в perlguts. Если новый код хочет работать с операторами на всех уровнях структуры подпрограммы, а не только на верхнем, то, скорее всего, удобнее обернуть обработчик "PL_rpeepp".

peep_t  PL_peepp

PL_rpeepp

Указатель на рекурсивный оптимизатор песочницы. Это функция, которая вызывается в конце компиляции подпрограммы Perl (или эквивалентного независимого фрагмента кода Perl) для выполнения исправлений некоторых операций и небольших оптимизаций. Функция вызывается один раз для каждой цепочки операций, связанных через поля op_next; она рекурсивно вызывается для обработки каждой боковой цепочки. Ей передаётся в качестве единственного параметра указатель на оператор, который находится в начале цепочки. Она изменяет дерево операторов непосредственно.

Оптимизатор песочницы никогда не следует полностью заменять. Вместо этого добавьте код в него, обернув существующий оптимизатор. Основной способ сделать это показан в "Compile pass 3: peephole optimization" в perlguts. Если новый код хочет работать только с операторами на верхнем уровне подпрограммы, а не по всей структуре, то, скорее всего, удобнее обернуть обработчик "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 (или 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 в стек и сделать его смертельным. В стеке должно быть достаточно места для этого элемента. Не использует 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

Извлекает целое число типа unsigned 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

looks_like_number

Проверка, похож ли контент SV на число (или является числом). Inf и Infinity обрабатываются как числа (поэтому предупреждение о нечисловом значении не выдаётся), даже если ваш atof() их не распознаёт. Get-magic игнорируется.

I32     looks_like_number(SV *const 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)

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 байт. Если параметр s равен 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)

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.

SV*     newSVrv(SV *const rv,
                const char *const classname)

newSVsv

Создаёт новый SV, являющийся точной копией исходного SV. (Использует sv_setsv.)

SV*     newSVsv(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' magic игнорируется для 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_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_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_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 не освобождается, хотя её тип устанавливается в все 1, чтобы во время глобального уничтожения и т.д. она не была случайно принята за живую. Эта функция должна вызываться только когда 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

Добавляет магию преобразования сортировки в 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)

sv_dec

Автоматическое уменьшение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает магию 'get' и перегрузку операторов.

void    sv_dec(SV *const sv)

sv_dec_nomg

Автоматическое уменьшение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает перегрузку операторов. Пропускает обработку магии 'get'.

void    sv_dec_nomg(SV *const 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; если мы — скаляр с копированием при записи, это время записи, когда мы делаем копию, и также используется локально; если это vstring, удалите магию vstring. Если SV_COW_DROP_PV установлено, то скаляр с копированием при записи удаляет свой буфер PV (если есть) и становится SvPOK_off вместо того, чтобы создавать копию. (Используется, когда этот скаляр собирается быть установлен на какое-то другое значение.) Кроме того, параметр flags передаётся в sv_unref_flags() при снятии ссылки. sv_force_normal вызывает эту функцию со флагами, установленными в 0.

Ожидается, что эта функция будет использоваться для сигнализации Perl о том, что этот 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)

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)

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. Аналогично функции Perl substr(). Обрабатывает магию «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)

sv_isa

Возвращает логическое значение, указывающее, благословен ли SV в указанный класс. Это не проверяет подтипы; используйте sv_derived_from для проверки отношения наследования.

int     sv_isa(SV* sv, const char *const name)

sv_isobject

Возвращает логическое значение, указывающее, является ли SV RV, указывающим на благословленный объект. Если SV не является RV или объект не благословлен, то это вернёт false.

int     sv_isobject(SV* sv)

sv_len

Возвращает длину строки в SV. Обрабатывает магию и приведение типов и устанавливает флаг UTF8 соответствующим образом. См. также "SvCUR", который даёт прямой доступ к слоту xpv_cur.

STRLEN  sv_len(SV *const sv)

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 больше нуля, то savepvn копия 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)

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)

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)

sv_pvbyten_force

Бэкенд для макроса SvPVbytex_force . Всегда используйте макрос вместо этого.

char*   sv_pvbyten_force(SV *const sv, STRLEN *const lp)

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)

sv_pvutf8n_force

Бэкенд для макроса SvPVutf8x_force . Всегда используйте макрос вместо этого.

char*   sv_pvutf8n_force(SV *const sv, STRLEN *const lp)

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)

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_setsv или один из его многочисленных макросов-фронтов.

void    sv_replace(SV *const sv, SV *const nsv)

sv_reset

Базовая реализация функции Perl reset. Обратите внимание, что функция на уровне perl устарела.

void    sv_reset(const char* s, HV *const stash)

sv_rvunweaken

Освободить ссылку: Снять флаг SvWEAKREF у данного RV; удалить обратную ссылку на данный RV из массива обратных ссылок, связанных с целевым SV; увеличить счётчик ссылок цели. Безмолвно игнорирует undef и предупреждает о ссылках, не являющихся слабыми.

SV*     sv_rvunweaken(SV *const sv)

sv_rvweaken

Ослабить ссылку: установить флаг SvWEAKREF у данного RV; присвоить ссылаемому SV PERL_MAGIC_backref магию, если она ещё не задана; и добавить обратную ссылку на данный RV в массив обратных ссылок, связанных с этой магией. Если RV магический, вызов set magic будет сделан после того, как 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

Копирует двойное число в данный 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

Копирует двойное число в новый 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_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)

sv_tainted

Проверка SV на заражённость. Используйте SvTAINTED вместо этого.

bool    sv_tainted(SV *const sv)

sv_true

Возвращает true, если SV имеет истинное значение по правилам Perl. Используйте макрос SvTRUE, который может вызвать sv_true(), или использовать встроенную версию.

I32     sv_true(SV *const 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, чтобы принудительно уменьшить счётчик ссылок (иначе уменьшение происходит при условии, что счётчик ссылок отличается от одного или ссылка является readonly SV). См. "SvROK_off".

void    sv_unref_flags(SV *const ref, const U32 flags)

sv_untaint

Удалить заражённость у SV. Используйте SvTAINTED_off вместо этого.

void    sv_untaint(SV *const sv)

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 (т.е. realloc, перемещение) память, на которую указывает ptr, поэтому указатель не должен освобождаться или использоваться программистом после передачи его в sv_usepvn, и ни один указатель "ниже" этого указателя (например, ptr + 1) тоже не должен использоваться.

Если flags & SV_SMAGIC истинно, вызовет SvSETMAGIC. Если flags & SV_HAS_TRAILING_NUL истинно, то ptr[len] должно быть NUL, и realloc будет пропущено (т.е. буфер фактически на 1 байт длиннее, чем len, и уже соответствует требованиям для хранения в SvPVX).

void    sv_usepvn_flags(SV *const sv, char* ptr,
                        const STRLEN len,
                        const U32 flags)

sv_utf8_decode

Если PV SV является последовательностью октетов в расширенном UTF-8 Perl и содержит многобайтовый символ, флаг SvUTF8 устанавливается, чтобы он выглядел как символ. Если PV содержит только однобайтовые символы, флаг SvUTF8 остаётся выключенным. Проверяет PV на валидность и возвращает FALSE, если PV является недопустимым UTF-8.

bool    sv_utf8_decode(SV *const sv)

sv_utf8_downgrade

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

Это не общий интерфейс кодирования Юникод в байты: используйте модуль 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 к строковому типу, если он им не является. Устанавливает флаг SvUTF8 для избежания будущих проверок валидности, даже если вся строка одинакова в UTF-8 и без него. Возвращает количество байтов в преобразованной строке.

Это не общий интерфейс кодирования байтов в Юникод: используйте модуль 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 теперь игнорируется.

Возвращает количество байтов в преобразованной строке.

Это не общий интерфейс кодирования байтов в Юникод: используйте модуль 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)

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, вызывает магию get.

Предполагает, что 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)

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)

Флаги 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

Флаг типа для typeglob. См. "svtype".

SVt_PVHV

Флаг типа для хэшей. См. "svtype".

SVt_PVIO

Флаг типа для объектов ввода/вывода. См. "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 представляет собой typeglob. Если !SvFAKE(sv), то это настоящий, непереводимый typeglob. Если SvFAKE(sv), то это скаляр, которому был назначен typeglob. Повторное назначение ему сделает его не typeglob. SVt_PVLV представляет собой скаляр, делегирующий другому скаляру за кулисами. Используется, например, для возвращаемого значения substr и для привязанных элементов хэшей и массивов. Он может содержать любое скалярное значение, включая typeglob. SVt_REGEXP - для регулярных выражений. SVt_INVLIST - только для внутреннего использования ядра Perl.

SVt_PVMG представляет собой "обычный" скаляр (не typeglob, регулярное выражение или делегат). Поскольку большинству скаляров не нужны все внутренние поля PVMG, мы экономим память, выделяя более компактные структуры, когда это возможно. Все остальные типы - это просто более простые формы SVt_PVMG, с меньшим количеством внутренних полей. SVt_NULL может содержать только undef. SVt_IV может содержать undef, целое число или ссылку. (SVt_RV - псевдоним для SVt_IV, который существует для обратной совместимости.) SVt_NV может содержать любое из них или число с плавающей точкой. SVt_PV может содержать только undef или строку. SVt_PVIV является супермножеством SVt_PV и SVt_IV. SVt_PVNV аналогичен. SVt_PVMG может содержать всё, что может содержать SVt_PVNV, но он может, но не обязан, быть благословенным или магическим.

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

boolSV

Возвращает SV, равный true, если b имеет истинное значение, или 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)

newRV_inc

Создаёт обёртку RV для SV. Счётчик ссылок исходного SV увеличивается.

SV*     newRV_inc(SV* sv)

newSVpadname

Создаёт новый SV, содержащий имя блока.

SV*     newSVpadname(PADNAME *pn)

newSVpvn_utf8

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символов). Если utf8 истинно, вызывает SvUTF8_on для нового SV. Реализовано как обёртка вокруг newSVpvn_flags.

SV*     newSVpvn_utf8(const char* s, STRLEN len,
                      U32 utf8)

sv_catpvn_nomg

Подобно sv_catpvn но не обрабатывает магию.

void    sv_catpvn_nomg(SV* sv, const char* ptr,
                       STRLEN len)

sv_catpv_nomg

Подобно sv_catpv но не обрабатывает магию.

void    sv_catpv_nomg(SV* sv, const char* ptr)

sv_catsv_nomg

Подобно sv_catsv но не обрабатывает магию.

void    sv_catsv_nomg(SV* dsv, SV* ssv)

SvCUR

Возвращает длину строки, которая находится в SV. См. "SvLEN".

STRLEN  SvCUR(SV* sv)

SvCUR_set

Устанавливает текущую длину строки, которая находится в SV. См. "SvCUR" и SvIV_set>.

void    SvCUR_set(SV* sv, STRLEN len)

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() как обычный Perl-метод.

В настоящее время единственное существенное значение для 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 может быть Perl-объектом или именем Perl-класса.

bool    sv_does_sv(SV* sv, SV* namesv, U32 flags)

SvEND

Возвращает указатель на позицию сразу после последнего символа в строке, которая находится в SV, где обычно находится заключительный NUL символ (хотя Perl-скаляры строго его не требуют). См. "SvCUR". Обратитесь к символу как *(SvEND(sv)).

Предупреждение: Если SvCUR равно SvLEN, то SvEND указывает на невыделенную память.

char*   SvEND(SV* sv)

SvGAMAGIC

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

U32     SvGAMAGIC(SV* sv)

SvGROW

Расширяет буфер символов в SV, чтобы в нём было место для указанного количества байтов (не забудьте зарезервировать место для дополнительного заключительного NUL символа). Вызывает sv_grow для выполнения расширения при необходимости. Возвращает указатель на буфер символов. SV должен быть типа >= SVt_PV. Альтернативой является вызов sv_grow, если вы не уверены в типе SV.

Возможно, вы ошибочно подумаете, что len — это количество байтов, которые нужно добавить к существующему размеру, но на самом деле это общий размер, который sv должен иметь.

char *  SvGROW(SV* sv, STRLEN len)

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)

SvIsCOW

Возвращает значение U32, указывающее, является ли SV Copy-On-Write (либо общие скаляры ключей хеша, либо полные скаляры Copy On Write, если 5.9.0 настроен для COW).

U32     SvIsCOW(SV* sv)

SvIsCOW_shared_hash

Возвращает логическое значение, указывающее, является ли SV общим скаляром ключа хеша Copy-On-Write.

bool    SvIsCOW_shared_hash(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. Можно выполнить ту же функцию с помощью присваивания lvalue к SvIVX. Однако в будущих версиях Perl это будет более эффективно, если использовать SvIV_set вместо присваивания lvalue к SvIVX.

void    SvIV_set(SV* sv, IV val)

SvIVX

Возвращает исходное значение в слоте IV SV без проверок или преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvIV".

IV      SvIVX(SV* sv)

SvIVx

Преобразует данный SV в IV и возвращает его. В большинстве случаев возвращаемое значение будет храниться в слоте IV sv, но не во всех. (Используйте "sv_setiv" чтобы убедиться, что это так).

Эта форма гарантирует, что sv будет вычислено только один раз. Используйте только если sv — это выражение с побочными эффектами, в противном случае используйте более эффективную форму SvIV.

IV      SvIVx(SV* sv)

SvLEN

Возвращает размер буфера строки в SV, не включая часть, приписываемую SvOOK. См. "SvCUR".

STRLEN  SvLEN(SV* sv)

SvLEN_set

Устанавливает размер буфера строки для SV. См. "SvLEN".

void    SvLEN_set(SV* sv, STRLEN len)

SvMAGIC_set

Устанавливает значение указателя MAGIC в sv на val. См. "SvIV_set".

void    SvMAGIC_set(SV* sv, MAGIC* val)

SvNIOK

Возвращает значение U32, указывающее, содержит ли SV число, целое число или двойное число.

U32     SvNIOK(SV* sv)

SvNIOK_off

Сбрасывает состояние NV/IV SV.

void    SvNIOK_off(SV* sv)

SvNIOKp

Возвращает значение U32, указывающее, содержит ли SV число, целое число или двойное число. Проверяет частное значение. Используйте 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 двойное число. Проверяет частное значение. Используйте 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

Преобразует заданный SV в NV и возвращает его. Возвращаемое значение во многих случаях будет сохранено в слоте NV sv, но не во всех случаях. (Используйте "sv_setnv", чтобы убедиться в этом).

Этот вариант гарантирует, что sv будет вычислен только один раз. Используйте его только если sv — выражение со побочными эффектами, в противном случае используйте более эффективный SvNV.

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 строку символов. Проверяет приватный флаг. Используйте SvPOK вместо этого.

U32     SvPOKp(SV* sv)

SvPV

Возвращает указатель на строку в SV или строковое представление SV, если SV не содержит строку. SV может кэшировать строковое представление, становясь SvPOK. Обрабатывает магию «получения». Переменная len будет установлена в длину строки (это макрос, поэтому не используйте &len). См. также "SvPVx" для версии, которая гарантирует, что sv будет вычислена только один раз.

Обратите внимание, что нет гарантии, что возвращаемое значение SvPV() равно SvPVX(sv), или что SvPVX(sv) содержит корректные данные, или что последовательные вызовы SvPV(sv) будут возвращать тот же указатель каждый раз. Это связано с тем, как обрабатываются такие вещи, как перегрузка и копирование при изменении. В этих случаях возвращаемое значение может указывать на временный буфер или подобное. Если вам абсолютно необходимо, чтобы поле 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)

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 напрямую. Обрабатывает магию «получения».

Обратите внимание, что принудительное преобразование произвольного скаляра в обычный PV может привести к удалению полезных данных. Например, если SV был SvROK, то ссылка будет иметь декрементированный счётчик ссылок, а сам SV может быть преобразован в скаляр типа SvPOK со строковым буфером, содержащим значение, например, "ARRAY(0x1234)".

char*   SvPV_force(SV* sv, STRLEN len)

SvPV_force_nomg

Аналогично SvPV_force, но не обрабатывает магию «получения».

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)

SvPV_set

Вероятно, это не то, что вам нужно. Возможно, вы хотели "sv_usepvn_flags" или "sv_setpvn" или "sv_setpvs".

Устанавливает значение указателя PV в sv на завершающую нулём строку NUL, выделенную Perl'ем val. См. также "SvIV_set".

Не забудьте освободить предыдущий буфер PV. Есть много пунктов для проверки. Будьте осторожны, существующий указатель может быть вовлечён в копирование при изменении или других операциях, поэтому выполните SvOOK_off(sv), и используйте sv_force_normal или SvPV_force (или проверьте флаг SvIsCOW) в первую очередь, чтобы убедиться в безопасности этого изменения. Затем, если это не копирование при изменении, вызовите SvPV_free для освобождения предыдущего буфера PV.

void    SvPV_set(SV* sv, char* val)

SvPVutf8

Аналогично SvPV, но сначала преобразует sv в UTF-8, если необходимо.

char*   SvPVutf8(SV* sv, STRLEN len)

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)

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_report_used

Вывести содержимое всех SV, которые ещё не освобождены (помощник для отладки).

void    sv_report_used()

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_setsv_nomg

Как sv_setsv, но не обрабатывает магию.

void    sv_setsv_nomg(SV* dsv, SV* ssv)

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 заражённым. Возвращает TRUE, если да, FALSE — если нет.

bool    SvTAINTED(SV* sv)

SvTAINTED_off

Снимает пометку заражённости с SV. Будьте очень осторожны с этой процедурой, так как она обнуляет некоторые фундаментальные средства безопасности Perl. Авторы модулей XS не должны использовать эту функцию, если не полностью понимают все последствия безусловного снятия метки заражённости. Снятие метки заражённости должно выполняться стандартным способом Perl, через тщательно составленный regexp, а не непосредственным снятием метки заражённости с переменных.

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)

SvTRUE_nomg

Возвращает булево значение, указывающее, расценит ли Perl SV как истинное или ложное. См. "SvOK" для проверки определённого/неопределённого значения. Не обрабатывает магию «get».

bool    SvTRUE_nomg(SV* sv)

SvTYPE

Возвращает тип SV. См. "svtype".

svtype  SvTYPE(SV* sv)

SvUOK

Возвращает булево значение, указывающее, содержит ли SV целое число, которое должно быть интерпретировано как беззнаковое. Положительное целое число, значение которого находится в диапазоне как IV, так и UV, может быть помечено как SvUOK или SVIOK.

bool    SvUOK(SV* sv)

SvUPGRADE

Используется для повышения SV до более сложной формы. Использует sv_upgrade для повышения, если необходимо. См. "svtype".

void    SvUPGRADE(SV* sv, svtype type)

SvUTF8

Возвращает значение U32, указывающее на статус UTF-8 SV. Если всё настроено правильно, это указывает, содержит ли SV данные, закодированные в UTF-8. Используйте это после вызова SvPV() или одной из его разновидностей, на случай, если какой-либо вызов перегрузки строк обновит внутренний флаг.

Если вы хотите учесть псевдоним bytes, используйте "DO_UTF8" вместо этого.

U32     SvUTF8(SV* sv)

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)

SvVOK

Возвращает булево значение, указывающее, содержит ли SV v-строку.

bool    SvVOK(SV* sv)

Поддержка Unicode

"Поддержка Unicode" в perlguts содержит введение в этот API.

См. также "Классификация символов" и "Изменение регистра символов". Различные функции вне этой секции также работают со Unicode. Поищите строку "utf8" в этом документе.

BOM_UTF8

Это макрос, который вычисляет строковую константу байтов UTF-8, определяющих метку порядка байтов Unicode (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 true, то строка s1 предполагается закодированной в UTF-8; в противном случае она предполагается в родной кодировке 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.

Для обеспечения регистронезависимости используется «сгибание регистра» Unicode вместо преобразования символов в верхний/нижний регистр, см. http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).

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

Возвращает TRUE, если первые len байтов строки s образуют корректную строку, закодированную в UTF-8, которая соответствует Поправке Unicode #9; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот параметр, у s не может быть вложенных NUL символов и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «корректную строку UTF-8».

Эта функция возвращает FALSE для строк, содержащих какие-либо символы с кодами выше максимального значения Unicode 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_strict_utf8_string", "is_strict_utf8_string_loc", "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, представляющей некоторый код Unicode, не являющийся суррогатным; в противном случае возвращает 0. Если ненулевое, значение указывает, сколько байтов, начиная с s, составляют представление кода. Любые оставшиеся байты перед e, но за пределами необходимых для формирования первого кода символа в s, не рассматриваются.

Наибольшее допустимое значение кода — максимальное значение Unicode 0x10FFFF. Это отличается от "isSTRICT_UTF8_CHAR" только тем, что оно принимает коды символов, не являющиеся символами. Это соответствует Поправке Unicode #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, представляющим некоторое кодовое значение Unicode, полностью приемлемое для открытого обмена между всеми приложениями; в противном случае возвращает 0. Если ненулевое, значение показывает, сколько байтов, начиная с s , составляют представление кодового значения. Любые оставшиеся байты перед e, но за пределами необходимых для формирования первого кодового значения в s, не проверяются.

Наибольшее допустимое кодовое значение — максимальное значение Unicode 0x10FFFF, и оно не должно быть замещающим или недопустимым кодовым значением. Таким образом, это исключает любые кодовые значения из расширенного UTF-8 Perl.

Это используется для эффективного определения, являются ли следующие несколько байтов в s законным Unicode-приемлемым UTF-8 для одного символа.

Используйте "isC9_STRICT_UTF8_CHAR" для использования определения допустимых кодовых значений из Поправки к Unicode #9; "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_strict_utf8_string", "is_strict_utf8_string_loc", и "is_strict_utf8_string_loclen" для проверки целых строк.

STRLEN  isSTRICT_UTF8_CHAR(const U8 *s, const U8 *e)

is_strict_utf8_string

Возвращает TRUE, если первые len байты строки s образуют правильную строку UTF-8, полностью взаимозаменяемую любым приложением, использующим правила Unicode; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот вариант, то s не может содержать встроенных NUL символов и должна иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «валидную строку UTF-8».

Эта функция возвращает FALSE для строк, содержащих любые кодовые значения, превышающие максимальное значение Unicode 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", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе 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" , но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе 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 как допустимый. Это означает, что кодовые точки, превышающие Unicode, замещающие и недопустимые кодовые точки, считаются допустимыми этой функцией. Используйте "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" , но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе 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" , но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе 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" , но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе 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" , но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе 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, не проверяются.

Кодовая точка может быть любой, которая поместится в UV на этом компьютере, используя расширение Perl для официального UTF-8 для представления тех, которые выше максимального значения Unicode 0x10FFFF. Это означает, что этот макрос используется для эффективного определения, являются ли следующие несколько байтов в s законным UTF-8 для одного символа.

Используйте "isSTRICT_UTF8_CHAR", чтобы ограничить допустимые кодовые точки теми, которые определены Unicode как полностью взаимозаменяемые в приложениях; "isC9_STRICT_UTF8_CHAR", чтобы использовать определение допустимых кодовых точек согласно Исправлению #9 Unicode; и "isUTF8_CHAR_flags", для более настраиваемого определения.

Используйте "is_utf8_string", "is_utf8_string_loc", и "is_utf8_string_loclen", чтобы проверить целые строки.

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

Обратите также внимание, что символ UTF-8 INVARIANT (то есть 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 для использования определения строгости, заданного поправкой Unicode №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_OVERFLOW

Последовательность ввода была неверной, так как она относится к кодовой точке, которая не может быть представлена в доступном количестве битов в IV на текущей платформе.

UTF8_GOT_SHORT

Последовательность ввода была неверной, так как curlen меньше, чем требуется для полной последовательности. Другими словами, входные данные относятся к частичной последовательности символов.

UTF8_GOT_SUPER

Последовательность ввода была неверной, так как она относится к кодовой точке, не являющейся кодовой точкой Unicode; то есть, к точке, превышающей допустимый максимум Unicode. Этот бит устанавливается только если входной flags параметр содержит либо флаги UTF8_DISALLOW_SUPER, либо UTF8_WARN_SUPER.

UTF8_GOT_SURROGATE

Последовательность ввода была неверной, так как она относится к кодовой точке-заместителю UTF-16 Unicode. Этот бит устанавливается только если входной 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.

Важно отметить, что если этот параметр задан не равным нулю, любые предупреждения, которые эта функция в противном случае генерировала бы, будут подавлены и вместо этого помещены в *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 s смещённый на не более чем 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_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 выбирает все три вышеупомянутых флага WARN; и UNICODE_DISALLOW_ILLEGAL_INTERCHANGE выбирает все три флага DISALLOW. UNICODE_DISALLOW_ILLEGAL_INTERCHANGE ограничивает разрешённые входные данные строгим UTF-8, традиционно определённому Unicode. Аналогично, UNICODE_WARN_ILLEGAL_C9_INTERCHANGE и UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE являются сокращениями для выбора вышеупомянутых флагов Unicode и суррогатных, но не для несимвольных, как определено в Поправке Unicode #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. См. "The VERSIONCHECK: Keyword" в perlxs.

XS_VERSION_BOOTCHECK;

Предупреждения и завершение

ckWARN

Возвращает булево значение, указывающее, включены ли предупреждения для категории предупреждений w. Если категория по умолчанию включена, даже если она не находится в области действия use warnings, используйте макрос "ckWARN_d".

bool    ckWARN(U32 w)

ckWARN2

Подобно "ckWARN", но принимает две категории предупреждений в качестве входных данных и возвращает TRUE, если включена любая из них. Если любая категория по умолчанию включена, даже если она не находится в области действия use warnings, используйте макрос "ckWARN2_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN2(U32 w1, U32 w2)

ckWARN3

Подобно "ckWARN2", но принимает три категории предупреждений в качестве входных данных и возвращает TRUE, если включена любая из них. Если любая из категорий по умолчанию включена, даже если она не находится в области действия use warnings, используйте макрос "ckWARN3_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN3(U32 w1, U32 w2, U32 w3)

ckWARN4

Подобно "ckWARN3", но принимает четыре категории предупреждений в качестве входных данных и возвращает TRUE, если включена любая из них. Если любая из категорий по умолчанию включена, даже если она не находится в области действия 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.

Сообщение или объект об ошибке по умолчанию будут выводиться в стандартный поток ошибок, но это может быть изменено обработчиком $SIG{__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_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
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
save_sptr
save_svref

END_OF_DOCUMENT_MARKER

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.28.3/perlapi

perlapi

СОДЕРЖАНИЕ

НАЗВАНИЕ

ОПИСАНИЕ

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

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

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

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

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

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

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

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

Пользовательские операторы

Функции для обработки CV

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

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

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

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

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

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

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

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

Значения "Gimme"

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

Функции GV

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

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

Управление хуками

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

Функции и макросы, связанные с локалью

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

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

Функции прочего назначения

Функции MRO

Функции Multicall

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

Функции устаревшей обратной совместимости

Дерево построения Optree

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

Упаковщики и распаковщики

Структуры данных заполнителя

Переменные интерпретатора

Функции REGEXP

Макросы для работы со стеком

Выделение памяти для тела SV

Флаги SV

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

Поддержка Unicode

Переменные, созданные xsubpp и xsubpp внутренними функциями

Предупреждения и завершение

Функции без документации

Авторы

См. также

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

Переменные, созданные `xsubpp` и `xsubpp` внутренними функциями