The FoldString function maps one string to another, performing a specified transformation option.

Syntax

int FoldString(      
    DWORD dwMapFlags,
    LPCTSTR lpSrcStr,
    int cchSrc,
    LPTSTR lpDestStr,
    int cchDest
);

Parameters

dwMapFlags

[in] 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 values.

MAP_FOLDCZONE

Fold compatibility zone characters into standard Unicode equivalents. This flag is equivalent to normalization form KD in Windows Vista, if the MAP_COMPOSITE flag is also set. If the composite flag is not set (default), this flag is equivalent to normalization form KC in Windows Vista. For information about compatibility zone characters, see the 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 flag is equvalent to normalization form C in Windows Vista. This value cannot be combined with MAP_COMPOSITE.

MAP_COMPOSITE

Map accented characters to decomposed characters, that is, characters in which a base character and one or more nonspacing characters each have distinct code point values. This flag is equivalent to normalization form D in Windows Vista. Note that this flag cannot be used with MB_PRECOMPOSED. This value cannot be combined with MAP_PRECOMPOSED.

MAP_EXPAND_LIGATURES

Expand all ligature characters so that they are represented by their two-character equivalent. For example, the ligature '?' expands to the two characters 'a' and 'e'. This value cannot be combined with MAP_PRECOMPOSED or MAP_COMPOSITE.

lpSrcStr

[in] Pointer to the string to be mapped.

cchSrc

[in] Specifies the size, in TCHARs, of the lpSrcStr buffer. This refers to bytes for ANSI versions of the function or WCHARs for Unicode versions. If cchSrc is any negative value, lpSrcStr is assumed to be null-terminated, and the length is calculated automatically.

lpDestStr

[out] Pointer to the buffer to store the mapped string.

cchDest

[in] Specifies the size, in TCHARs, of the lpDestStr buffer. If cchDest is zero, except in the case of MAP_FOLDDIGITS, the function returns the number of characters required to hold the mapped string and the buffer pointed to by lpDestStr is not used.

In the case of MAP_FOLDDIGITS, when cchDest is zero the return value will be the maximum size required, even if the actual number of characters needed is smaller than the maximum size. If the maximum size is not passed, the function will fail and return ERROR_INSUFFICIENT_BUFFER.

Return Value

If the function succeeds, the return value is the number of TCHARs written to the destination buffer, or if the cchDest parameter is zero, the number of characters required to hold the mapped string. This refers to bytes for ANSI versions of the function or WCHARs for Unicode versions. Note that, when cchDest is zero, except in the case of MAP_FOLDDIGITS, the return value includes space for the null termination if the original string includes a null termination and if cchSrc is either -1 or a length that includes the null termination.

In the case of MAP_FOLDDIGITS, when cchDest is zero the return value will be the maximum size required, even if the actual number of characters needed is smaller than the maximum size. If the maximum size is not passed, the function will fail and return ERROR_INSUFFICIENT_BUFFER.

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

ERROR_OUTOFMEMORY

ERROR_INVALID_DATA

ERROR_MOD_NOT_FOUND

ERROR_PROC_NOT_FOUND

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.

Windows Vista: Supports Unicode normalization. All Unicode compatibility characters are mapped.

Windows Vista: In Windows Vista, the transformations indicated by the MAP_FOLDCZONE, MAP_PRECOMPOSED, and MAP_COMPOSITE flags use Unicode normalization (through the NormalizeString function) to do the mappings.

Security Alert  Using this function incorrectly can compromise the security of your application. Strings that are not mapped correctly can produce invalid input. Test strings to make sure they are valid before using them and provide error handlers. For more information, see Security Considerations: International Features.

Function Information

Minimum DLL Version	kernel32.dll
Header	Declared in Winnls.h, include Windows.h
Import library	Kernel32.lib
Minimum operating systems	Windows NT 3.1
Unicode	Implemented as Unicode version.

See Also

Strings Overview, LCMapString, CompareString