Unicode::Japanese::JA(3pm)

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

概要
 use Unicode::Japanese;
 use Unicode::Japanese qw(unijp);

 # convert utf8 -> sjis

 print Unicode::Japanese->new($str)->sjis;
 print unijp($str)->sjis; # same as above.

 # convert sjis -> utf8

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

 # convert sjis (imode_EMOJI) -> utf8

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

 # convert zenkaku (utf8) -> hankaku (utf8)

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

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

  機能

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

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

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

•   携帯電話 (DoCoMo i-mode，KDDI AU, Softbank Mobile, ASTEL dot-i) の絵文字を Unicode 私用領域にマッピングすることで，DB 等で安全に扱うことができます．

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

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

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

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

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

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

動作に必要なもの

•   perl 5.10.x, 5.8.x, etc. (5.004 以降).

•   (なくてもOK) C コンパイラ. このモジュールは XS と Pure Perl 両方に対応しています. C コンパイラがないときには, Unicode::Japanese は Pure Perl モジュールとしてインストールされます.

•   (なくてもOK) テスト用に Test.pm 及び Test::More.

実行時に必須なモジュールはありません.

メソッド

$s = Unicode::Japanese->new($str [, $icode [, $encode]])
    新しい Unicode::Japanese インスタンスを指定します．

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

$s = unijp($str [, $icode [, $encode]])
    Unicode::Janaese->new(...) と同義.

$s->set($str [, $icode [, $encode]])
    $str: 文字列
    $icode: 文字コード指定．省略可．省略時は 'utf8'
    $encode: バイナリ符号化方式．省略可．

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

    利用可能な文字コード:

     auto
     utf8 ucs2 ucs4
     utf16-be utf16-le utf16
     utf32-be utf32-le utf32
     sjis cp932 euc euc-jp jis
     sjis-imode sjis-imode1 sjis-imode2
     utf8-imode utf8-imode1 utf8-imode2
     sjis-doti sjis-doti1
     sjis-jsky sjis-jsky1 sjis-jsky2
     jis-jsky  jis-jsky1  jis-jsky2
     utf8-jsky utf8-jsky1 utf8-jsky2
     sjis-au sjis-au1 sjis-au2
     jis-au  jis-au1  jis-au2
     sjis-icon-au sjis-icon-au1 sjis-icon-au2
     euc-icon-au  euc-icon-au1  euc-icon-au2
     jis-icon-au  jis-icon-au1  jis-icon-au2
     utf8-icon-au utf8-icon-au1 utf8-icon-au2
     ascii binary

    ("サポートされているエンコーディング" も参照.)

    文字コードを自動判別する場合は，'auto' を指定しなくてはいけません． 'auto' 時の文字コード自動判別は，getcode() メソッドにより 行われます．

    バイナリ符号化方式には，'base64' のみ指定可能です． base64 を指定した場合は，base64 デコードされてから Unicode::Japanese クラスの文字列となります．

    渡された文字列を変更せずそのまま格納して欲しい場合には，文字コードとして 'binary' を指定します．

    sjis-imode，sjis-doti，の場合，文字列中の &#dddd; は 絵文字に変換されます．

    文字コードは領域が重なっている場合があるため， 自動判別は確実ではありません．

    sjis, utf8 の両方に解釈できる文字列の場合は，sjis， sjis-au，sjis-doti の両方に解釈できる文字列の場合は，sjis-au， を返します．

$str = $s->get
    $str: 文字列(UTF-8)

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

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

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

$str = $s->getu
    $str: 文字列(UTF-8)

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

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

$code = $s->getcode($str)
    $str: 文字列
    $code: 文字コードを表す文字列

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

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

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

    (PurePerl時)

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

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

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

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

    5.  ESC 文字 または 8 ビット目の立っている文字が含まれていなければ，ascii と判定しま す。ESC を除いた ASCII 制御文字 (0x00-0x1F 及び 0x7F) は ascii の範囲内と見做しま す。

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

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

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

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

    10. SJIS コードと au の絵文字として正しい形式なら，sjis-au と判定します．

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

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

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

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

    (XS時)

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

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

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

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

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

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

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

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

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

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

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

    •   携帯絵文字は，バイナリで直接絵文字がある場合のみ認識できます．
         &#dddd; 形式で記述されている場合は，携帯絵文字の自動判別は行われません．

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

$code = $s->getcodelist($str)
    $str: 文字列
    $code: 文字コードを表す文字列

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

    getcode とは違い, すべての受理可能な文字コードの 一覧を返します.

$str = $s->conv($ocode, $encode)
    $ocode: 出力コード (以下から指定)
         utf8 ucs2 ucs4 utf16
         sjis cp932 euc euc-jp jis
         sjis-imode sjis-imode1 sjis-imode2
         utf8-imode utf8-imode1 utf8-imode2
         sjis-doti sjis-doti1
         sjis-jsky sjis-jsky1 sjis-jsky2
         jis-jsky  jis-jsky1  jis-jsky2
         utf8-jsky utf8-jsky1 utf8-jsky2
         sjis-au sjis-au1 sjis-au2
         jis-au  jis-au1  jis-au2
         sjis-icon-au sjis-icon-au1 sjis-icon-au2
         euc-icon-au  euc-icon-au1  euc-icon-au2
         jis-icon-au  jis-icon-au1  jis-icon-au2
         utf8-icon-au utf8-icon-au1 utf8-icon-au2
         binary

        ("サポートされているエンコーディング" も参照.)

        携帯向け文字コードのうち，末尾に数字がついているものは，数字が大きいほど 大きな絵文字セット（最新機種の絵文字セット）を表しています． 数字なしのものは，もっとも数字が大きい文字コードと同一です．

    $encode: バイナリ符号化方式．省略可．
    $str: 文字列

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

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

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

$s->tag2bin
    文字列中に含まれる &#dddd; 形式の文字列を，それが表す文字自体に置き換えます．

$s->z2h
    全角を半角に変換します．

$s->h2z
    半角を全角に変換します．

$s->hira2kata
    ひらがなをカタカナに変換します．

$s->kata2hira
    カタカナをひらがなに変換します．

$str = $s->jis
    $str: JIS エンコーディング形式のバイト列

    文字列を JIS（ISO-2022-JP） コードで取り出します．

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

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

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

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

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

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

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

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

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

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

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

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

    文字列を SJIS（MS-CP932） コードで取り出します．

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

    文字列を i-mode 端末向けの SJIS コードで取り出します． 最新のimode絵文字の別名です.

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

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

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

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

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

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

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

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

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

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

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

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

$str = $s->sjis_icon_au
    $str: sjis/AU iconタグ エンコーディング形式のバイト列

    文字列を AU 端末向けの SJIS コードで取り出します．

$str_arrayref = $s->strcut($len)
    $len: 分割する文字数(全角相当)
    $str_arrayref: 文字列

    $lenで指定された文字数(全角)以下の文字列の配列に分割します．

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

$len = $s->strlen
    $len: 文字列の表示幅

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

$s->join_csv(@values);
    @values: データ配列

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

@values = $s->split_csv;
    @values: データ配列

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

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

サポートされているエンコーディング
 +---------------+----+-----+-------+
 |encoding       | in | out | guess |
 +---------------+----+-----+-------+
 |auto           : OK : --  | ----- |
 +---------------+----+-----+-------+
 |utf8           : OK : OK  | OK    |
 |ucs2           : OK : OK  | ----- |
 |ucs4           : OK : OK  | ----- |
 |utf16-be       : OK : --  | ----- |
 |utf16-le       : OK : --  | ----- |
 |utf16          : OK : OK  | OK(#) |
 |utf32-be       : OK : --  | OK    |
 |utf32-le       : OK : --  | OK    |
 |utf32          : OK : --  | OK(#) |
 +---------------+----+-----+-------+
 |sjis           : OK : OK  | OK    |
 |cp932          : OK : OK  | ----- |
 |euc            : OK : OK  | OK    |
 |euc-jp         : OK : OK  | ----- |
 |jis            : OK : OK  | OK    |
 +---------------+----+-----+-------+
 |sjis-imode     : OK : OK  | OK    |
 |sjis-imode1    : OK : OK  | ----- |
 |sjis-imode2    : OK : OK  | ----- |
 |utf8-imode     : OK : OK  | ----- |
 |utf8-imode1    : OK : OK  | ----- |
 |utf8-imode2    : OK : OK  | ----- |
 +---------------+----+-----+-------+
 |sjis-doti      : OK : OK  | OK    |
 |sjis-doti1     : OK : OK  | ----- |
 +---------------+----+-----+-------+
 |sjis-jsky      : OK : OK  | OK    |
 |sjis-jsky1     : OK : OK  | ----- |
 |sjis-jsky2     : OK : OK  | ----- |
 |jis-jsky       : OK : OK  | ----- |
 |jis-jsky1      : OK : OK  | ----- |
 |jis-jsky2      : OK : OK  | ----- |
 |utf8-jsky      : OK : OK  | ----- |
 |utf8-jsky1     : OK : OK  | ----- |
 |utf8-jsky2     : OK : OK  | ----- |
 +---------------+----+-----+-------+
 |sjis-au        : OK : OK  | OK    |
 |sjis-au1       : OK : OK  | ----- |
 |sjis-au2       : OK : OK  | ----- |
 |jis-au         : OK : OK  | ----- |
 |jis-au1        : OK : OK  | ----- |
 |jis-au2        : OK : OK  | ----- |
 |sjis-icon-au   : OK : OK  | ----- |
 |sjis-icon-au1  : OK : OK  | ----- |
 |sjis-icon-au2  : OK : OK  | ----- |
 |euc-icon-au    : OK : OK  | ----- |
 |euc-icon-au1   : OK : OK  | ----- |
 |euc-icon-au2   : OK : OK  | ----- |
 |jis-icon-au    : OK : OK  | ----- |
 |jis-icon-au1   : OK : OK  | ----- |
 |jis-icon-au2   : OK : OK  | ----- |
 |utf8-icon-au   : OK : OK  | ----- |
 |utf8-icon-au1  : OK : OK  | ----- |
 |utf8-icon-au2  : OK : OK  | ----- |
 +---------------+----+-----+-------+
 |ascii          : OK : --  | OK    |
 |binary         : OK : OK  | ----- |
 +---------------+----+-----+-------+
 (#): guessed when it has bom.

  自動認識優先順位
 1.  utf32 (#)
 2.  utf16 (#)
 3.  utf32-be
 4.  utf32-le
 5.  ascii
 6.  jis
 7.  sjis-jsky (pp)
 8.  euc
 9.  sjis
 10. sjis-jsky (xs)
 11. sjis-au
 12. sjis-imode
 13. sjis-doti
 14. utf8
 15. unknown

DESCRIPTION OF UNICODE MAPPING
Unicode とのマッピングは以下のように行われます．

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

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

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

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

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

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

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

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

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

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

AU  絵文字が存在する部分を，U+0FF500 - U+0FF6FF の領域にマッピングします．

PurePerl mode
   use Unicode::Japanese qw(PurePerl);

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

バグ
バグや要望は "bug-unicode-japanese at rt.cpan.org" 宛に 報告してください. 若しくは <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Unicode-Japanese>. にある web インターフェースからでもかまいません. そこから私に通知され, そして私が変更を行うことで報告頂いたバグの進捗は 自動的にあなたに伝わります.

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

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

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

サポート
このモジュールのドキュメントは perldoc コマンドで見ることが出来ます.

    perldoc Unicode::Japanese

また, 以下の場所でも見ることが出来ます:

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Unicode-Japanese>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Unicode-Japanese>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Unicode-Japanese>

•   Search CPAN

    <http://search.cpan.org/dist/Unicode-Japanese>

CREDITS
Thanks very much to:

NAKAYAMA Nao

SUGIURA Tatsuki & Debian JP Project

著作権及びライセンス
Copyright 2001-2008 SANO Taku (SAWATARI Mikage) and YAMASHINA Hio, all rights reserved.

このプログラムはフリーソフトウェアです。あなたは Perl と同じ ライセンスの 元で再配布及び変更を行うことが出来ます.