utf8

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• СИНОПСИС
• ОПИСАНИЕ
  • Функции утилит
• ОШИБКИ
• СМОТРИТЕ ТАКЖЕ

НАЗВАНИЕ

utf8 - Предикат 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);

ОПИСАНИЕ

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

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

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

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

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

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

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

Обратите внимание, что если у вас есть не-ASCII, не-UTF-8 байты в вашем скрипте (например, вложенный Latin-1 в ваших строковых литералах), use utf8 будет недоволен. Если вы хотите иметь такие байты под use utf8, вы можете отключить этот предикат до конца блока (или файла, если на верхнем уровне) с помощью 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 v5.38, если $string является undef, никаких действий не происходит; до этого она будет преобразована в определённое и нулевой длины.

  Если вашему коду требуется совместимость с версиями 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 равно true, возвращается 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) Попытка преобразовать in-place последовательность октетов, закодированных в расширенном 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