home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / nlsnps.zip / nls.doc < prev    next >
Text File  |  1996-09-05  |  7KB  |  207 lines
  1.     OS/2 National Language Support functions Manual
  2.  
  3.  
  4. [Abstract]
  5.  
  6.   This package is intended for easy use of OS/2's National Language
  7. Support (NLS) functions.  All the functions defined in this package
  8. can be used only for C++, not C.  If you are a skilled C programmer,
  9. I think you can convert them into C programs.
  10.  
  11.   With these NLS functions, you can create international programs
  12. easier, especially DBCS language programs.  DBCS means Double Byte
  13. Code System, and one DBCS character consists of 2 bytes.  In DBCS,
  14. some of the characters consist only of one byte like English, and the
  15. rest consists of two bytes.  I am a Japanese, and the Japanese language
  16. is one of the DBCS languages.
  17.  
  18.   This package is totally free. You can use, modify, and distribute it
  19. freely without any permission.  I have renounced my copyright on it.
  20.  
  21.  
  22. [File Description]
  23.  
  24.   This package contains these files.  Some of these filenames are
  25. invalid on a FAT drive, and UNZIP will truncate them into 8.3
  26. filenames. For example, "nlsInitialize.cpp" will be renamed to
  27. "NLSINITI.CPP" on a FAT drive.
  28.  
  29. 1. nls.h
  30. 2. nlsCompare.cpp
  31. 3. nlsData.cpp
  32. 4. nlsIncludeDBCS.cpp
  33. 5. nlsInitialize.cpp
  34. 6. nlsSearch.cpp
  35. 7. nlsUpperString.cpp
  36.  
  37.   "nls.h" is the header file necessary to use the NLS functions.
  38. OS/2's basic header file "os2.h" must be included before "nls.h"
  39. is included, because "nls.h" contains OS/2's type definitions
  40. such as PUCHAR, UINT, etc.
  41.  
  42.   Other C++ source files must be compiled yourself.  I use Borland C++
  43. for OS/2, and I have not tested other compilers.
  44.  
  45.   To see the source files properly on the command line window,
  46. the window width of at least 100 columns is necessary.
  47.  
  48.  
  49. [Function Description]
  50.  
  51. 1. void nlsInitialize()
  52.   
  53.   This function initializes the character information necessary for
  54. all the other NLS functions in this package.  It is recommended to call
  55. this function once at the head of main().  Call this function again if
  56. the codepage of the process is changed.
  57.  
  58.  
  59. 2. PUCHAR nlsSearch(PUCHAR psz, UINT ui)
  60.  
  61.   This function searches the specified character in the string.  It is
  62. quite similar to the strchr function in C, but nlsSearch is aware of
  63. DBCS character sets.  The first argument psz is the pointer to the
  64. string, and the second argument ui is the character to be searched.
  65. If the character is found, a pointer to it is returned.  Otherwise
  66. NULL is returned.
  67.  
  68.   If you want to search a DBCS character, give it as a 16-bit number.
  69. Put the head byte in the highter 8 bits, and the tail byte in the lower
  70. 8 bits.  Note that Intel's microprocessors are little-endian
  71. so reading 16 bits at the address of the DBCS string will give the
  72. combination of the head byte in the lower 8 bits and the tail byte in
  73. the highter 8 bits.
  74.  
  75.   You can also pass the head byte of a DBCS character as the second
  76. argument.
  77.  
  78.  
  79. 3. PUCHAR nlsSearch(PUCHAR pb, UINT ui, UINT cbLength)
  80.  
  81.   Similar to the nlsSearch function with 2 arguments shown above,
  82. but with 3 arguments this function works for a memory area rather than
  83. a string.  It doesn't care for the null at the end of the string.
  84. The third argument cbLength determines the maximum length of bytes to
  85. be searched in, like the memchr function in C.
  86.  
  87.  
  88. 4. PUCHAR nlsSearchCollate(PUCHAR psz, UINT ui)
  89.  
  90.   Similar to the nlsSearch function, but this function ignores case
  91. like the strichr function in C.  This function uses the "collate value"
  92. which is returned by the DosQueryCollate API, so accented characters
  93. are also treated the same as an ordinary character.
  94.  
  95.  
  96. 5. PUCHAR nlsSearchCollate(PUCHAR pb, UINT ui, UINT cbLength)
  97.  
  98.   With 3 arguments this function works for a memory area.
  99.  
  100.  
  101. 6. PUCHAR nlsSearchLast(PUCHAR psz, UINT ui)
  102.  
  103.   This function works like nlsSearch, but returns a pointer to the last
  104. occurrence of the specified character.  It is similar to the strrchr
  105. function in C.  NULL will be returned if the string doesn't contain the
  106. specified character.
  107.  
  108.  
  109. 7. PUCHAR nlsSearchLast(PUCHAR pb, UINT ui, UINT cbLength)
  110.  
  111.   With 3 arguments this function works for a memory area.
  112.  
  113.  
  114. 8. PUCHAR nlsSearchCollateLast(PUCHAR psz, UINT ui)
  115.  
  116.   The nlsSearchLast function with the collate value.
  117.  
  118.  
  119. 9. PUCHAR nlsSearchCollateLast(PUCHAR pb, UINT ui, UINT cbLength)
  120.  
  121.   The nlsSearchLast function with the collate value.
  122.  
  123.  
  124. 10. BOOL nlsIncludeDBCS(PUCHAR psz)
  125.  
  126.   It returns TRUE if the string contains a DBCS character, FALSE if
  127. not.
  128.  
  129.  
  130. 11. int nlsCountChar(PUCHAR psz)
  131.  
  132.   This function counts the number of characters in the string.
  133. Remember that one DBCS character consists of two bytes. The strlen
  134. function in C returns the length of the string in bytes, not in
  135. characters.
  136.  
  137.  
  138. 12. int nlsCompare(PUCHAR psz1, PUCHAR psz2)
  139.  
  140.   This function compares two strings given as psz1 and psz2, and
  141. returns zero if the two strings are the same, a negative value if psz1
  142. is smaller in the alphabetical order, or a positive value if psz1 is
  143. bigger.  All comparison is made according to the collate values.
  144.  
  145.  
  146. 13. PUCHAR nlsUpperString(PUCHAR psz)
  147.  
  148.   It converts the string into upper case.  The string will be
  149. overwritten.  This function returns the first argument.
  150.  
  151.  
  152. 14. PUCHAR nlsLowerString(PUCHAR psz)
  153.  
  154.   It converts the string into lower case.  The string will be
  155. overwritten.  This function returns the first argument.
  156.  
  157.  
  158. 15. UCHAR nlsIsDBCS(UCHAR uc)
  159.  
  160.   It returns TRUE if the character is the head byte of a DBCS
  161. character.  In that case, the next byte must be the tail byte.
  162. The tail byte can take any value practically, so you cannot determine
  163. the tail byte of the DBCS character without knowing where the head
  164. byte is.  Be sure that nlsIsDBCS returns TRUE for some tail bytes,
  165. because they share the same codes even with the head bytes.  You must
  166. start from the head of the string to handle DBCS characters properly.
  167.  
  168.  
  169. 16. UCHAR nlsUpper(UCHAR uc)
  170.  
  171.   It gives the upper case of the character.  Do not use for the DBCS
  172. tail bytes.
  173.  
  174.  
  175. 17. UCHAR nlsLower(UCHAR uc)
  176.  
  177.   It gives the lower case of the character.  Do not use for the DBCS
  178. tail bytes.
  179.  
  180.  
  181. 18. UCHAR nlsCollate(UCHAR uc)
  182.  
  183.   It returns the collate value, which is useful for comparison.  Do not
  184. use for the DBCS tail bytes.
  185.  
  186.  
  187. 19. PUCHAR nlsNext(PUCHAR psz)
  188.  
  189.   This function returns psz + 1 if *psz is an ordinary character,
  190. or psz + 2 if *psz is the head byte of a DBCS character.
  191. (the tail byte is skipped)
  192.  
  193.  
  194.  
  195. [Other]
  196.  
  197.   I am not very good at using English, so if there is something
  198. unclear, please send me an email.  I will gladly reply to you to
  199. support your programming of international softwares.
  200.  
  201.   Thank you very much for downloading my software.
  202.  
  203.  
  204.   TAKASUGI Shinji (surname first - Japanese way)
  205.   member of Team OS/2 Japan
  206.   nps1970@ibm.net, jbd03575@niftyserve.or.jp
  207.