FoldString
The FoldString
function maps one string to another, performing a specified transformation
option.
int FoldString(
|
DWORD dwMapFlags, |
// mapping
transformation options |
|
LPCTSTR lpSrcStr, |
// pointer to
source string |
|
int cchSrc, |
// size of source
string, in bytes or characters |
|
LPTSTR lpDestStr, |
// pointer to
destination buffer |
|
int cchDest |
// size of
destination buffer, in bytes or characters |
|
); |
|
Parameters
dwMapFlags
A set of bit
flags that indicate the type of transformation to be used during mapping. This
value can be a combination of the following bit-flag constants:
|
Option |
Meaning |
|
MAP_FOLDCZONE |
Fold
compatibility zone characters into standard Unicode equivalents. For
information about compatibility zone characters, see the following Remarks
section. |
|
MAP_FOLDDIGITS |
Map all
digits to Unicode characters 0 through 9. |
|
MAP_PRECOMPOSED |
Map
accented characters to precomposed characters, in which the accent and base
character are combined into a single character value. This value cannot be
combined with MAP_COMPOSITE. |
|
MAP_COMPOSITE |
Map
accented characters to composite characters, in which the accent and base
character are represented by two character values. This value cannot be
combined with MAP_PRECOMPOSED. |
lpSrcStr
Points to the
string to be mapped.
cchSrc
Specifies the
size, in bytes (ANSI version) or characters (Unicode version), of the lpSrcStr
buffer. If cchSrc is -1, lpSrcStr
is assumed to be null-terminated, and the length is calculated automatically.
lpDestStr
Points to the
buffer to store the mapped string.
cchDest
Specifies the
size, in bytes (ANSI version) or characters (Unicode version), of the lpDestStr
buffer. If cchDest is zero, the function returns the number of bytes or
characters required to hold the mapped string, and the buffer pointed to by lpDestStr
is not used.
Return Values
If the function
succeeds, the return value is the number of bytes (ANSI version) or characters
(Unicode version) written to the destination buffer, or if the cchDest
parameter is zero, the number of bytes or characters required to hold the
mapped string.
If the function
fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may
return one of the following error codes:
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
Remarks
The mapped
string is null-terminated if the source string is null-terminated.
The lpSrcStr
and lpDestStr pointers must not be the same. If they are the same, the
function fails and GetLastError returns ERROR_INVALID_PARAMETER.
The
compatibility zone in Unicode consists of characters in the range 0xF900
through 0xFFEF that are assigned to characters from other character-encoding
standards but are actually variants of characters that are already in Unicode.
The compatibility zone is used to support round-trip mapping to these
standards. Applications can use the MAP_FOLDCZONE flag to avoid supporting the
duplication of characters in the compatibility zone.
See Also