This section contains some useful notes about managing the input and output buffers used by the codepage conversion functions.

Determining Buffer Size

When creating the output buffers for the conversion functions, care must be taken to ensure that the buffer is large enough for the entire converted output, plus a terminating null character.

• When converting to Unicode, most multi-byte characters will map to a single UniChar. Therefore, it is generally safe to use an output buffer of the same length as the input buffer.

• When converting from Unicode, you should take into account the possible number of bytes per character which the specific target codepage allows. While single-byte (SBCS) codepages have a maximum of one byte per character, multi-byte (MBCS) encodings may use up to four bytes to represent a single character:
  • The common MBCS-PC codepages have a maximum of two bytes per character.
  • Most EUC-based codepages use up to three byte per character. However, EUC-TW (codepage 964) uses up to four bytes per character.
  • Both the UTF-8 (1208) and UPF-8 (1207) codepages use up to three bytes per character.
  Consequently, you should first identify the codepage(s) to which your buffer may be used for conversion. Identify the maximum number of bytes that could be used for any of those codepages, and set your buffer size accordingly.

  If you wish to use your buffer for conversion to any arbitrary codepage, the best practise is to use a buffer size of four times the length of the input Unicode string (plus one byte for the terminating null).

Using Length Parameters

The two different sets of conversion functions differ in how they treat their respective buffer length parameters.

• With the UniStr*Ucs functions, the last parameter indicates the total size of the output buffer. Consequently, it must include space for the terminating null character.

• By contrast, the length parameters used by the UniUconv*Ucs functions indicate numbers of character positions in the input and output buffers. Somewhat confusingly, therefore, they should not include the terminating null character (and must therefore be set to one less than the total length of the buffer).