home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ruby164.zip / rbemx164.zip / ruby / share / doc / uconv-0.4.6 / README next >
Text File  |  2001-03-15  |  7KB  |  217 lines
  1.          Unicode Conversion Module for Ruby
  2.             version 0.4.6
  3.  
  4.                Yoshida Masato
  5.  
  6.  
  7.  
  8. - Introduction
  9.  
  10. This is the module to convert ISO/IEC 10646 (Unicode) string
  11. and Japanese string each other.
  12.  
  13. Supported character encodings are UCS-4, UTF-16, UTF-8,
  14. EUC-JP, CP932 (a variant of Shift_JIS for Japanese Windows).
  15.  
  16. This cannot detect character encoding automatically.
  17.  
  18. Note that EUC-JP conversion table has been changed.
  19.  
  20.  
  21. - Install
  22.  
  23. This can work with ruby-1.4. I recommend you to use
  24. ruby-1.4.2 or later.
  25.  
  26. Extract this package.
  27.  
  28.   cd ext
  29.   gzip -dc < uconv-0.2.tar.gz | tar xvf -
  30.   cd uconv
  31.  
  32. If you do not need EUC-JP or CP932 conversion, you can
  33. undefine USE_EUC or USE_SJIS to reduce the size of this
  34. module. On Windows System, you can define USE_WIN32API
  35. to use Win32 encoding conversion API.
  36.  
  37. And make and install usually.
  38. For example, when Ruby supports dynamic linking on your OS,
  39.  
  40.   ruby extconf.rb
  41.   make
  42.   make install
  43.  
  44.  
  45. - Usage
  46.  
  47. If you do not link this module with Ruby statically, 
  48.  
  49.   require "uconv"
  50.  
  51. before using.
  52.  
  53.  
  54. - Module Function
  55.  
  56.   UTF-16 and UCS-4 strings must be little-endian without
  57.   using u16swap (u2swap) and u4swap.
  58.  
  59.   The functions that had treated USC-2 now can treat UTF-16.
  60.  
  61.   All ZERO WIDTH NO-BREAK SPACE (U+FEFF) are regarded as
  62.   BYTE ORDER MARK (BOM) and deleted in some functions.
  63.  
  64.   The function matrix is the following.
  65.  
  66.              |               dest
  67.              |  EUC-JP    CP932     UTF-8    UTF-16    UCS-4
  68.     ---------+------------------------------------------------
  69.        EUC-JP|  \         -         euctou8  euctou16  -
  70.     s  CP932 |  -         \         sjistou8 sjistou16 -
  71.     r  UTF-8 |  u8toeuc   u8tosjis  \        u8tou16   u8tou4
  72.     c  UTF-16|  u16toeuc  u16tosjis u16tou8  u16swap   u16tou4
  73.        USC-4 |  -         -         u4tou8   u4tou16   u4swap
  74.  
  75.  
  76.   utf16 = Uconv.u16swap(utf16)
  77.   ucs2 = Uconv.u2swap(ucs2)
  78.   utf16 = Uconv.u16swap!(utf16)
  79.   ucs2 = Uconv.u2swap!(ucs2)
  80.     Byte-swaps a UTF-16 string. The little-endian string is
  81.     converted to the big-endian string.
  82.     Bang functions change the the parameter string directly.
  83.  
  84.   ucs4 = Uconv.u4swap(ucs4)
  85.   ucs4 = Uconv.u4swap!(ucs4)
  86.     Byte-swaps a UCS-4 string. The 1234-ordered string is
  87.     converted into the 4321-ordered string.
  88.     Bang function changes the the parameter string directly.
  89.  
  90.   utf16 = Uconv.u8tou16(utf8)
  91.   ucs2 = Uconv.u8tou2(utf8)
  92.     Converts a UTF-8 string into an UTF-16 string. The
  93.     Illegal UTF-8 sequence raises the exception. The
  94.     character except for a range from U-00000000 to
  95.     U-0010FFFF also raises the exception.
  96.  
  97.   utf8 = Uconv.u16tou8(utf16)
  98.   utf8 = Uconv.u2tou8(ucs2)
  99.     Converts a UTF-16 string into a UTF-8 string. ZWNBSPs
  100.     (U+FEFF) are deleted in default. Illegal surrogate pair
  101.     raises the exception.
  102.  
  103.   utf8 = Uconv.u4tou8(ucs4)
  104.     Converts a UTF-16 string into a UTF-8 string. ZWNBSPs
  105.     (U+FEFF) are deleted in default.
  106.  
  107.   ucs4 = Uconv.u8tou4(utf8)
  108.     Converts a UTF-8 string into an UCS-4 string. The Illegal
  109.     UTF-8 sequence raises the exception. 
  110.  
  111.   utf16 = Uconv.u4tou16(ucs4)
  112.     Converts a UTF-8 string into an UTF-16 string. The
  113.     character except for a range from U-00000000 to
  114.     U-0010FFFF also raises the exception.
  115.  
  116.   ucs = Uconv.u16tou4(utf16)
  117.     Converts a UTF-16 string into a UTF-8 string. Illegal
  118.     surrogate pair raises the exception.
  119.  
  120.   euc  = Uconv.u16toeuc(utf16)
  121.   euc  = Uconv.u2toeuc(ucs2)
  122.     Converts a UTF-16 string into an EUC-JP string. If
  123.     "Uconv.unknown_unicode_handler" function is not defined,
  124.     the character that cannot be converted is converted into '?'.
  125.  
  126.   utf16 = Uconv.euctou16(euc)
  127.   ucs2 = Uconv.euctou2(euc)
  128.     Converts an EUC-JP string into a UTF-16 string.
  129.  
  130.   euc  = Uconv.u8toeuc(utf8)
  131.     Converts a UTF-8 string into an EUC-JP string. This is
  132.     equal to u16toeuc(u8tou16(utf8)).
  133.  
  134.   utf8 = Uconv.euctou8(euc)
  135.     Converts an EUC-JP string into a UTF-8 string. This is
  136.     equal to u16tou8(euctou16(euc)).
  137.  
  138.   sjis  = Uconv.u16tosjis(utf16)
  139.   sjis  = Uconv.u2tosjis(ucs2)
  140.     Converts a UTF-16 string into an CP932 string. If
  141.     "Uconv.unknown_unicode_handler" function is not defined,
  142.     the character that cannot be converted is converted into '?'.
  143.  
  144.   utf16 = Uconv.sjistou16(sjis)
  145.   ucs2 = Uconv.sjistou2(sjis)
  146.     Converts an CP932 string into a UTF-16 string. 
  147.  
  148.   sjis  = Uconv.u8tosjis(utf8)
  149.     Converts a UTF-8 string into an CP932 string. This is
  150.     equal to u16tosjis(u8tou16(utf8)).
  151.  
  152.   utf8 = Uconv.sjistou8(sjis)
  153.     Converts an CP932 string into a UTF-8 string. This is
  154.     equal to u16tou8(euctou16(sjis)).
  155.  
  156.   euc = Uconv.unknown_unicode_handler(unicode)
  157.     When a UTF-16 or a UTF-8 string is converted into an EUC-JP
  158.     or CP932 string, this function is called if the
  159.     character that cannot converted is detected. The
  160.     parameter is a Unicode character code in integer. You
  161.     must return a string. This function is not defined
  162.     initially.
  163.  
  164.   unicode = Uconv.unknown_euc_handler(euc)
  165.     When an EUC-JP string is converted into a UTF-16 or UTF-8
  166.     string, this function was called if the undefined
  167.     character by JIS X 0208 or JIS X 0212 is detected. 
  168.     The parameter is a EUC-JP string (2bytes or 3bytes).
  169.     You must return a Unicode value in integer (0-65535).
  170.  
  171.   unicode = Uconv.unknown_sjis_handler(euc)
  172.     When an CP932 string is converted into a UTF-16 or UTF-8
  173.     string, this function was called if the undefined
  174.     character by CP932 is detected. The parameter is a
  175.     CP932 string (1byte or 2bytes).
  176.     You must return a Unicode value in integer (0-65535).
  177.  
  178.   flag = Uconv::eliminate_zwnbsp
  179.   Uconv::eliminate_zwnbsp = flag
  180.     Gets/sets ZWNBSP elimination flag. Flag must be true or false.
  181.     It is true in the initial state. If true, u4tou8 and
  182.     u16tou8 functions eliminate all ZWNBSPs, if false, they
  183.     preserve all ZWNBSPs.
  184.  
  185.  
  186. - Copying
  187.  
  188. This extension module is copyrighted free software by
  189. Yoshida Masato.
  190.  
  191. You can redistribute it and/or modify it under the same term
  192. as Ruby.
  193.  
  194.  
  195. - Author
  196.  
  197.  Yoshida Masato <yoshidam@inse.co.jp>, <yoshidam@yoshidam.net>
  198.  
  199.  
  200. - History
  201.  
  202.  Mar  4, 2001 version 0.4.6 fixes s2u_conv
  203.                             and add USE_WIN32API
  204.  Jan 30, 2001 version 0.4.5 fixes u2s_conv
  205.                             and changes USC/CP932 conversion table
  206.  Apr 18, 2000 version 0.4.4 SJIS to UCS conversion bug
  207.  Mar 11, 2000 version 0.4.3 Eliminates non-constant initializers
  208.  Nov 23, 1999 version 0.4.2 Appends eliminate_zwnbsp flag
  209.                             Replace ustring library
  210.  Nov  5, 1999 version 0.4.0 Supports CP932
  211.  Mar 29, 1999 version 0.3.1 Removes xmallocs
  212.  Feb 22, 1999 version 0.3.0 Supports UCS-4 and UTF-16
  213.  Jan 13, 1999 version 0.2.2 Supports Japanese supplement characters
  214.  Aug 15, 1998 version 0.2.1 Appends this README file
  215.  Jul 24, 1998 version 0.2
  216.  Jul  8, 1998 version 0.1
  217.