=encoding euc-jp =head1 NAME =begin original utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source code =end original utf8 - ソースコード内の UTF-8(または UTF-EBCDIC) を有効/無効にするためのプラグマ =head1 SYNOPSIS 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}" $flag = utf8::is_utf8(STRING); # since Perl 5.8.1 $flag = utf8::valid(STRING); =head1 DESCRIPTION =begin original The C pragma tells the Perl parser to allow UTF-8 in the program text in the current lexical scope (allow UTF-EBCDIC on EBCDIC based platforms). The C pragma tells Perl to switch back to treating the source text as literal bytes in the current lexical scope. =end original C プラグマは、Perl パーサーに、現在のレキシカルスコープ内の プログラムのテキストに UTF-8(EBCDIC ベースのプラットフォームなら、UTF-EBCDIC) を許すように伝えます。 C プラグマは Perl に、現在のレキシカルスコープのソーステキストを リテラルなバイトとして扱うように伝えます。 =begin original B The utility functions described below are directly usable without C. =end original B<スクリプトが UTF-8 で書かれているということを Perl に教える目的以外で このプラグマをつかってはいけません。> 下に書かれているユーティリティ関数は、C なしで直接使えます。 =begin original Because it is not possible to reliably tell UTF-8 from native 8 bit encodings, you need either a Byte Order Mark at the beginning of your source code, or C, to instruct perl. =end original ネイティブな 8 ビットエンコーディングから UTF-8 であると確実に 知らせることは不可能なので、perl に知らせるためにソースコードの先頭に バイト順マークを置くか、C を指定するかのどちらかが必要です。 =begin original When UTF-8 becomes the standard source format, this pragma will effectively become a no-op. For convenience in what follows the term I is used to refer to UTF-8 on ASCII and ISO Latin based platforms and UTF-EBCDIC on EBCDIC based platforms. =end original UTF-8 が標準ソースフォーマットとなったときには、 このプラグマは事実上何もしなくなります。 利便性のために、以下での I という単語は、 ASCII と ISO Latin ベースのプラットフォームでは UTF-8 を示し、 EBCDIC ベースのプラットフォームでは UTF-EBCDIC を示すものとします。 =begin original See also the effects of the C<-C> switch and its cousin, the C<$ENV{PERL_UNICODE}>, in L. =end original L にある、C<-C> スイッチ及びそのいとこの C<$ENV{PERL_UNICODE}> の 効果も参照してください。 =begin original Enabling the C pragma has the following effect: =end original C プラグマを有効にすると次の効果があります: =over 4 =item * =begin original Bytes in the source text that have their high-bit set will be treated as being part of a literal UTF-X sequence. This includes most literals such as identifier names, string constants, and constant regular expression patterns. =end original 高ビットがセットされている、ソーステキストにあるバイトは、 リテラルの UTF-X シーケンスの部分として扱われます。 このことは、ほとんどのリテラル、識別子の名前、 文字列定数、正規表現パターン定数も含みます。 =begin original On EBCDIC platforms characters in the Latin 1 character set are treated as being part of a literal UTF-EBCDIC character. =end original EBCDIC プラットフォームでは、Latin 1 文字集合の文字は、 リテラルの UTF-EBCDIC の文字として扱われます。 =back =begin original Note that if you have bytes with the eighth bit on in your script (for example embedded Latin-1 in your string literals), C will be unhappy since the bytes are most probably not well-formed UTF-X. If you want to have such bytes under C, you can disable this pragma until the end the block (or file, if at top level) by C. =end original スクリプト内に 8 ビットのバイト列がある(たとえば、文字列リテラルに Latin-1 がある)なら、C は不幸をもたらすでしょう; バイト列は、ほとんどの場合、適切な UTF-X ではないからです。 C 内でそのようなバイト列を使いたい場合は、ブロック(または、 最上部に書けば、ファイル)の終わりまで、C で、utf8 を 無効にできます。 =head2 Utility functions (ユーティリティ関数) =begin original The following functions are defined in the C package by the Perl core. You do not need to say C to use these and in fact you should not say that unless you really want to have UTF-8 source code. =end original 下記の関数は、Perl core によって、C パッケージに定義されています。 これらの関数を使うのに、C する必要はありませんし、 実際、本当に UTF-8 のソースコードを書こうとするのでないなら、 C すべきではありません。 =over 4 =item * $num_octets = utf8::upgrade($string) =begin original Converts in-place the internal representation of the string from an octet sequence in the native encoding (Latin-1 or EBCDIC) to I. The logical character sequence itself is unchanged. If I<$string> is already stored as I, then this is a no-op. Returns the number of octets necessary to represent the string as I. Can be used to make sure that the UTF-8 flag is on, so that C<\w> or C work as Unicode on strings containing characters in the range 0x80-0xFF (on ASCII and derivatives). =end original 文字列の内部表現を、ネイティブエンコーディング (Latin-1 や EBCDIC) の オクテットシーケンスから I にその場で変換します。 論理的な文字並び自身は変更されません。 I<$string> が既に I として保管されている場合は何もしません。 I として、文字列を表現するのに必要なオクテットの数を返します。 UTF-8 フラグがオンであることを確認するのに使えます; ですので、C<\w> や C は、(ASCII とその派生では) 0x80-0xFF の 文字を含む文字列で期待されるように動きます。 =begin original B Therefore Encode is recommended for the general purposes; see also L. =end original B<この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。> 従って、一般的な用途では Encode を推奨します; L も 参照してください。 =item * $success = utf8::downgrade($string[, FAIL_OK]) =begin original Converts in-place the the internal representation of the string from I to the equivalent octet sequence in the native encoding (Latin-1 or EBCDIC). The logical character sequence itself is unchanged. If I<$string> is already stored as native 8 bit, then this is a no-op. Can be used to make sure that the UTF-8 flag is off, e.g. when you want to make sure that the substr() or length() function works with the usually faster byte algorithm. =end original 文字列の内部表現を、I から等価なネイティブエンコーディング (Latin-1 や EBCDIC) の内部オクテットシーケンスにその場で変換します。 論理的な文字並び自身は変更されません。 I<$string> が既にネイティブな 8 ビットとして保管されている場合は 何もしません。 たとえば、substr() や length() 関数が、 通常はより速いバイトアルゴリズムで動くようにしたい場合、 UTF-8フラグがオフであるのを確認するのに使えます。 =begin original Fails if the original I sequence cannot be represented in the native 8 bit encoding. On failure dies or, if the value of C is true, returns false. =end original 元の I シーケンスがネイティブな 8 ビットエンコーディングで 表現できない場合は失敗します。 失敗したときには、C の値が真の場合は偽を返し、そうでない場合は die します。 =begin original Returns true on success. =end original 成功すると真を返します。 =begin original B Therefore Encode is recommended for the general purposes; see also L. =end original B<この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。> 従って、一般的な用途では Encode を推奨します; L も 参照してください。 =item * utf8::encode($string) =begin original Converts in-place the character sequence to the corresponding octet sequence in I. That is, every (possibly wide) character gets replaced with a sequence of one or more characters that represent the individual I bytes of the character. The UTF8 flag is turned off. Returns nothing. =end original 文字シーケンスを、対応する I のオクテットシーケンスに その場で変換します。 つまり、それぞれの(ワイドかもしれない)文字は、個々の I バイトの 文字を表現する一つ以上の文字の並びに置き換えられます。 UTF8 フラグはオフになります。 何も返しません。 my $a = "\x{100}"; # $a contains one character, with ord 0x100 utf8::encode($a); # $a contains two characters, with ords 0xc4 and 0x80 =begin original B Therefore Encode is recommended for the general purposes; see also L. =end original B<この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。> 従って、一般的な用途では Encode を推奨します; L も 参照してください。 =item * $success = utf8::decode($string) =begin original Attempts to convert in-place the octet sequence in I to the corresponding character sequence. That is, it replaces each sequence of characters in the string whose ords represent a valid UTF-X byte sequence, with the corresponding single character. The UTF-8 flag is turned on only if the source string contains multiple-byte I characters. If I<$string> is invalid as I, returns false; otherwise returns true. =end original I のオクテットシーケンスを、対応する文字シーケンスに 適切に変換しようとします。 UTF-8 フラグは、元の文字列が複数バイトの I 文字を含んでいる場合にのみ オンになります。 もし I<$string> が I として不正なら、偽を返します; さもなければ真を返します。 my $a = "\xc4\x80"; # $a contains two characters, with ords 0xc4 and 0x80 utf8::decode($a); # $a contains one character, with ord 0x100 =begin original B Therefore Encode is recommended for the general purposes; see also L. =end original B<この関数は、任意のエンコーディングを扱えるわけではないことに 注意してください。> 従って、一般的な用途では Encode を推奨します; L も 参照してください。 =item * $flag = utf8::is_utf8(STRING) =begin original (Since Perl 5.8.1) Test whether STRING is in UTF-8 internally. Functionally the same as Encode::is_utf8(). =end original (Perl 5.8.1 から) STRING が、内部的に UTF-8 かどうかをテストします。 機能的には、Encode::is_utf8() と同じです。 =item * $flag = utf8::valid(STRING) =begin original [INTERNAL] Test whether STRING is in a consistent state regarding UTF-8. Will return true is well-formed UTF-8 and has the UTF-8 flag on B if string is held as bytes (both these states are 'consistent'). Main reason for this routine is to allow Perl's testsuite to check that operations have left strings in a consistent state. You most probably want to use utf8::is_utf8() instead. =end original [内部関数] STRING が UTF-8 として一貫しているかを調べます。 STRING が well-formed UTF-8 で UTF-8 フラグがオンの場合 B<または> 文字列がバイトとして保持されている場合に真を返します (両方とも状態は「一貫して」います)。 このルーチンの主目的は、 ある操作が文字列を一貫した状態に保っているかを Perl のテストスイートが 調べられるようにすることです。 おそらくたいていの場合は代わりに utf8::is_utf8() を使いたいはずです。 =back =begin original C is like C, but the UTF8 flag is cleared. See L for more on the UTF8 flag and the C API functions C, C, C, and C, which are wrapped by the Perl functions C, C, C and C. Also, the functions utf8::is_utf8, utf8::valid, utf8::encode, utf8::decode, utf8::upgrade, and utf8::downgrade are actually internal, and thus always available, without a C statement. =end original C は、C に似ていますが、UTF8 フラグが 削除されます。 UTF8 フラグの詳細および、Perl 関数の C, C, C, C でラッピングされている C API 関数 C, C, C, C については L を 参照してください。 また、utf8::is_utf8, utf8::valid, utf8::encode, utf8::decode, utf8::upgrade, utf8::downgrade は、 実際には内部関数なので、常に C なしで利用可能になっています。 =head1 BUGS =begin original One can have Unicode in identifier names, but not in package/class or subroutine names. While some limited functionality towards this does exist as of Perl 5.8.0, that is more accidental than designed; use of Unicode for the said purposes is unsupported. =end original 識別子の名前として Unicode を使えますが、パッケージ/クラスや サブルーチンの名前としては使えません。 Perl 5.8.0 からはこれに関する限定された機能が存在しますが、 これらは予定されたものというよりは偶然の産物です; このような目的で Unicode を使うことは非サポートです。 =begin original One reason of this unfinishedness is its (currently) inherent unportability: since both package names and subroutine names may need to be mapped to file and directory names, the Unicode capability of the filesystem becomes important-- and there unfortunately aren't portable answers. =end original この不完全性の原因の一つは(現在のところ)先天的な非移植性です; パッケージ名とサブルーチン名はそれぞれファイルとディレクトリ名に 対応付けられる必要があるので、ファイルシステムの Unicode 対応が 重要となります -- そして残念ながら移植性のある答えが存在しません。 =head1 SEE ALSO L, L, L, L, L =begin meta Translate: Ktat Update: Kentaro Shirakata (1.07-) Status: completed =end meta =cut