File: //usr/local/lib64/perl5/Unicode/Japanese/JA.pod
=encoding utf-8
=head1 NAME
Unicode::Japanese::JA - 日本語文字コード変換
=head1 概要
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;
=head1 説明
Unicode::Japanese は，日本語の文字コードの相互変換を行うモジュールです．
=head2 機能
=over 2
=item *
Unicode::Japanese のインスタンスは，UTF-8 で文字列を保持します．
=item *
XS 使用/不使用を共にサポートしています．
XS 版はパフォーマンスが必要な場合に，
No-XS 版は手軽に使用したい場合に使用して下さい
(Japanese.pm をコピーするだけで動作します)．
=item *
全角半角変換，カタカナひらがな変換をサポートしています．
=item *
携帯電話 (DoCoMo i-mode，KDDI AU, Softbank Mobile, ASTEL dot-i) の絵文字を
Unicode 私用領域にマッピングすることで，DB 等で安全に扱うことができます．
=item *
異なる携帯電話同士で，同じイメージの絵文字は相互変換することが可能です．
=item *
SJIS は， MS-CP932 とみなして Unicode とマッピングを行います．
=item *
Unicode -> SJIS（及びEUC-JP/JIS） のマッピング時，SJIS で表現できない文字は
&#dddd; 形式に変換します． ただしUnicode私用領域におかれている絵文字は
'?'になります. また, 携帯電話向けの変換時には, すべての対応しない文字は'?'になります.
=item *
Perl-5.8.0 以降において, utf8 フラグの設定処理を行います.
utf-8 `バイト'列 の取得には utf8() メソッドを,
utf-8 `文字'列 の取得には getu() メソッドを使います.
get() メソッドは現時点では utf-8 `バイト'列 を返します
(将来的に変更される可能性もあります).
sjis(), jis(), utf8(), etc.. メソッドではバイト列を返します.
new, set, getcode メソッドの入力には, utf8-flaged/bytes を問いません.
=back
=head1 動作に必要なもの
=over 4
=item *
perl 5.10.x, 5.8.x, etc. (5.004 以降).
=item *
(なくてもOK)
C コンパイラ.
このモジュールは XS と Pure Perl 両方に対応しています.
C コンパイラがないときには, Unicode::Japanese は
Pure Perl モジュールとしてインストールされます.
=item *
(なくてもOK)
テスト用に Test.pm 及び Test::More.
=back
実行時に必須なモジュールはありません.
=head1 メソッド
=over 4
=item $s = Unicode::Japanese->new($str [, $icode [, $encode]])
新しい Unicode::Japanese インスタンスを指定します．
パラメータを指定すると，L</set> メソッドに渡されます．
=item $s = unijp($str [, $icode [, $encode]])
Unicode::Janaese->new(...) と同義.
=item $s->set($str [, $icode [, $encode]])
X<set>
=over 2
=item $str: 文字列
=item $icode: 文字コード指定．省略可．省略時は 'utf8'
=item $encode: バイナリ符号化方式．省略可．
=back
インスタンスに文字列をセットします．
文字コード指定を省略すると 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
(L<|/サポートされているエンコーディング>
も参照.)
文字コードを自動判別する場合は，'auto' を指定しなくてはいけません．
'auto' 時の文字コード自動判別は，getcode() メソッドにより
行われます．
バイナリ符号化方式には，'base64' のみ指定可能です．
base64 を指定した場合は，base64 デコードされてから
Unicode::Japanese クラスの文字列となります．
渡された文字列を変更せずそのまま格納して欲しい場合には，文字コードとして
'binary' を指定します．
sjis-imode，sjis-doti，の場合，文字列中の &#dddd; は
絵文字に変換されます．
文字コードは領域が重なっている場合があるため，
自動判別は確実ではありません．
sjis, utf8 の両方に解釈できる文字列の場合は，sjis，
sjis-au，sjis-doti の両方に解釈できる文字列の場合は，sjis-au，
を返します．
=item $str = $s->get
=over 2
=item $str: 文字列(UTF-8)
=back
文字列を UTF-8 コードで取り出します．
現在は `バイト' 列 を返しますが, 将来的に変更される可能性もあります.
バイト列が必要なら utf8() メソッドを,
文字列が必要なら getu() メソッドを使うことをオススメします.
=item $str = $s->getu
=over 2
=item $str: 文字列(UTF-8)
=back
文字列を UTF-8 コードで取り出します．
Perl-5.8.0 以降においては, utf-8 フラグのついた utf-8 文字列として
返します.
=item $code = $s->getcode($str)
=over 2
=item $str: 文字列
=item $code: 文字コードを表す文字列
=back
渡された文字列(I<$str>)の文字コードを自動判別します．
この関数では, 例外的に, インスタンスに保持されている
文字列のコードを判別するのではないことに注意してください．
文字コード自動判別時は，以下のアルゴリズムにより判定が行われます．
(PurePerl時)
=over 4
=item 1
UTF-32 の BOM があれば，utf32 と判定します．
=item 2
UTF-16 の BOM があれば，utf16 と判定します．
=item 3
UTF-32BE として正しい形式なら，utf32-be と判定します．
=item 4
UTF-32LE として正しい形式なら，utf32-le と判定します．
=item 5
ESC 文字 または 8 ビット目の立っている文字が含まれていなければ，ascii と判定しま
す。ESC を除いた ASCII 制御文字 (0x00-0x1F 及び 0x7F) は ascii の範囲内と見做しま
す。
=item 6
JISエスケープシーケンスが含まれていれば，jis と判定します．
=item 7
J-PHONE の絵文字が含まれていれば，sjis-jsky と判別します．
=item 8
EUC-JP コードとして正しい形式なら，euc と判定します．
=item 9
SJIS コードとして正しい形式なら，sjis と判定します．
=item 10
SJIS コードと au の絵文字として正しい形式なら，sjis-au と判定します．
=item 11
SJIS と i-mode の絵文字として正しい形式なら，sjis-imode と判別します．
=item 12
SJIS と dot-i の絵文字として正しい形式なら，sjis-doti と判別します．
=item 13
UTF-8 として正しい形式なら，utf8 と判定します．
=item 14
いずれにも当てはまらない場合，unknown と判定します．
=back
(XS時)
=over 4
=item 1
UTF-32 の BOM があれば，utf32 と判定します．
=item 2
UTF-16 の BOM があれば，utf16 と判定します．
=item 3
以下のコードについて, 正しい文字コードであることを状態遷移を用いて調べます.
ascii / euc / sjis / jis / utf8 / utf32-be / utf32-le / sjis-jsky /
sjis-imode / sjis-au / sjis-doti
=item 4
最後まで正しかったものの中から, 以下の優先順で１つをえらんで, それと判定します.
utf32-be / utf32-le / ascii / jis / euc / sjis / sjis-jsky / sjis-imode /
sjis-au / sjis-doti / utf8
=item 5
いずれにも当てはまらない場合，unknown と判定します．
=back
以上のアルゴリズムのため，以下の点に注意してください．
=over 2
=item *
UTF-8 文字列でも，SJISコードと見なされる可能性があります．
=item *
UCS2 の自動判別はできません．
=item *
UTF-16 は BOM がある場合のみ自動認識します．
=item *
携帯絵文字は，バイナリで直接絵文字がある場合のみ認識できます．
&#dddd; 形式で記述されている場合は，携帯絵文字の自動判別は行われません．
=back
XSとPurePerlでは, 判別のアルゴリズムに違いがあるため, 異なる結果になる可能性があります.
特に, エスケープ文字を含んでいるsjisの場合, PurePerlではsjisと認識しますが
XSでは認識しません. これはsjis-jskyと区別できなくなるためです. また, この
作用による誤認識を防ぐため, euc-jpにおいても, 同様にエスケープ文字を受け付けなく
なっています.
=item $code = $s->getcodelist($str)
=over 2
=item $str: 文字列
=item $code: 文字コードを表す文字列
=back
渡された文字列(I<$str>)の文字コードを自動判別します．
getcode とは違い, すべての受理可能な文字コードの
一覧を返します.
=item $str = $s->conv($ocode, $encode)
=over 2
=item $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
(L<|/サポートされているエンコーディング>
も参照.)
携帯向け文字コードのうち，末尾に数字がついているものは，数字が大きいほど
大きな絵文字セット（最新機種の絵文字セット）を表しています．
数字なしのものは，もっとも数字が大きい文字コードと同一です．
=item $encode: バイナリ符号化方式．省略可．
=item $str: 文字列
=back
文字列を指定した文字コードに変換してから取り出します．
文字エンコードには，'base64' のみ指定可能です．
base64 を指定した場合は，base64 エンコードされた
文字列が返されます．
perl-5.8.0 以降において, 出力は utf-8 フラグを持たないバイト列になります.
=item $s->tag2bin
文字列中に含まれる &#dddd; 形式の文字列を，それが表す文字自体に置き換えます．
=item $s->z2h
全角を半角に変換します．
=item $s->h2z
半角を全角に変換します．
=item $s->hira2kata
ひらがなをカタカナに変換します．
=item $s->kata2hira
カタカナをひらがなに変換します．
=item $str = $s->jis
$str: JIS エンコーディング形式のバイト列
文字列を JIS（ISO-2022-JP） コードで取り出します．
=item $str = $s->euc
$str: euc-jp エンコーディング形式のバイト列
文字列を EUC-JP コードで取り出します．
=item $str = $s->utf8
$str: utf-8 エンコーディング形式のバイト列
文字列を UTF-8 コードで取り出します．
perl-5.8.0 以降においても, バイト列を返します.
=item $str = $s->ucs2
$str: ucs2 エンコーディング形式のバイト列
文字列を UCS2 コードで取り出します．
=item $str = $s->ucs4
$str: ucs4 エンコーディング形式のバイト列
文字列を UCS4 コードで取り出します．
=item $str = $s->utf16
$str: ucs-16 エンコーディング形式のバイト列
文字列を UTF-16 コードで取り出します．
BOMは付きません．
ビックエンディアン形式で返されます．
=item $str = $s->sjis
$str: sjis エンコーディング形式のバイト列
文字列を SJIS（MS-CP932） コードで取り出します．
=item $str = $s->sjis_imode
$str: sjis/imode絵文字 エンコーディング形式のバイト列
文字列を i-mode 端末向けの SJIS コードで取り出します．
最新のimode絵文字の別名です.
=item $str = $s->sjis_imode1
$str: sjis/imode 絵文字 エンコーディング形式のバイト列
文字列を i-mode 端末向けの SJIS コードで取り出します．
基本絵文字だけから成ります.
=item $str = $s->sjis_imode2
$str: sjis/imode 絵文字 エンコーディング形式のバイト列
文字列を i-mode 端末向けの SJIS コードで取り出します．
基本絵文字, 拡張絵文字を含みます.
=item $str = $s->sjis_doti
$str: sjis/dot-i 絵文字 エンコーディング形式のバイト列
文字列を dot-i 端末向けの SJIS コードで取り出します．
=item $str = $s->sjis_jsky
$str: sjis/j-sky 絵文字 エンコーディング形式のバイト列
文字列を j-sky 端末向けの SJIS コードで取り出します．
最新のj-sky絵文字(VERSION 0.15 では, jsky2)の別名です.
=item $str = $s->sjis_jsky1
$str: sjis/j-sky 絵文字 エンコーディング形式のバイト列
文字列を j-sky 端末向けの SJIS コードで取り出します．
Page 1～3 のみの絵文字を含みます.
=item $str = $s->sjis_jsky
$str: sjis/j-sky 絵文字 エンコーディング形式のバイト列
文字列を j-sky 端末向けの SJIS コードで取り出します．
Page 1～6 の絵文字を含みます.
=item $str = $s->sjis_icon_au
$str: sjis/AU iconタグ エンコーディング形式のバイト列
文字列を AU 端末向けの SJIS コードで取り出します．
=item $str_arrayref = $s->strcut($len)
=over 2
=item $len: 分割する文字数(全角相当)
=item $str_arrayref: 文字列
=back
I<$len>で指定された文字数(全角)以下の文字列の配列に分割します．
配列の各要素は, utf-8 フラグを持ったutf-8文字列です.
=item $len = $s->strlen
$len: 文字列の表示幅
UTF-8 文字に対して length() を使うと全角文字は１文字あたり長さ 3 になってしまいますが，
このメソッドを使用すると，従来の SJIS のように，全角文字は１文字あたり長さ 2 を返します．
=item $s->join_csv(@values);
@values: データ配列
配列を CSV 文字列に変換し，インスタンスに格納します．
文字列の最後には改行("\n")が追加されます．
=item @values = $s->split_csv;
@values: データ配列
インスタンスに格納されている文字列を CSV と見なし，配列に分割します．
文字列の最後にある改行("\n")は取り除かれてから分割されます．
入力が binary でなければ utf-8 文字列を返します.
binary だったときはバイト列を返します.
=back
=head1 サポートされているエンコーディング
+---------------+----+-----+-------+
|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.
=head2 自動認識優先順位
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
=head1 DESCRIPTION OF UNICODE MAPPING
Unicode とのマッピングは以下のように行われます．
=over 2
=item Shift_JIS
MS-CP932 として Unicode へマッピングを行います．
マッピングテーブルは以下のURLのものを使用しています．
L<< ftp://ftp.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/CP932.TXT >>
Unicode から SJIS へマッピングする場合に，表現できない文字があると，
その文字は &#dddd; 形式に変換します．
ただし，携帯絵文字は「?」に変換されます．
また，携帯向けの SJIS へ変換するときは，全ての表現できない文字は「?」に変換されます．
=item EUC-JP/ISO-2022-JP
一度SJISコードに変換してから，Unicode へマッピングします．
このとき，SJIS で表現できない文字が含まれていた場合，
その文字は正しくマッピングできません．
=item DoCoMo i-mode
F800 - F9FF の領域のうち絵文字が存在する部分を，U+0FF800 - U+0FF9FF
の領域にマッピングします．
=item ASTEL dot-i
F000 - F4FF の領域のうち絵文字が存在する部分を，U+0FF000 - U+0FF4FF
の領域にマッピングします．
=item 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バイト目が同一である絵文字が連続している場合は，圧縮処理を自動的に行います．
=item AU
絵文字が存在する部分を，U+0FF500 - U+0FF6FF の領域にマッピングします．
=back
=head1 PurePerl mode
use Unicode::Japanese qw(PurePerl);
use 時の引数に C<'PurePerl'> を与えることで,
XSを使わないことを明示的に宣言できます.
=head1 バグ
バグや要望は C<bug-unicode-japanese at rt.cpan.org> 宛に
報告してください. 若しくは
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Unicode-Japanese>.
にある web インターフェースからでもかまいません.
そこから私に通知され, そして私が変更を行うことで報告頂いたバグの進捗は
自動的にあなたに伝わります.
=over 2
=item *
EUC-JP，JIS コードは，SJIS に変換されてから UTF-8 へ変換されるため，
SJIS で表現できない文字列は正しく変換することはできません．
=item *
XSを使用している場合，EUC-JP，SJIS(絵文字含む)コードの文字列中に
\e が含まれると，EUC-JP，SJIS コードの判定に失敗し，
正しく自動判別や変換を行うことが出来ません．
=item *
Japanese.pm はファイル後半にバイナリを含むため，FTP の ASCII モードで
転送するとファイルが壊れます．
=back
=head1 サポート
このモジュールのドキュメントは perldoc コマンドで見ることが出来ます.
perldoc Unicode::Japanese
また, 以下の場所でも見ることが出来ます:
=over 4
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/Unicode-Japanese>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/Unicode-Japanese>
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Unicode-Japanese>
=item * Search CPAN
L<http://search.cpan.org/dist/Unicode-Japanese>
=back
=head1 CREDITS
Thanks very much to:
NAKAYAMA Nao
SUGIURA Tatsuki & Debian JP Project
=head1 著作権及びライセンス
Copyright 2001-2008
SANO Taku (SAWATARI Mikage) and YAMASHINA Hio,
all rights reserved.
このプログラムはフリーソフトウェアです。あなたは Perl と同じ
ライセンスの 元で再配布及び変更を行うことが出来ます.