内容

名称
概要
说明
- 实用程序函数
缺陷
另请参阅

#名称

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

#说明

use utf8 pragma 告诉 Perl 解析器允许在当前词法作用域的程序文本中使用 UTF-8。no utf8 pragma 告诉 Perl 在当前词法作用域中切换回将源文本视为文本字节。（在 EBCDIC 平台上，从技术上讲，它允许使用 UTF-EBCDIC，而不是 UTF-8，但这种区别是学术性的，因此在本文档中，术语 UTF-8 用于表示两者）。

不要将此 pragma 用于除告诉 Perl 脚本以 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; 禁用此编译指示，直到块（或文件，如果在顶级）结束。

#实用程序函数

Perl 核心在 utf8:: 包中定义了以下函数。您无需说 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，则不采取任何操作；在此之前，它将被转换为已定义且长度为零。

如果您的代码需要与没有 use feature 'unicode_strings'; 的 perl 版本兼容，则可以在给定的字符串上强制使用 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 起）就地将字符序列转换为 Perl 的扩展 UTF-8 中的相应八位字节序列。也就是说，每个（可能很宽）字符都会替换为一个或多个字符序列，这些字符序列表示字符的各个 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 起）尝试就地将 Perl 的扩展 UTF-8 中编码的八位字节序列转换为相应的字符序列。也就是说，它将字符串中每个字符序列（其序数表示有效的（扩展）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 的内部，Devel::Peek's Dump() 以紧凑的形式提供了更多详细信息。

如果你仍然认为在调试、测试或处理文件名之外需要此项，你可能应该阅读 perlunitut 和 "What is "the UTF8 flag"?" in perlunifaq。

不要将此标志用作区分字符和二进制数据的标记：应在编写代码时为每个变量决定此项。

要在可移植到 perl 5.8 和 5.10 的代码中强制使用 unicode 语义，无条件调用 utf8::upgrade($string)。
$flag = utf8::valid($string)

[内部] 测试 $string 是否在 UTF-8 方面处于一致状态。如果它是格式良好的 Perl 扩展 UTF-8 并且具有 UTF-8 标志，或如果 $string 作为字节保存（这两种状态都是“一致的”），则返回 true。此例程的主要原因是允许 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 文件名。因此，文件系统可见的 UTF-8 名称（例如模块名称）可能无法使用。

#另请参阅

perlunitut、perluniintro、perlrun、bytes、perlunicode