utf8 - ソースコード内に、UTF-8(か、UTF-EBCDIC)を有効/無効にするためのプラグマ
use utf8;
no utf8;
# Convert a Perl scalar to/from UTF-8.
$num_octets = utf8::upgrade($string);
$success = utf8::downgrade($string[, FAIL_OK]);
# Change the native bytes of a Perl scalar to/from UTF-8 bytes.
utf8::encode($string);
utf8::decode($string);
$flag = utf8::is_utf8(STRING); # since Perl 5.8.1
$flag = utf8::valid(STRING);use utf8 プラグマは、Perl パーサーに、現在のレキシカルスコープ内の プログラムのテキストに、UTF-8(EBCDIC ベースのプラットフォームなら、UTF-EBCDIC) を許すように伝えます。 no utf8 プラグマは Perl に、現在のレキシカルスコープのソーステキストを リテラルなバイトとして扱うように伝えます。
スクリプトが UTF-8 で書かれているということを Perl に教える目的以外で このプラグマをつかってはいけません。 下に書かれているユーティリティ関数は、use utf8; なしで 直接使えます。
ネイティブな 8 ビットエンコーディングから UTF-8 であると確実に 知らせることは不可能なので、perl に知らせるためにソースコードの先頭に バイト順マークを置くか、use utf8; を指定するかのどちらかが必要です。
UTF-8 が標準ソースフォーマットとなったときには、 このプラグマは事実上何もしなくなります。 利便性のために、以下での UTF-X という単語は、 ASCII と ISO Latin ベースのプラットフォームでは UTF-8 を示し、 EBCDIC ベースのプラットフォームでは UTF-EBCDIC を示すものとします。
perlrun にある、-C スイッチ及びそのいとこの $ENV{PERL_UNICODE} の 効果も参照してください。
utf8 プラグマを有効にすると次の効果があります:
高ビットのセットのあるソーステキストにあるバイトは、 リテラルの UTF-X シーケンスの部分として扱われます。 このことは、ほとんどのリテラル、識別子の名前、 文字列定数、正規表現パターン定数も含みます。
EBCDIC プラットフォームでは、Latin 1 文字集合の文字は、 リテラルの UTF-EBCDIC の文字として扱われます。
スクリプト内に 8 ビットのバイト列がある(たとえば、文字列リテラルに Latin-1 がある)なら、use utf8 は不幸をもたらすでしょう; バイト列は、ほとんどの場合、適切な UTF-X ではないからです。 use utf8 内でそのようなバイト列を使いたい場合は、ブロック(または、 最上部に書けば、ファイル)の終わりまで、no utf8; で、utf8 を 無効にできます。
下記の関数は、Perl core によって、utf8:: パッケージに定義されています。 これらの関数を使うのに、use utf8 する必要はありませんし、 実際、本当に UTF-8 のソースコードを書こうとするのでないなら、 use utf8 すべきではありません。
$num_octets = utf8::upgrade($string)
ネイティブエンコーディング (Latin-1 や EBCDIC) の内部オクテットシーケンスを、 等価な UTF-X の文字シーケンスに適切に変換します。 $string が既に文字としてエンコードされている場合は何もしません。 UTF-X として、文字列を表現するのに必要なオクテットの数を返します。 UTF-8 フラグがオンであることを確認するのに使えます; ですので、\w や lc() は、(ASCII とその派生では) 0x80-0xFF の 文字を含む文字列で期待されるように動きます。
この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。 従って、一般的な用途では Encode を推奨します; Encode も 参照してください。
$success = utf8::downgrade($string[, FAIL_OK])
UTF-Xの内部オクテットシーケンスを、 等価なネイティブエンコーディング (Latin-1 や EBCDIC) の 内部オクテットシーケンスに適切に変換します。 $string が既にネイティブな 8 ビットとしてエンコードされている場合は 何もしません。 たとえば、substr() や length()関数が、 通常はより速いバイトアルゴリズムで動くようにしたい場合、 UTF-8フラグがオフであるのを確認するのに使えます。
元の UTF-X シーケンスがネイティブな 8 ビットエンコーディングで 表現できない場合は失敗します。 失敗したときには、FAIL_OK の値が真の場合は偽を返し、そうでない場合は die します。
成功すると真を返します。
この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。 従って、一般的な用途では Encode を推奨します; Encode も 参照してください。
utf8::encode($string)
文字シーケンスを、対応する UTF-X のオクテットシーケンスに 適切に変換します。 UTF8 フラグはオフになるので、この操作の後、文字列は バイト文字列になります。 何も返しません。
この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。 従って、一般的な用途では Encode を推奨します; Encode も 参照してください。
$success = utf8::decode($string)
UTF-X のオクテットシーケンスを、対応する文字シーケンスに 適切に変換しようとします。 UTF-8 フラグは、元の文字列が複数バイトの UTF-X 文字を含んでいる場合にのみ オンになります。 もし $string が UTF-X として不正なら、偽を返します; さもなければ真を返します。
この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。 従って、一般的な用途では Encode を推奨します; Encode も 参照してください。
$flag = utf8::is_utf8(STRING)
(Perl 5.8.1から) STRING が、内部的に UTF-8 かどうかをテストします。 機能的には、Encode::is_utf8() と同じです。
$flag = utf8::valid(STRING)
[内部関数] STRING が UTF-8 として一貫しているかを調べます。 STRING が well-formed UTF-8 で UTF-8 フラグがオンの場合 または 文字列がバイトとして保持されている場合に真を返します (両方とも状態は「一貫して」います)。 このルーチンの主目的は、 ある操作が文字列を一貫した状態に保っているかをPerl のテストスイートが 調べられるようにすることです。 おそらくたいていの場合は代わりに utf8::is_utf8() を使いたいはずです。
utf8::encode は、utf8::upgrade に似ていますが、UTF8 フラグが 削除されます。 UTF8 フラグの詳細および、Perl 関数の utf8::upgrade, utf8::downgrade, utf8::encode, utf8::decode でラッピングされている C API 関数 sv_utf8_upgrade, sv_utf8_downgrade, sv_utf8_encode, sv_utf8_decode については perlunicode を 参照してください。 また、utf8::is_utf8, utf8::valid, utf8::encode, utf8::decode, utf8::upgrade, utf8::downgrade は、 実際には内部関数なので、常に require utf8 なしで利用可能になっています。
識別子の名前として Unicode を使えますが、パッケージ/クラスや サブルーチンの名前としては使えません。 Perl 5.8.0 からはこれに関する限定された機能が存在しますが、 これらは予定されたものというよりは偶然の産物です; このような目的で Unicode を使うことは非サポートです。
この不完全性の原因の一つは(現在のところ)先天的な非移植性です; パッケージ名とサブルーチン名はそれぞれファイルとディレクトリ名に 対応付けられる必要があるので、ファイルシステムの Unicode 対応が 重要となります -- そして残念ながら移植性のある答えが存在しません。