Multibyte Macros and Functions in toolbox.h
The macros and functions in toolbox.h that are listed in the following table offer generally useful multibyte-aware functionality that is comparable to the string handling functions in the ANSI C library and pointer arithmetic, such as *s++. In these macro and function descriptions, p refers to a pointer to the beginning of the string, and s refers to the character pointer that you want to move.
| Function/Macro | Description |
|---|---|
| OnMBSystem | Returns TRUE if the program is running on a multibyte system. |
| CmbIsSingleC | Checks if the given 16-bit character fits into a single byte. |
| CmbGetNumBytesInChar | Returns the number of bytes required to store the given character. |
| CmbIsLeadByte | Checks if the given byte is a valid lead byte. Call CmbIsLeadByte only if you know that the byte starts on a character boundary; that is, the byte cannot be a trail byte. |
| CmbCharCodeLeadByte | Returns the lead byte of a dual-byte character. |
| CmbCharCodeTrailByte | Returns the trail byte of a dual-byte character. |
| CmbStrByteType | Returns the type of the byte at a given offset within a string, taking into account the bytes before the given byte. If you know that p[offset] is not in the middle of a dual-byte character, you can call CmbIsLeadByte instead. Possible return values are CMB_SINGLE_BYTE, CMB_LEAD_BYTE, CMB_TRAIL_BYTE, and CMB_ILLEGAL_BYTE. |
| CmbStrDec | Changes s by moving it back by one character. Analogous to --s. |
| CmbStrInc | Changes s by moving it forward by one character. Analogous to ++s. |
| CmbStrPrev | Returns a pointer to the previous character in the string. Analogous to s-1. |
| CmbStrNext | Returns a pointer to the next character in the string. Analogous to s+1. |
| CmbGetC | Retrieves the character at the given pointer. Analogous to *s. |
| CmbSetC | Sets the character at the given pointer. CmbSetC overwrites any values at the given location and does not properly insert a dual-byte character into the middle of a string. Analogous to *s = c. |
| CmbGetCInc | First retrieves the character at the given position and then advances the pointer to the next character. Analogous to *s++. |
| CmbGetCNdxInc | First retrieves the character at the given position and then advances the index to the next character. Analogous to s[i++]. |
| CmbSetCInc | First sets the character at the given position and then advances the pointer to the next character. The newly set character is returned. Analogous to *s++ = c. |
| CmbSetCNdxInc | First sets the character at the given position and then advances the index to the next character. The newly set character is returned. Analogous to s[i++] = c. |
| CmbIncGetC | First advances the given pointer to the next character and then returns that character. Analogous to *++s. |
| CmbIncSetC | First advances the given pointer to the next character and then sets and returns the new character. Analogous to *++s = c. |
| CmbFirstByteOfChar | Returns the first byte of the given single or dual-byte character. |
| CmbNumChars | Returns the number of characters in the given string. |
| CmbStrEq | Compares the two given strings. Returns TRUE if they are equal. |
| CmbStrEqI | Compares the two given strings. The comparison is not case-sensitive. Returns TRUE if they are equal. |
| CmbStrEqN | Compares the first n bytes of the two given strings. Returns TRUE if they are equal. |
| CmbStrEqNI | Compares the first n bytes of the two given strings. The comparison is not case-sensitive. Returns TRUE if they are equal. |
| CmbStrCmp | Equivalent to _mbscmp. |
| CmbStrNCmp | Equivalent to _mbsnbcmp. |
| CmbStrICmp | Equivalent to _mbsicmp. |
| CmbStrNICmp | Equivalent to _mbsnbicmp. |
| CmbStrCat | Equivalent to strcat. |
| CmbStrNCat | Equivalent to _mbsnbcat. |
| CmbStrCpy | Equivalent to strcpy. |
| CmbStrNCpy | Equivalent to _mbsnbcpy. |
| CmbStrSpn | Equivalent to _mbsspn. |
| CmbStrCSpn | Equivalent to _mbscspn. |
| CmbStrChr | Equivalent to _mbschr. |
| CmbStrRChr | Equivalent to _mbsrchr. |
| CmbStrTok | Equivalent to _mbstok. |
| CmbStrPBrk | Equivalent to _mbspbrk. |
| CmbStrStr | Equivalent to _mbsstr. |
| CmbStrUpr | Converts all the lowercase characters in the given string to uppercase characters. Converts only English characters. |
| CmbStrLwr | Converts all the uppercase characters in the given string to lowercase characters. Converts only English characters. |
| CmbStrByteIs | Returns TRUE if the character at the given offset in the given string is equal to the given single byte character. Analogous to (s[offset] == ‘*’ ). |
| CmbStrLastChar | Returns a pointer to the last character of the given string. |