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

			  吉田正人

- 概要

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

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

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

EUC-JP と Unicode との間の変換テーブルが version 0.3.x まで
とは変更されているのでご注意下さい。


- インストール

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

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

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

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

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

  ruby extconf.rb
  make
  make install


- 使い方

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

  require "uconv"

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


- モジュール関数

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

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


             |               変換先
             |  EUC-JP    CP932     UTF-8    UTF-16    UCS-4
    ---------+------------------------------------------------
       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)) と同等です。

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

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

  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 の文字列が渡されます。戻値として 31 ビットの整数を
    返してください。初期状態では未定義です。

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

  unicode = Uconv.euc_hook(euc)

  unicode = Uconv.sjis_hook(sjis)

  euc = Uconv.unicode_euc_hook(unicode)

  sjis = Uconv.unicode_sjis_hook(unicode)

  flag = Uconv::eliminate_zwnbsp
  Uconv::eliminate_zwnbsp = flag
    ZWNBSP 文字削除フラグの参照，変更を行います。flag は 
    true か false を指定して下さい。初期値は true です。
    true の場合，u4tou8, u16tou8 関数で ZWNBSP 文字が削除さ
    れます。false の場合は ZWNBSP 文字は保存されます。

  flag = Uconv::shortest
  Uconv::shortest = flag
    最短形式フラグの参照，変更を行います。flag は true か 
    false を指定して下さい。初期値は true です。true の場合，
    u8to* 関数で UTF-8 文字列が最短形式でない時に例外が発生
    します。

  char = Uconv::replace_invalid
  Uconv::replace_invalid(char)
    UTF-8, UTF-16, UCS-4 文字列を変換するとき，不正なバイト
    列があった場合の置換文字を参照，指定します。nil を指定し
    た場合，不正なバイト列を変換しようとすると例外が発生しま
    す。nil 以外の整数が指定された場合，不正なバイト列の代わ
    りに指定されたコードポイントの文字を挿入します。初期値は 
    nil です。


- 注意

以前のバージョンでは 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) は相互変換します。

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


- 権利

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

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


- 作者

 吉田正人 <yoshidam@yoshidam.net>


- 履歴

 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 リリース
