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 без 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