FoldStringW function (stringapiset.h)

Maps one Unicode string to another, performing the specified transformation. For an overview of the use of the string functions, see Strings.

Syntax

int FoldStringW(
  [in]            DWORD                         dwMapFlags,
  [in]            _In_NLS_string_(cchSrc)LPCWCH lpSrcStr,
  [in]            int                           cchSrc,
  [out, optional] LPWSTR                        lpDestStr,
  [in]            int                           cchDest
);

Parameters

[in] dwMapFlags

Flags specifying the type of transformation to use during string mapping. This parameter can be a combination of the following values.

[in] lpSrcStr

Pointer to a source string that the function maps.

[in] cchSrc

Size, in characters, of the source string indicated by lpSrcStr, excluding the terminating null character. The application can set the parameter to any negative value to specify that the source string is null-terminated. In this case, the function calculates the string length automatically, and null-terminates the mapped string indicated by lpDestStr.

[out, optional] lpDestStr

Pointer to a buffer in which this function retrieves the mapped string.

[in] cchDest

Size, in characters, of the destination string indicated by lpDestStr. If space for a terminating null character is included in cchSrc, cchDest must also include space for a terminating null character.

The application can set cchDest to 0. In this case, the function does not use the lpDestStr parameter and returns the required buffer size for the mapped string. If the MAP_FOLDDIGITS flag is specified, the return value is 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 fails with ERROR_INSUFFICIENT_BUFFER.

Return value

Returns the number of characters in the translated string, including a terminating null character, if successful. If the function succeeds and the value of cchDest is 0, the return value is the size of the buffer required to hold the translated string, including a terminating null character.

This function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:

• ERROR_INSUFFICIENT_BUFFER. A supplied buffer size was not large enough, or it was incorrectly set to NULL.
• ERROR_INVALID_DATA. The data was invalid.
• ERROR_INVALID_FLAGS. The values supplied for flags were not valid.
• ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
• ERROR_MOD_NOT_FOUND. The module was not found.
• ERROR_OUTOFMEMORY. Not enough storage was available to complete this operation.
• ERROR_PROC_NOT_FOUND. The required procedure was not found.

Remarks

The values of the lpSrcStr and lpDestStr parameters must not be the same. If they are the same, the function fails with ERROR_INVALID_PARAMETER.

The compatibility zone in Unicode consists of characters in the range 0xF900 through 0xFFEF that are assigned to characters from other encoding standards for characters but are actually variants of characters 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.

Starting with Windows Vista: This function supports Unicode normalization. All Unicode compatibility characters are mapped.

Starting with Windows Vista: The transformations indicated by the MAP_FOLDCZONE, MAP_PRECOMPOSED, and MAP_COMPOSITE flags use Unicode normalization forms KC, C, and D (through the NormalizeString function) to do the mappings.

Starting with Windows 8: The ANSI version of the function is declared in Winnls.h and the Unicode version is declared in Stringapiset.h. Before Windows 8, both versions were declared in Winnls.h.

Requirements

See also

National Language Support

National Language Support Functions

NormalizeString

Security Considerations: International Features

Sorting

Using Unicode Normalization to Represent Strings