               Unicode 変換用拡張モジュール
                     version 0.6.1

			  吉田正人

- 概要

本モジュールは，ISO/IEC 10646 (Unicode) 文字列と 日本語文字
列との相互変換のための拡張モジュールです。

サポートしている エンコーディングは UCS-4, UTF-16, UTF-8,
EUC-JP, CP932 (Windows で使われている Shift_JIS の変種) です。

自動的にエンコーディングを認識する機能はありません。

バージョン 0.6.0 で extconf.rb のデフォルトオプションが変更さ
れています。また，動作変更変数がスレッドローカルになったの
で，マルチスレッド環境では以前とは動作が異なることがあります。


- インストール

Ruby-1.8 以降でしか動作確認されていません。Ruby-1.8.7，
1.9.2 での使用をおすすめします。

適当なディレクトリに uconv のソースを展開してください。

  gzip -dc < uconv-version.tar.gz | tar xvf -
  cd uconv

EUC-JP，CP932 用変換テーブルを持っているため，かなり大きいモ
ジュールになります。もし，EUC-JP または CP932 のどちらかしか
使わない場合は extconf.rb の --disable-euc か --disable-sjis
オプションを使うとサイズを小さくできます。
Windows の場合，--enable-win32api を指定すると CP932 の変換に
Win32 API を使うので，モジュールを小さくできます。

後は通常のモジュールインストールを行ってください。動的リン
クに対応している場合は以下の通りです。

  ruby extconf.rb
  make
  make install

gem を使ってい以下のようにインストールする事もできます。

  gem build uconv.gemspac
  gem install uconv -- --enable-compat-win32api


-- extconf.rb オプション

  * --enable-euc [default]
    --disable-euc
        EUC-JP サポートを有効化/無効化します。
        EUC-JP サポート無効化すると eucto*/*toeuc メソッドな
        どが使えなくなります。
  * --enable-sjis [default]
    --disable-sjis
        Shift_JIS サポートを有効化/無効化します。
        Shift_JIS サポート無効化すると sjisto*/*tosjis メソッ
        ドなどが使えなくなります。
  * --enable-win32api
    --disable-win32api [default]
        Shift_JIS 変換に Win32 API を使うかどうか指定します。
        指定できるのは Windows プラットフォームのみです。
        Shift_JIS 変換テーブルが不要になるのでモジュールサイ
        ズが小さくなります。
  * --enable-fullwidth-reverse-solidus [default]
    --disable-fullwidth-reverse-solidus
        EUC-JP 変換の際，全角の逆スラッシュ(0xa1c0)を
        U+005c (REVERSE SOLIDUS) に変換するか，
        U+2140 (FULLWIDTH REVERSE SOLIDUS) に変換するかを
        指定します。
        バージョン 0.6.0 でデフォルト値が enable (U+2140 に変
        換) に変更されました。
  * --enable-compat-win32api [default]
    --disable-compat-win32api
        Shift_JIS 変換の際，Win32 API の変換との互換性を高め
        るかどうか指定します。
        バージョン 0.6.0 でデフォルト値が enable に変更されま
        した。
  * --enable-thread-local [default]
    --disable-thread-local
        動作変更変数をスレッドローカルにするか，グローバルに
        するか指定します。
        disable を指定するとバージョン 0.6.0 以前と互換動作に
        なります。
  * --enable-utf-32 [default]
    --disable-utf-32
        UTF-32 に対応するかどうか指定します。
        enable ではコード値が U+10FFFF までに制限され，それ以
        上の文字は不正になります。
        disable を指定するとバージョン 0.6.0 以前と同様，
        UCS4/UTF-8 で 31 ビット値を使うことができます。


- 使い方

Ruby の make 時に静的にリンクしていない場合は，

  require "uconv"

としてから使用してください。


- モジュール関数

  u16swap (u2swap)，u4swap 以外は UTF-16, UTF-32 文字列はリト
  ルエンディアンでなくてはなりません。
  以前 UCS-2 を扱っていた関数は UTF-16 を扱うように変更され
  ました。

  関数によってはすべての ZERO WIDTH NO-BREAK SPACE (U+FEFF) を
  BYTE ORDER MARK (BOM) とみなして削除してしまいます。


             |               変換先
             |  EUC-JP    CP932     UTF-8    UTF-16    UTF-32
    ---------+------------------------------------------------
       EUC-JP|  \         -         euctou8  euctou16  -
    変 CP932 |  -         \         sjistou8 sjistou16 -
    換 UTF-8 |  u8toeuc   u8tosjis  \        u8tou16   u8tou4
    元 UTF-16|  u16toeuc  u16tosjis u16tou8  u16swap   u16tou4
       USC-4 |  -         -         u4tou8   u4tou16   u4swap


  utf16 = Uconv.u16swap(utf16)
  ucs2 = Uconv.u2swap(ucs2)
  utf16 = Uconv.u16swap!(utf16)
  ucs2 = Uconv.u2swap!(ucs2)
    UTF-16 文字列をバイトスワップします。リトルエンディアン
    の場合はビッグエンディアンに変換されます。
    ! の付いた関数は引き数の文字列を直接変更します。

  ucs4 = Uconv.u4swap(ucs4)
  ucs4 = Uconv.u4swap!(ucs4)
    UCS-4 文字列をバイトスワップします。1234 というバイトオー
    ダが 4321 に変換されます
    ! の付いた関数は引き数の文字列を直接変更します。

  utf16 = Uconv.u8tou16(utf8)
  ucs2 = Uconv.u8tou2(utf8)
    UTF-8 文字列を UTF-16 文字列に変換します。不正な UTF-8
    シーケンスは例外が発生します。UTF-16 で表現できる文字
    (U-00000000 〜 U-0010FFFF) 以外の文字が入っていると例外
    が発生します。

  utf8 = Uconv.u16tou8(utf16)
  utf8 = Uconv.u2tou8(ucs2)
    UTF-16 文字列を UTF-8 文字列に変換します。デフォルトでは 
    ZWNBSP (U+FEFF) は削除されます。不正なサロゲート・ペアは
    例外が発生します。

  utf8 = Uconv.u4tou8(ucs4)
    UCS-4 文字列を UTF-8 文字列に変換します。デフォルトでは 
    ZWNBSP (U+FEFF) は削除されます。

  ucs4 = Uconv.u8tou4(utf8)
    UTF-8 文字列を UCS-4 文字列に変換します。不正な UTF-8
    シーケンスは例外が発生します。

  utf16 = Uconv.u4tou16(ucs4)
    UCS-4 文字列を UTF-16 文字列に変換します。UTF-16 で表現
    できる文字 (U-00000000 〜 U-0010FFFF) 以外の文字が入って
    いると例外が発生します。

  ucs4 = Uconv.u16tou4(utf16)
    UTF-16 文字列を UCS-4 文字列に変換します。不正なサロゲー
    ト・ペアは例外が発生します。

  euc  = Uconv.u16toeuc(utf16)
  euc  = Uconv.u2toeuc(ucs2)
    UTF-16 文字列を EUC-JP 文字列に変換します。変換できない文
    字は Uconv.unknown_unicode_handler が未定義の場合，'?'
    になります。

  utf16 = Uconv.euctou16(euc)
  ucs2 = Uconv.euctou2(euc)
    EUC-JP 文字列を UTF-16 文字列に変換します。

  euc  = Uconv.u8toeuc(utf8)
    UTF-8 文字列を EUC-JP 文字列に変換します。
    u16toeuc(u8tou16(utf8)) と同等です。

  utf8 = Uconv.euctou8(euc)
    EUC-JP 文字列を UTF-8 文字列に変換します。
    u16tou8(euctou16(euc)) と同等です。

  sjis  = Uconv.u16tosjis(utf16)
  sjis  = Uconv.u2tosjis(ucs2)
    UTF-16 文字列を CP932 文字列に変換します。変換できない文
    字は Uconv.unknown_unicode_handler が未定義の場合，'?'
    になります。

  utf16 = Uconv.sjistou16(sjis)
  ucs2 = Uconv.sjistou2(sjis)
    CP932 文字列を UTF-16 文字列に変換します。

  sjis  = Uconv.u8tosjis(utf8)
    UTF-8 文字列を CP932 文字列に変換します。
    u16tosjis(u8tou16(utf8)) と同等です。

  utf8 = Uconv.sjistou8(sjis)
    CP932 文字列を UTF-8 文字列に変換します。
    u16tou8(sjistou16(sjis)) と同等です。

  Uconv.unknown_unicode_euc_handler = proc_obj
    UTF-16 または UTF-8 から EUC-JP に変換するとき，変換でき
    ない UCS 文字 があった場合に呼び出される Proc オブジェク
    トを指定します。

      proc_obj = proc {|unicode| euc_str }

    Proc オブジェクトには引数として Unocode の文字コードが整
    数で渡されます。戻値として文字列を返してください。初期状
    態では未定義 (nil) です。
    バージョン 0.6.0 以降で利用できます。
    モジュール関数形式のハンドラより優先されます。この変数に
    nil 以外の値が設定されている場合，モジュール関数形式のハ
    ンドラ unknown_unicode_euc_handler は呼び出されません。
    この変数はスレッドローカルです。

  Uconv.unknown_unicode_sjis_handler = proc_obj
    UTF-16 または UTF-8 から CP932 に変換するとき，変換できな
    い UCS 文字 があった場合に呼び出される Proc オブジェクト
    を指定します。


      proc_obj = proc {|unicode| sjis_str }

    Proc オブジェクトには引数として Unocode の文字コードが整
    数で渡されます。戻値として文字列を返してください。初期状
    態では未定義 (nil) です。
    バージョン 0.6.0 以降で利用できます。
    モジュール関数形式のハンドラより優先されます。この変数に
    nil 以外の値が設定されている場合，モジュール関数形式のハ
    ンドラ unknown_unicode_sjis_handler は呼び出されません。
    この変数はスレッドローカルです。

  Uconv.unknown_euc_handler = proc_obj
    EUC-JP から UTF-16 または UTF-8 に変換するときに，JIS X
    0208，JIS X 0212 で未定義の文字があった場合に呼び出される
    Proc オブジェクトを指定します。

      proc_obj = proc {|euc_str| unicode }

    Proc オブジェクトには引き数として，1 バイトから 3 バイトの
    EUC-JP の文字列が渡されます。戻値として Unicode 整数値を
    返してください。
    extconf.rb での --{enable|disable}-utf-32 の指定にかかわらず，
    Unicode 範囲外の値を返すと例外になります。
    初期状態では未定義です。
    バージョン 0.6.0 以降で利用できます。
    モジュール関数形式のハンドラより優先されます。この変数に
    nil 以外の値が設定されている場合，モジュール関数形式のハ
    ンドラ unknown_unicode_euc_handler は呼び出されません。
    この変数はスレッドローカルです。

  Uconv.unknown_sjis_handler = proc_obj
    CP932 から UTF-16 または UTF-8 に変換するときに，CP932
    で未定義の文字があった場合に呼び出される Proc オブジェクトを指定します。

      proc_obj = proc {|sjis_str| unicode }

    Proc オブジェクトには引き数として，1 バイトまたは 2 バイ
    トの CP932 の文字列が渡されます。戻値として Unicode 整数
    値を返してください。
    extconf.rb での --{enable|disable}-utf-32 の指定にかかわらず，
    Unicode 範囲外の値を返すと例外になります。
    初期状態では未定義です。
    バージョン 0.6.0 以降で利用できます。
    モジュール関数形式のハンドラより優先されます。この変数に
    nil 以外の値が設定されている場合，モジュール関数形式のハ
    ンドラ unknown_unicode_euc_handler は呼び出されません。
    この変数はスレッドローカルです。

  Uconv.euc_hook = proc_obj
    EUC-JP から UTF-16 または UTF-8 に変換するときに，一文字毎に呼び出される
    Proc オブジェクトを指定します。変換テーブルのカスタマイズを行うことができます。

      proc_obj = proc {|euc_str| unicode }

    Proc オブジェクトには引き数として，1 バイトから 3 バイトの
    EUC-JP の文字列が渡されます。戻値として nil または Unicode 整数値を
    返してください。nil を返した場合は通常の変換テーブルが参照されます。
    extconf.rb での --{enable|disable}-utf-32 の指定にかかわらず，
    Unicode 範囲外の値を返すと例外になります。
    初期状態では未定義です。

  Uconv.sjis_hook = proc_obj

  Uconv.unicode_euc_hook = proc_obj

  Uconv.unicode_sjis_hook = proc_obj

  euc = Uconv.unknown_unicode_handler(unicode)
    ** deprecated **

  euc = Uconv.unknown_unicode_euc_handler(unicode)
    UTF-16 または UTF-8 から EUC-JP に変換する
    とき，変換できない UCS 文字 があった場合に呼び出されるハ
    ンドラです。引数として Unocode の文字コードが整数で渡さ
    れます。戻値として文字列を返して下さい。初期状態では未定
    義です。

  sjis = Uconv.unknown_unicode_sjis_handler(unicode)
    UTF-16 または UTF-8 から CP932 に変換する
    とき，変換できない UCS 文字 があった場合に呼び出されるハ
    ンドラです。引数として Unocode の文字コードが整数で渡さ
    れます。戻値として文字列を返して下さい。初期状態では未定
    義です。

  unicode = Uconv.unknown_euc_handler(euc)
    EUC-JP から UTF-16 または UTF-8 に変換するときに，JIS X
    0208，JIS X 0212 で未定義の文字があった場合に呼び出される
    ハンドラです。引き数として，1 バイトから 3 バイトの
    EUC-JP の文字列が渡されます。戻値として Unicode 整数値を
    返してください。初期状態では未定義です。

  unicode = Uconv.unknown_sjis_handler(sjis)
    CP932 から UTF-16 または UTF-8 に変換するときに，CP932
    で未定義の文字があった場合に呼び出されるハンドラです。引
    き数として，1 バイトまたは 2 バイトの CP932 の文字列が渡
    されます。戻値として Unicode 整数値を返してください。初
    期状態では未定義です。

  unicode = Uconv.euc_hook(euc)
    EUC-JP から UTF-16 または UTF-8 に変換するときに，一文字毎に呼び出される
    フックです。変換テーブルのカスタマイズを行うことができます。
    引き数として，1 バイトから 3 バイトの
    EUC-JP の文字列が渡されます。戻値として nil または Unicode 整数値を
    返してください。nil を返した場合は通常の変換テーブルが参照されます。
    初期状態では未定義です。

  unicode = Uconv.sjis_hook(sjis)
    CP932 から UTF-16 または UTF-8 に変換するときに，一文字毎に呼び出される
    フックです。変換テーブルのカスタマイズを行うことができます。
    引き数として，1 バイトまたは 2 バイトの
    CP932 の文字列が渡されます。戻値として nil または Unicode 整数値を
    返してください。nil を返した場合は通常の変換テーブルが参照されます。
    初期状態では未定義です。

  euc = Uconv.unicode_euc_hook(unicode)
    UTF-16 または UTF-8 から EUC-JP に変換する
    とき，一文字毎に呼び出される
    フックです。変換テーブルのカスタマイズを行うことができます。
    引数として Unocode の文字コードが整数で渡さ
    れます。戻値として nil または文字列を返して下さい。
    nil を返した場合は通常の変換テーブルが参照されます。初期状態では未定
    義です。

  sjis = Uconv.unicode_sjis_hook(unicode)
    UTF-16 または UTF-8 から CP932 に変換する
    とき，一文字毎に呼び出される
    フックです。変換テーブルのカスタマイズを行うことができます。
    引数として Unocode の文字コードが整数で渡さ
    れます。戻値として nil または文字列を返して下さい。
    nil を返した場合は通常の変換テーブルが参照されます。初期状態では未定
    義です。

  flag = Uconv::eliminate_zwnbsp
  Uconv::eliminate_zwnbsp = flag
    ZWNBSP 文字 (U+FEFF) 削除フラグの参照，変更を行います。flag は 
    true か false を指定して下さい。初期値は true です。
    true の場合，u4tou8, u16tou8 関数で ZWNBSP 文字が削除さ
    れます。false の場合は ZWNBSP 文字は保存されます。
    バージョン 0.6.0 以降はスレッドローカルです。

  flag = Uconv::shortest
  Uconv::shortest = flag
    最短形式フラグの参照，変更を行います。flag は true か 
    false を指定して下さい。初期値は true です。true の場合，
    u8to* 関数で UTF-8 文字列が最短形式でない時に例外が発生
    します。
    バージョン 0.6.0 以降はスレッドローカルです。

  char = Uconv::replace_invalid
  Uconv::replace_invalid(char)
    UTF-8, UTF-16, UCS-4 文字列を変換するとき，不正なバイト
    列があった場合の置換文字を参照，指定します。nil または 0 を指定し
    た場合，不正なバイト列を変換しようとすると例外が発生しま
    す。nil または 0 以外の整数が指定された場合，不正なバイト列の代わ
    りに指定された Unicode コードポイントの文字を挿入します。初期値は 
    nil です。
    extconf.rb での --{enable|disable}-utf-32 の指定にかかわらず，
    Unicode 範囲外の値を設定すると例外になります。
    バージョン 0.6.0 以降はスレッドローカルです。


- 注意

以前のバージョンでは Windows の Unicode ファイルとの互換性を
考慮して，Unicode Inc. の変換テーブルに一部手を加えたものを
使っていましたが，version 0.4 では CP932 変換テーブルを別に
用意したので，EUC-JP 変換テーブルは Unicode Inc. の変換テー
ブルのままとしました。

以前のバージョンでは WAVE DASH [U+301C] と FULL WIDTH TILDE
[U+FF5E] を EUC-JP に変換する際，両方とも '〜' (EUC-JP:
A1C1) にしていましたが，version 0.4 では FULL WIDTH TILDE は
未定義文字になります。逆に EUC-JP の '〜' を UCS-2 または 
UTF-8 に変換する場合は U+FF5E に変換していましたが，U+301C 
に変換するようになりました。

CP932 変換テーブルを使う場合は WAVE DASH は未定義文字，
FULL WIDTH TILDE と '〜' (CP932: 8160) は相互変換します。

--enable-win32api を指定した場合，UCS -> CP932 の変換結果がテー
ブルを使った場合と異なる結果になることがあります。

バージョン 0.6.0 で --enable-fullwidth-reverse-solidus
および --enable-compat-win32api がデフォルトに変更されました。

バージョン 0.6.0 で動作変更変数がスレッドローカルになったた
め，マルチスレッド環境では以前とは動作が異なる場合があります。


- 権利

本拡張モジュールの著作権は吉田正人が保持します。

本拡張モジュールは，Ruby 本体のライセンスにしたがって利用す
ることができます。


- 作者

 吉田正人 <yoshidam@yoshidam.net>


- 履歴

 Aug 15, 2011 version 0.6.0 動作変更変数をグローバルからスレッドローカルに
                            変更
                            各種フックをスレッドローカルに指定できるようにした
                            --enable-fullwidth-reverse-solidus をデフォルトに
                            変更
 Jan  3, 2010 version 0.5.3 Ruby 1.9.1
 Aug 23, 2004 version 0.5.2 pre-conversion hook for Win32
 Aug 19, 2004 version 0.5.1 u2s, s2u, shift_jis-2004
 Aug 16, 2004 version 0.5.0  pre-conversion hook, euc-jis-2004, eucjp-open
 Jul 18, 2004 version 0.4.13 配列の範囲チェックを修正
 Mar 12, 2003 version 0.4.12 for ruby 1.8.0
 Oct  3, 2002 version 0.4.11 --enable-compat-win32api 追加
                             (CP932 テーブルを Win32API 互換にする)
 Sep  4, 2002 version 0.4.10 メモリリークの修正
 Feb 10, 2002 version 0.4.9 replace_invalid 追加
 Dec 10, 2001 version 0.4.8 汚染状態の感染に対応
 Nov 23, 2001 version 0.4.7 non-shortest form UTF-8 をチェック
                            Exception を Uconv::Error に変更
 Mar  4, 2001 version 0.4.6 s2u_conv2 を修正
                            USE_WIN32API 追加
 Jan 30, 2001 version 0.4.5 u2s_conv2 を修正
                            USC/CP932 変換テーブルを変更
 Apr 18, 2000 version 0.4.4 SJIS から UCS の変換バグを修正
 Mar 11, 2000 version 0.4.3 non-constant initializers の削除
 Nov 23, 1999 version 0.4.2 eliminate_zwnbsp フラグ追加
                            ustring ライブラリを最新版に差し替え
                            若干の高速化
 Nov 19, 1999 version 0.4.1 addUString のバグフィックス
 Nov  5, 1999 version 0.4.0 CP932 対応
 Mar 29, 1999 version 0.3.1 GC に害がある様なので xmalloc の使用をやめた
 Feb 22, 1999 version 0.3.0 UCS-4，UTF-16 サポート
 Jan 13, 1999 version 0.2.2 補助漢字サポート
 Aug 15, 1998 version 0.2.1 英語版 README ファイル追加
 Jul 24, 1998 version 0.2 変換できない文字があったときにハン
                          ドラを呼び出すように変更
                          メモリ管理方法を変更
 Jul  8, 1998 version 0.1 リリース
