=encoding euc-jp

=head1 NAME

Unicode::Japanese::JA - Japanese Character Encoding Handler (ja-doc)

=head1 NAME (ja)

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

=head1 SYNOPSIS

 use Unicode::Japanese;
 use Unicode::Japanese qw(unijp);
 
 # convert utf8 -> sjis
 
 print Unicode::Japanese->new($str)->sjis;
 print unijp($str)->sjis; # same as avobe.
 
 # 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 DESCRIPTION

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

=head2 FEATURES

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

=over 2

=item *

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

=item *

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

=item *

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

=item *

携帯電話 (DoCoMo i-mode，ASTEL dot-i，J-PHONE J-Sky) の絵文字を
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/bytes を問いません.

=back


=head1 METHODS

=over 2

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

新しい Unicode::Japanese インスタンスを指定します．
パラメータを指定すると，set メソッドに渡されます．

=item unijp($str [, $icode [, $encode]])

Unicode::Janaese->new(...) と同義.

=item $s->set($str [, $icode [, $encode]])

=over 2

=item $str: 文字列

=item $icode: 文字コード指定．省略可．省略時は 'utf8'

=item $encode: 文字エンコード．省略可．

=back

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

文字コードを指定する場合は，'jis', 'sjis', 'euc', 'utf8',
'ucs2', 'ucs4', 'utf16', 'utf16-be', 'utf16-le',
'utf32', 'utf32-be', 'utf32-le', 'ascii', 'binary',
'sjis-imode', 'sjis-doti', 'sjis-jsky'.


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

文字エンコードには，'base64' のみ指定可能です．
base64 を指定した場合は，base64 デコードされてから
String クラスの文字列となります．

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

'auto' 時の文字コード自動判別は，getcode() メソッドにより
行われます．

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

=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

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

=item 6

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

=item 7

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

=item 8

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

=item 9

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

=item 10

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

=item 11

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

=item 12

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

=item 13

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

=back

(XS時)

=over 4

=item 1

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

=item 2

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

=item 3

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

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

=item 4

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

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

=item 5

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

=back

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

=over 2

=item *

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

=item *

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

=item *

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

=item *

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

=back

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

=item $str = $s->conv($ocode, $encode)

=over 2

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

=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絵文字(VERSION 0.15 では, imode2)の別名です.

=item $str = $s->sjis_imode2

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

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

=item $str = $s->sjis_imode1

$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_jsky2

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

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

=item $str = $s->sjis_jsky1

$str: sjis/j-sky絵文字 エンコーディング形式のバイト列
Page 1〜3 のみの絵文字を含みます.

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

=item @str = $s->strcut($len)

=over 2

=item $len: 分割する文字数

=item @STR: 文字列

=back

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

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

=item $len = $s->strlen

=over 2

=item $len: 文字列の表示幅

=back

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

=item $s->join_csv(@values);

=over 2

=item @values: データ配列

=back

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

=item @values = $s->split_csv;

=over 2

=item @values: データ配列

=back

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

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

=back


=head1 UNICODE MAPPING

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

=over 2

=item SJIS

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

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

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

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

=item EUC-JP/JIS

一度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 絵文字にマッピングするとき，
バイト目が同じ絵文字が連続している場合は，圧縮処理を自動的に行います．

=back

=head1 PurePerl mode

use Unicode::Japanese qw(PurePerl);
 と引数で与えることで, XSを使わないことを明示的に宣言できます.

=head1 BUGS

=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 AUTHOR INFORMATION

Copyright 2001-2004
SANO Taku (SAWATARI Mikage) and YAMASHINA Hio.
All right resreved.

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

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

=head1 CREDITS

Thanks very much to:

NAKAYAMA Nao

SUGIURA Tatsuki & Debian JP Project

=cut