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

ОПИСАНИЕ

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

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

Поскольку невозможно надёжно отличить UTF-8 от кодировок nтивного 8-битного представления, вам требуется либо метка порядка байтов в начале вашего исходного кода, либо 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 5.8.0) Преобразует внутреннее представление строки из последовательности октетов в кодировке по умолчанию (Latin-1 или EBCDIC) в UTF-8. Логическая последовательность символов остается неизменной. Если строка уже преобразована, то это ничто. Возвращает количество октетов, необходимых для представления строки как 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 5.8.0) Преобразует внутреннее представление строки из UTF-8 в эквивалентную последовательность октетов в кодировке по умолчанию (Latin-1 или EBCDIC). Логическая последовательность символов остается неизменной. Если строка уже хранится как nативные 8 бит, то это ничто. Может использоваться для гарантированного выключения флага UTF-8, например, когда вы хотите убедиться, что функция substr() или length() работает с обычно более быстрым алгоритмом байтов.

  Возвращает 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 5.8.0) Преобразует последовательность символов в соответствующую последовательность октетов в расширенном UTF-8 Perl. То есть каждый (возможно, широкий) символ заменяется последовательностью одного или нескольких символов, которые представляют отдельные байты UTF-8 символа. Флаг UTF-8 выключен. Ничего не возвращает.

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

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

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

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

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

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

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

  (С версии Perl 5.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, и функции C API 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