utf8

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПСИС
• ОПИСАНИЕ
  • Вспомогательные функции
• ОШИБКИ
• СМОТРИ ТАКЖЕ

ИМЯ

utf8 - Perl-pragma для включения/выключения 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 используется для обозначения обоих).

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

Поскольку невозможно надёжно отличить UTF-8 от кодировок 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 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.

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