utf8

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• СИНОПСИС
• ОПИСАНИЕ
  • Функции служебного назначения
• ОШИБКИ
• СМОТРИТЕ ТАКЖЕ

НАЗВАНИЕ

utf8 — pragma Perl для включения/выключения UTF-8 (или UTF-EBCDIC) в исходном коде

СИНОПСИС

use utf8;
no utf8;

# Convert the internal representation of a Perl scalar to/from UTF-8.

$num_octets = utf8::upgrade($string);
$success    = utf8::downgrade($string[, $fail_ok]);

# Change each character of a Perl scalar to/from a series of
# characters that represent the UTF-8 bytes of each original character.

utf8::encode($string);  # "\x{100}"  becomes "\xc4\x80"
utf8::decode($string);  # "\xc4\x80" becomes "\x{100}"

# Convert a code point from the platform native character set to
# Unicode, and vice-versa.
$unicode = utf8::native_to_unicode(ord('A')); # returns 65 on both
                                              # ASCII and EBCDIC
                                              # platforms
$native = utf8::unicode_to_native(65);        # returns 65 on ASCII
                                              # platforms; 193 on
                                              # EBCDIC

$flag = utf8::is_utf8($string); # since Perl 5.8.1
$flag = utf8::valid($string);

ОПИСАНИЕ

Pragma use utf8 сообщает анализатору Perl о возможности использования UTF-8 в тексте программы в текущей лексической области. Pragma no utf8 сообщает Perl о возвращении к интерпретации исходного текста как последовательности байтов в текущей лексической области. (На платформах EBCDIC технически используется UTF-EBCDIC, а не UTF-8, но это различие теоретическое, поэтому в данном документе термин UTF-8 используется для обоих случаев).

Не используйте этот pragma для целей, отличных от указания Perl, что ваш скрипт написан в формате UTF-8. Функции служебного назначения, описанные ниже, могут использоваться непосредственно без use utf8;.

Поскольку невозможно надёжно отличить UTF-8 от кодировок с 8-битовыми байтами, вам необходима либо метка порядка байтов в начале исходного кода, либо use utf8;, для инструкции perl.

Когда UTF-8 станет стандартным форматом исходного кода, этот pragma фактически станет бесполезным.

См. также последствия переключателя -C и его аналога, переменной окружения PERL_UNICODE, в perlrun.

Включение pragmy utf8 имеет следующие последствия:

• Байты в исходном тексте, не входящие в набор символов ASCII, будут обрабатываться как часть последовательности символов UTF-8. Это относится к большинству литералов, таким как имена идентификаторов, строковые константы и постоянные образцы регулярных выражений.

Обратите внимание, что если в вашем скрипте есть не-ASCII, не-UTF-8 байты (например, вставленный Latin-1 в строковые литералы), use utf8 будет недоволен. Если вы хотите иметь такие байты в use utf8, вы можете отключить этот pragma до конца блока (или файла, если на верхнем уровне) с помощью no utf8;.

Функции служебного назначения

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

• $num_octets = utf8::upgrade($string)

  (С Perl v5.8.0) Преобразует внутреннее представление строки из последовательности байтов в кодировке по умолчанию (Latin-1 или EBCDIC) в UTF-8. Логическая последовательность символов не меняется. Если $string уже обновлён, то это бесполезно. Возвращает количество байтов, необходимых для представления строки в формате UTF-8.

  Если ваш код должен быть совместим с версиями perl без use feature 'unicode_strings';, вы можете принудительно задать семантику Unicode для данной строки:

  # force unicode semantics for $string without the
  # "unicode_strings" feature
  utf8::upgrade($string);

  Например:

  # without explicit or implicit use feature 'unicode_strings'
  my $x = "\xDF";    # LATIN SMALL LETTER SHARP S
  $x =~ /ss/i;       # won't match
  my $y = uc($x);    # won't convert
  utf8::upgrade($x);
  $x =~ /ss/i;       # matches
  my $z = uc($x);    # converts to "SS"

  Обратите внимание, что эта функция не обрабатывает произвольные кодировки; используйте Encode вместо этого.

• $success = utf8::downgrade($string[, $fail_ok])

  (С Perl v5.8.0) Преобразует внутреннее представление строки из UTF-8 в эквивалентную последовательность байтов в кодировке по умолчанию (Latin-1 или EBCDIC). Логическая последовательность символов не меняется. Если $string уже хранится как 8-битная последовательность байтов, то это бесполезно. Может использоваться для того, чтобы убедиться, что флаг UTF-8 выключен, например, когда вы хотите убедиться, что функция substr() или length() работает с обычно более быстрым алгоритмом байтов.

  Возникает ошибка, если исходная последовательность UTF-8 не может быть представлена в кодировке 8 бит по умолчанию. При ошибке происходит выход из программы или, если значение $fail_ok истинно, возвращается значение false.

  Возвращает true при успехе.

  Если ваш код ожидает последовательность байтов, это можно использовать для проверки того, что вы получили именно её:

  # throw an exception if not representable as octets
  utf8::downgrade($string)
  
  # or do your own error handling
  utf8::downgrade($string, 1) or die "string must be octets";

  Обратите внимание, что эта функция не обрабатывает произвольные кодировки; используйте Encode вместо этого.

• utf8::encode($string)

  (С Perl v5.8.0) Преобразует последовательность символов в соответствующую последовательность байтов в расширенном UTF-8 Perl. То есть, каждый (возможно, широкий) символ заменяется последовательностью одного или нескольких символов, которые представляют отдельные байты UTF-8 символа. Флаг UTF8 выключается. Ничего не возвращает.

  my $x = "\x{100}"; # $x contains one character, with ord 0x100
  utf8::encode($x);  # $x contains two characters, with ords (on
                     # ASCII platforms) 0xc4 and 0x80.  On EBCDIC
                     # 1047, this would instead be 0x8C and 0x41.

  Аналогично:

  use Encode;
  $x = Encode::encode("utf8", $x);

  Обратите внимание, что эта функция не обрабатывает произвольные кодировки; используйте Encode вместо этого.

• $success = utf8::decode($string)

  (С Perl v5.8.0) Попытка преобразовать последовательность байтов, закодированных в расширенном UTF-8 Perl, в соответствующую последовательность символов. То есть, каждая последовательность символов в строке, чьи орды представляют собой действительную последовательность байтов UTF-8, заменяется соответствующим одиночным символом. Флаг UTF-8 включается только в том случае, если исходная строка содержит символы UTF-8 с несколькими байтами. Если $string не является допустимой последовательностью расширенного UTF-8, возвращается false; в противном случае возвращается true.

  my $x = "\xc4\x80"; # $x contains two characters, with ords
                      # 0xc4 and 0x80
  utf8::decode($x);   # On ASCII platforms, $x contains one char,
                      # with ord 0x100.   Since these bytes aren't
                      # legal UTF-EBCDIC, on EBCDIC platforms, $x is
                      # unchanged and the function returns FALSE.
  my $y = "\xc3\x83\xc2\xab"; This has been encoded twice; this
                      # example is only for ASCII platforms
  utf8::decode($y);   # Converts $y to \xc3\xab, returns TRUE;
  utf8::decode($y);   # Further converts to \xeb, returns TRUE;
  utf8::decode($y);   # Returns FALSE, leaves $y unchanged

  Обратите внимание, что эта функция не обрабатывает произвольные кодировки; используйте Encode вместо этого.

• $unicode = utf8::native_to_unicode($code_point)

  (С Perl v5.8.0) Принимает целое число без знака (представляющее порядковый номер символа (или кодового пункта) на платформе, на которой выполняется программа), и возвращает его эквивалентное значение Unicode. Так как платформы ASCII по умолчанию используют кодовые точки Unicode, эта функция возвращает свой вход на них. На платформах EBCDIC она выполняет преобразование из EBCDIC в Unicode.

  В настоящее время будет возвращено бессмысленное значение, если вход не является целым числом без знака.

  С Perl v5.22.0 вызовы этой функции оптимизированы на платформах ASCII, так что её использование не влияет на производительность.

• $native = utf8::unicode_to_native($code_point)

  (С Perl v5.8.0) Это обратное преобразование utf8::native_to_unicode(), выполняется в обратном направлении. Снова, на платформах ASCII это возвращает свой вход, но на платформах EBCDIC она найдёт кодовую точку платформы по умолчанию, если задана любая кодовая точка Unicode.

  В настоящее время будет возвращено бессмысленное значение, если вход не является целым числом без знака.

  С Perl v5.22.0 вызовы этой функции оптимизированы на платформах ASCII, так что её использование не влияет на производительность.

• $flag = utf8::is_utf8($string)

  (С Perl 5.8.1) Проверка, помечена ли строка $string как закодированная в UTF-8. Функционально то же самое, что и Encode::is_utf8($string).

  Как правило, необходимо только для отладки и тестирования. Если вам нужно вывести внутреннее содержимое SV, Dump() из Devel::Peek предоставляет более подробную информацию в компактной форме.

  Если вы всё ещё думаете, что вам это нужно вне отладки, тестирования или работы с именами файлов, вам, вероятно, следует прочитать perlunitut и "Что такое "флаг UTF8"?" в perlunifaq.

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

  Для принудительного использования семантики Unicode в коде, переносимом на perl 5.8 и 5.10, вызывайте utf8::upgrade($string) безусловно.

• $flag = utf8::valid($string)

  [ВНУТРЕННЕЕ] Проверка, находится ли $string в согласованном состоянии по отношению к UTF-8. Вернёт true, если она хорошо сформирована в расширенном UTF-8 Perl и имеет флаг UTF-8 включён или если $string хранится как последовательность байтов (оба этих состояния являются «согласованными»). Основной причиной этой функции является возможность для набора тестов Perl проверять, что операции оставили строки в согласованном состоянии.

utf8::encode подобен utf8::upgrade, но флаг UTF8 очищается. См. perlunicode и функции API C sv_utf8_upgrade, "sv_utf8_downgrade" in perlapi, "sv_utf8_encode" in perlapi, и "sv_utf8_decode" in perlapi, которые обернуты функциями Perl utf8::upgrade, utf8::downgrade, utf8::encode и utf8::decode. Также функции utf8::is_utf8, utf8::valid, utf8::encode, utf8::decode, utf8::upgrade и utf8::downgrade на самом деле являются внутренними и поэтому всегда доступны без инструкции require utf8.

ОШИБКИ

Некоторые файловые системы могут не поддерживать имена файлов UTF-8 или поддерживать их несовместимо с Perl. Поэтому имена UTF-8, видимые файловой системе, такие как имена модулей, могут не работать.

СМОТРИТЕ ТАКЖЕ

perlunitut, perluniintro, perlrun, bytes, perlunicode