Unicode-Japanese-0.18 > Unicode::Japanese
Unicode-Japanese-0.18

名前

Unicode::Japanese - Japanese Character Encoding Handler

Unicode::Japanese - 日本語文字コード変換

概要

  use Unicode::Japanese;

  # convert utf8 -> sjis
  print Unicode::Japanese->new($str)->sjis;

  # convert sjis -> utf8
  print Unicode::Japanese->new($str,'sjis')->get;

  # convert sjis (imode_EMOJI) -> utf8
  # convert sjis (imode絵文字) -> utf8
  print Unicode::Japanese->new($str,'sjis-imode')->get;
  
  # convert ZENKAKU (utf8) -> HANKAKU (utf8)
  # convert 全角 (utf8) -> 半角(utf8)

  print Unicode::Japanese->new($str)->z2h->get;

説明

Module for conversion among Japanese character encodings.

Unicode::Japanese は,日本語の文字コードの相互変換を行うモジュールです.

FEATURES

以下のような特徴があります.

  • The instance stores internal strings in UTF-8.

    Unicode::Japanese のインスタンスは,UTF-8 で文字列を保持します.

  • Supports both XS and Non-XS. Use XS for high performance, or No-XS for ease to use (only by copying Japanese.pm).

    XS 使用/不使用を共にサポートしています. XS 版はパフォーマンスが必要な場合に, No-XS 版は手軽に使用したい場合に使用して下さい (Japanese.pm をコピーするだけで動作します).

  • Supports conversion between ZENKAKU and HANKAKU.

    全角半角変換,カタカナひらがな変換をサポートしています.

  • Safely handles "EMOJI" of the mobile phones (DoCoMo i-mode, ASTEL dot-i and J-PHONE J-Sky) by mapping them on Unicode Private Use Area.

    携帯電話 (DoCoMo i-mode,ASTEL dot-i,J-PHONE J-Sky) の絵文字を Unicode 私用領域にマッピングすることで,DB 等で安全に扱うことができます.

  • Supports conversion of the same image of EMOJI between different mobile phone's standard mutually.

    異なる携帯電話同士で,同じイメージの絵文字は相互変換することが可能です.

  • Considers Shift_JIS(SJIS) as MS-CP932. (Shift_JIS on MS-Windows (MS-SJIS/MS-CP932) differ from generic Shift_JIS encodings.)

    SJIS は, MS-CP932 とみなして Unicode とマッピングを行います.

  • On converting Unicode to SJIS (and EUC-JP/JIS), those encodings that cannot be converted to SJIS (except "EMOJI") are escaped in "&#dddd;" format. "EMOJI" on Unicode Private Use Area is going to be '?'. When converting strings from Unicode to SJIS of mobile phones, any characters not up to their standard is going to be '?'

    Unicode -> SJIS(及びEUC-JP/JIS) のマッピング時,SJIS で表現できない文字は &#dddd; 形式に変換します. ただしUnicode私用領域におかれている絵文字は '?'になります. また, 携帯電話向けの変換時には, すべての対応しない文字は'?'になります.

  • On perl-5.8.0 and later, setting of utf-8 flag is performed properly. utf8() method returns utf-8 `bytes' string and getu() method returns utf-8 `char' string.

    Perl-5.8.0 以降において, utf8 フラグの設定処理を行います. utf-8 `バイト'列 の取得には utf8() メソッドを, utf-8 `文字'列 の取得には getu() メソッドを使います.

    get() method returns utf-8 `bytes' string in current release. in future, the behavior of get() maybe change.

    get() メソッドは現時点では utf-8 `バイト'列 を返します (将来的に変更される可能性もあります).

    sjis(), jis(), utf8(), etc.. methods return bytes string. The input of new, set, and a getcode method is not asked about utf8/bytes.

    sjis(), jis(), utf8(), etc.. メソッドではバイト列を返します. new, set, getcode メソッドの入力には, utf8/bytes を問いません.

メソッド

$s = Unicode::Japanese->new($str [, $icode [, $encode]])

Creates a new instance of Unicode::Japanese.

新しい Unicode::Japanese インスタンスを指定します.

If arguments are specified, passes through to set method.

パラメータを指定すると,set メソッドに渡されます.

$s->set($str [, $icode [, $encode]])
$str: string

($str: 文字列)

$icode: character encodings, may be omitted (default = 'utf8')

($icode: 文字コード指定.省略可.省略時は 'utf8')

$encode: ASCII encoding, may be omitted.

($encode: 文字エンコード.省略可.)

Set a string in the instance. If '$icode' is omitted, string is considered as UTF-8.

インスタンスに文字列をセットします. 文字コード指定を省略すると UTF-8 と見なされます.

To specify a encodings, choose from the following; 'jis', 'sjis', 'euc', 'utf8', 'ucs2', 'ucs4', 'utf16', 'utf16-ge', 'utf16-le', 'utf32', 'utf32-ge', 'utf32-le', 'ascii', 'binary', 'sjis-imode', 'sjis-doti', 'sjis-jsky'.

文字コードを指定する場合は,次のいずれかを選んでください. 'jis', 'sjis', 'euc', 'utf8', 'ucs2', 'ucs4', 'utf16', 'utf16-ge', 'utf16-le', 'utf32', 'utf32-ge', 'utf32-le', 'ascii', 'binary', 'sjis-imode', 'sjis-doti', 'sjis-jsky'.

'&#dddd' will be converted to "EMOJI", when specified 'sjis-imode' or 'sjis-doti'.

'sjis-imode' もしくは 'sjis-doti' が指定されているときには '&#dddd' は絵文字へと変換されます.

For auto encoding detection, you MUST specify 'auto' so as to call getcode() method automatically.

文字コードを自動判別する場合は,'auto' を指定しなくてはいけません.

For ASCII encoding, only 'base64' may be specified. With it, the string will be decoded before storing.

文字エンコードには,'base64' のみ指定可能です. base64 を指定した場合は,base64 デコードされてから インスタンスに格納されます.

To decode binary, specify 'binary' as the encoding.

バイナリをデコードする場合は,文字エンコードタイプとして 'binary' を指定します.

$str = $s->get
$str: string (UTF-8)

($str: 文字列(UTF-8))

Gets a string with UTF-8.

文字列を UTF-8 コードで取り出します.

return `bytes' string in current release, this behavior will be changed.

現在は `バイト' 列 を返しますが, 将来的に変更される可能性もあります.

utf8() method for `character' string or getu() method for `bytes' string seems better.

バイト列が必要なら utf8() メソッドを, 文字列が必要なら getu() メソッドを使うことをオススメします.

$str = $s->getu
$str: string (UTF-8)

($str: 文字列(UTF-8))

Gets a string with UTF-8.

文字列を UTF-8 コードで取り出します.

On perl-5.8.0 and later, return value is with utf-8 flag.

Perl-5.8.0 以降においては, utf-8 フラグのついた utf-8 文字列として 返します.

$code = $s->getcode($str)
$str: string

($str: 文字列)

$code: character encoding name

($code: 文字コードを表す文字列)

Detects the character encodings of $str.

渡された文字列($str)の文字コードを自動判別します.

Notice: This method detects NOT encoding of the string in the instance but $str.

この関数では, 例外的に, インスタンスに保持されている文字列のコードを判別するのではないことに注意してください.

Character encodings are distinguished by the following algorithm:

文字コード自動判別時は,以下のアルゴリズムにより判定が行われます.

(In case of PurePerl)

(PurePerl時)

  1. If BOM of UTF-32 is found, the encoding is utf32.

    UTF-32 の BOM があれば,utf32 と判定します.

  2. If BOM of UTF-16 is found, the encoding is utf16.

    UTF-16 の BOM があれば,utf16 と判定します.

  3. If it is in proper UTF-32BE, the encoding is utf32-be.

    UTF-32BE として正しい形式なら,utf32-be と判定します.

  4. If it is in proper UTF-32LE, the encoding is utf32-le.

    UTF-32LE として正しい形式なら,utf32-le と判定します.

  5. Without NON-ASCII characters, the encoding is ascii. (control codes except escape sequences has been included in ASCII)

    非 ASCII 文字が含まれていなければ, ascii と判定します. (非 ASCII 文字には,エスケープシーケンス以外のコントロールコードは含まれません.)

  6. If it includes ISO-2022-JP(JIS) escape sequences, the encoding is jis.

    JISエスケープシーケンスが含まれていれば,jis と判定します.

  7. If it includes "J-PHONE EMOJI", the encoding is sjis-sky.

    J-PHONE の絵文字が含まれていれば,sjis-jsky と判別します.

  8. If it is in proper EUC-JP, the encoding is euc.

    EUC-JP コードとして正しい形式なら,euc と判定します.

  9. If it is in proper SJIS, the encoding is sjis.

    SJIS コードとして正しい形式なら,sjis と判定します.

  10. If it is in proper SJIS and "EMOJI" of i-mode, the encoding is sjis-imode.

    SJIS と i-mode の絵文字として正しい形式なら,sjis-imode と判別します.

  11. If it is in proper SJIS and "EMOJI" of dot-i,the encoding is sjis-doti.

    SJIS と dot-i の絵文字として正しい形式なら,sjis-doti と判別します.

  12. If it is in proper UTF-8, the encoding is utf8.

    UTF-8 として正しい形式なら,utf8 と判定します.

  13. If none above is true, the encoding is unknown.

    いずれにも当てはまらない場合,unknown と判定します.

(In case of XS)

(XS時)

  1. If BOM of UTF-32 is found, the encoding is utf32.

    UTF-32 の BOM があれば,utf32 と判定します.

  2. If BOM of UTF-16 is found, the encoding is utf16.

    UTF-16 の BOM があれば,utf16 と判定します.

  3. String is checked by State Transition if it is applicable for any listed encodings below.

    以下のコードについて, 正しい文字コードであることを状態遷移を用いて調べます.

    ascii / euc-jp / sjis / jis / utf8 / utf32-be / utf32-le / sjis-jsky / sjis-imode / sjis-doti

  4. The listed order below is applied for a final determination.

    最後まで正しかったものの中から, 以下の優先順で1つをえらんで, それと判定します.

    utf32-be / utf32-le / ascii / jis / euc-jp / sjis / sjis-jsky / sjis-imode / sjis-doti / utf8

  5. If none above is true, the encoding is unknown.

    いずれにも当てはまらない場合,unknown と判定します.

Regarding the algorithm, pay attention to the following:

以上のアルゴリズムのため,以下の点に注意してください.

  • UTF-8 is occasionally detected as SJIS.

    UTF-8 文字列でも,SJISコードと見なされる可能性があります.

  • Can NOT detect UCS2 automatically.

    UCS2 の自動判別はできません.

  • Can detect UTF-16 only when the string has BOM.

    UTF-16 は BOM がある場合のみ自動認識します.

  • Can detect "EMOJI" when it is stored in binary, not in "&#dddd;" format. (If only stored in "&#dddd;" format, getcode() will return incorrect result. In that case, "EMOJI" will be crashed.)

    携帯絵文字は,バイナリで直接絵文字がある場合のみ認識できます. &#dddd; 形式で記述されている場合は,携帯絵文字の自動判別は行われません. (&#dddd; のみの場合,参照先が異なるため,その後 getcode() の結果を 基に変換を行うと,絵文字が化けます.)

Because each of XS and PurePerl has a different algorithm, A result of the detection would be possibly different. In case that the string is SJIS with escape characters, it would be considered as SJIS on PurePerl. However, it can't be detected as S-JIS on XS. This is because by using Algorithm, the string can't be distinguished between SJIS and SJIS-Jsky. This exclusion of escape characters on XS from the detection is suppose to be the same for EUC-JP.

XSとPurePerlでは, 判別のアルゴリズムに違いがあるため, 異なる結果になる可能性があります. 特に, エスケープ文字を含んでいるsjisの場合, PurePerlではsjisと認識しますが XSでは認識しません. これはsjis-jskyと区別できなくなるためです. また, この 作用による誤認識を防ぐため, euc-jpにおいても, 同様にエスケープ文字を受け付けなく なっています.

$str = $s->conv($ocode, $encode)
$ocode: output character encoding (Choose from 'jis', 'sjis', 'euc', 'utf8', 'ucs2', 'ucs4', 'utf16', 'binary')

($ocode: 出力コード 'jis', 'sjis', 'euc', 'utf8', 'ucs2', 'ucs4', 'utf16', 'binary', の中から指定.)

$encode: encoding, may be omitted.

($encode: 文字エンコード.省略可.)

$str: string

($str: 文字列)

Gets a string converted to $ocode.

文字列を指定した文字コードに変換してから取り出します.

For ASCII encoding, only 'base64' may be specified. With it, the string encoded in base64 will be returned.

文字エンコードには,'base64' のみ指定可能です. base64 を指定した場合は,base64 エンコードされた 文字列が返されます.

On perl-5.8.0 and later, return value is not with utf-8 flag, and is bytes string.

perl-5.8.0 以降において, 出力は utf-8 フラグを持たないバイト列になります.

$s->tag2bin

Replaces the substrings "&#dddd;" in the string with the binary entity they mean.

文字列中に含まれる &#dddd; 形式の文字列を,それが表す文字自体に置き換えます.

$s->z2h

Converts ZENKAKU to HANKAKU.

全角を半角に変換します.

$s->h2z

Converts HANKAKU to ZENKAKU.

半角を全角に変換します.

$s->hira2kata

Converts HIRAGANA to KATAKANA.

ひらがなをカタカナに変換します.

$s->kata2hira

Converts KATAKANA to HIRAGANA.

カタカナをひらがなに変換します.

$str = $s->jis

$str: string (JIS)

$str: JIS エンコーディング形式のバイト列

Gets the string converted to ISO-2022-JP(JIS).

文字列を JIS(ISO-2022-JP) コードで取り出します.

$str = $s->euc

$str: string (EUC-JP)

$str: euc-jp エンコーディング形式のバイト列

Gets the string converted to EUC-JP.

文字列を EUC-JP コードで取り出します.

$str = $s->utf8

$str: `bytes' string (UTF-8)

$str: utf-8 エンコーディング形式のバイト列

Gets the string converted to UTF-8.

文字列を UTF-8 コードで取り出します.

On perl-5.8.0 and later, return value is not with utf-8 flag, and is bytes string.

perl-5.8.0 以降においても, バイト列を返します.

$str = $s->ucs2

$str: string (UCS2)

$str: ucs2 エンコーディング形式のバイト列

Gets the string converted to UCS2.

文字列を UCS2 コードで取り出します.

$str = $s->ucs4

$str: string (UCS4)

$str: ucs4 エンコーディング形式のバイト列

Gets the string converted to UCS4.

文字列を UCS4 コードで取り出します.

$str = $s->utf16

$str: string (UTF-16)

$str: ucs-16 エンコーディング形式のバイト列

Gets the string converted to UTF-16(big-endian). BOM is not added.

文字列を UTF-16 コードで取り出します. BOMは付きません. ビックエンディアン形式で返されます.

$str = $s->sjis

$str: string (SJIS)

$str: sjis エンコーディング形式のバイト列

Gets the string converted to Shift_JIS(MS-SJIS/MS-CP932).

文字列を SJIS(MS-CP932) コードで取り出します.

$str = $s->sjis_imode

$str: string (SJIS/imode_EMOJI)

$str: sjis/imode絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for i-mode. This method is alias of sjis_imode2 on VERSION 0.15.

文字列を i-mode端末向けの SJIS コードで取り出します. 最新のimode絵文字(VERSION 0.15 では, imode2)の別名です.

$str = $s->sjis_imode1

$str: string (SJIS/imode_EMOJI)

$str: sjis/imode絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for i-mode. $str includes only basic pictgraphs, and is without extended pictgraphs.

文字列を i-mode端末向けの SJIS コードで取り出します. 基本絵文字, 拡張絵文字を含みます.

$str = $s->sjis_imode2

$str: string (SJIS/imode_EMOJI)

$str: sjis/imode絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for i-mode. $str includes both basic pictgraphs, and extended ones.

文字列を i-mode端末向けの SJIS コードで取り出します. 基本絵文字だけから成ります.

$str = $s->sjis_doti

$str: string (SJIS/dot-i_EMOJI)

$str: sjis/dot-i絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for dot-i.

文字列を dot-i端末向けの SJIS コードで取り出します.

$str = $s->sjis_jsky

$str: string (SJIS/J-SKY_EMOJI)

$str: sjis/j-sky絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for j-sky. This method is alias of sjis_jsky2 on VERSION 0.15.

文字列を j-sky端末向けの SJIS コードで取り出します. 最新のj-sky絵文字(VERSION 0.15 では, jsky2)の別名です.

$str = $s->sjis_jsky2

$str: string (SJIS/J-SKY_EMOJI)

$str: sjis/j-sky絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for j-sky. $str includes from Page 1 to Page 6.

文字列を j-sky端末向けの SJIS コードで取り出します. Page 1-6 の絵文字を含みます.

$str = $s->sjis_jsky1

$str: string (SJIS/J-SKY_EMOJI)

$str: sjis/j-sky絵文字 エンコーディング形式のバイト列

Gets the string converted to SJIS for j-sky. $str includes from Page 1 to Page 3.

文字列を j-sky端末向けの SJIS コードで取り出します. Page 1-3 のみの絵文字を含みます.

@str = $s->strcut($len)
$len: number of characters

($len: 分割する文字数)

@str: strings

(@STR: 文字列)

Splits the string by length($len).

$lenで指定された文字数以下の文字列の配列に分割します.

On perl-5.8.0 and later, each element in return array is with utf-8 flag.

配列の各要素は, utf-8 フラグを持ったutf-8文字列です.

$len = $s->strlen

$len: `visual width' of the string

$len: 文字列の表示幅

Gets the length of the string. This method has been offered to substitute for perl build-in length(). ZENKAKU characters are assumed to have lengths of 2, regardless of the coding being SJIS or UTF-8.

UTF-8 文字に対して length() を使うと全角文字は1文字あたり長さ 3 になってしまいますが, このメソッドを使用すると,従来の SJIS のように,全角文字は1文字あたり長さ 2 を返します.

$s->join_csv(@values);
@values: data array

(@values: データ配列)

Converts the array to a string in CSV format, then stores into the instance. In the meantime, adds a newline("\n") at the end of string.

配列を CSV 文字列に変換し,インスタンスに格納します. 文字列の最後には改行("\n")が追加されます.

@values = $s->split_csv;
@values: data array

(@values: データ配列)

Splits the string, accounting it is in CSV format. Each newline("\n") is removed before split.

インスタンスに格納されている文字列を CSV と見なし,配列に分割します. 文字列の最後にある改行("\n")は取り除かれてから分割されます.

on perl-5.8.0 and later, utf-8 flag of return value depends on icode of set method. if $s contains binary, return value is bytes too. if $s contains any string, return value is with utf-8 flag.

入力が binary でなければ utf-8 文字列を返します. binary だったときはバイト列を返します.

UNICODE マッピング

Unicode とのマッピングは以下のように行われます.

SJIS

Mapped as MS-CP932. Mapping table in the following URL is used.

MS-CP932 として Unicode へマッピングを行います. マッピングテーブルは以下のURLのものを使用しています.

ftp://ftp.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP932.TXT

If a character cannot be mapped to SJIS from Unicode, it will be converted to &#dddd; format.

Unicode から SJIS へマッピングする場合に,表現できない文字があると, その文字は &#dddd; 形式に変換します.ただし,携帯絵文字は「?」に変換されます.

Also, any unmapped character will be converted into "?" when converting to SJIS for mobile phones.

また,携帯向けの SJIS へ変換するときは,全ての表現できない文字は「?」に変換されます.

EUC-JP/JIS

Converted to SJIS and then mapped to Unicode. Any non-SJIS character in the string will not be mapped correctly.

一度SJISコードに変換してから,Unicode へマッピングします. このとき,SJIS で表現できない文字が含まれていた場合, その文字は正しくマッピングできません.

DoCoMo i-mode

Portion of involving "EMOJI" in F800 - F9FF is maapped to U+0FF800 - U+0FF9FF.

F800 - F9FF の領域のうち絵文字が存在する部分を,U+0FF800 - U+0FF9FF の領域にマッピングします.

ASTEL dot-i

Portion of involving "EMOJI" in F000 - F4FF is mapped to U+0FF000 - U+0FF4FF.

F000 - F4FF の領域のうち絵文字が存在する部分を,U+0FF000 - U+0FF4FF の領域にマッピングします.

J-PHONE J-SKY

"J-SKY EMOJI" are mapped down as follows: "\e\$"(\x1b\x24) escape sequences, the first byte, the second byte and "\x0f". With sequential "EMOJI"s of identical first bytes, it may be compressed by arranging only the second bytes.

J-SKY の絵文字は,エスケープシーケンス "\e\$" の後に,絵文字1バイト目, 1つ以上の絵文字2バイト目,"\x0f",と続きます. 1バイト目が同じ絵文字が続く場合は,2バイト目のみを連続して書くことで圧縮することができます.

4500 - 47FF is mapped to U+0FFB00 - U+0FFDFF, accounting the first and the second bytes make one EMOJI character.

この1バイト目と2バイト目のペアを1文字と見なして,4500 - 47FF の領域を, U+0FFB00 - U+0FFDFF の領域にマッピングします.

Unicode::Japanese will compress "J-SKY_EMOJI" automatically when the first bytes of a sequence of "EMOJI" are identical.

Unicode::Japanese では,Unicode から J-SKY 絵文字にマッピングするとき, バイト目が同じ絵文字が連続している場合は,圧縮処理を自動的に行います.

PurePerl mode

   use Unicode::Japanese qw(PurePerl);

If module was loaded with 'PurePerl' keyword, it works on Non-XS mode.

PurePerl を引数に与えることで, XSを使わないことを明示的に宣言できます.

バグ

  • EUC-JP, JIS strings cannot be converted correctly when they include non-SJIS characters because they are converted to SJIS before being converted to UTF-8.

    EUC-JP,JIS コードは,SJIS に変換されてから UTF-8 へ変換されるため, SJIS で表現できない文字列は正しく変換することはできません.

  • When using XS, character encoding detection of EUC-JP and SJIS(included all EMOJI) strings when they include "\e" will fail. Also, getcode() and all convert method will not work.

    XSを使用している場合,EUC-JP,SJIS(絵文字含む)コードの文字列中に \e が含まれると,EUC-JP,SJIS コードの判定に失敗し, 正しく自動判別や変換を行うことが出来ません.

  • The Japanese.pm file will collapse if sent via ASCII mode of FTP, as it has a trailing binary data.

    Japanese.pm はファイル後半にバイナリを含むため,FTP の ASCII モードで 転送するとファイルが壊れます.

著作権表記

Copyright 2001-2002 SANO Taku (SAWATARI Mikage) and YAMASHINA Hio. All right reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

このプログラムはフリーソフトウェアです. このプログラムは Perl 自身と 同じ条件下で再配布・改変可能です.

Bug reports and comments to: mikage@cpan.org. Thank you.

協力

Thanks very much to:

NAKAYAMA Nao

SUGIURA Tatsuki & Debian JP Project