For a locale specified by identifier, maps one input character string to another using a specified transformation, or generates a sort key for the input string.
Note For interoperability reasons, the application should prefer the LCMapStringEx function to LCMapString because Microsoft is migrating toward the use of locale names instead of locale identifiers for new locales. This recommendation applies especially to custom locales, including those created by Microsoft. Any application that will be run only on Windows Vista and later should use LCMapStringEx.
int LCMapString( _In_ LCID Locale, _In_ DWORD dwMapFlags, _In_ LPCTSTR lpSrcStr, _In_ int cchSrc, _Out_opt_ LPTSTR lpDestStr, _In_ int cchDest );
- Locale [in]
The following custom locale identifiers are also supported.
- dwMapFlags [in]
Flags specifying the type of transformation to use during string mapping or the type of sort key to generate. For detailed definitions, see the dwMapFlags parameter of LCMapStringEx.
- lpSrcStr [in]
Pointer to a source string that the function maps or uses for sort key generation. This string cannot have a size of 0.
- cchSrc [in]
Size, in characters, of the source string indicated by lpSrcStr. The size of the source string can include the terminating null character, but does not have to. If the terminating null character is included, the mapping behavior of the function is not greatly affected because the terminating null character is considered to be unsortable and always maps to itself.
The application can set the parameter to any negative value to specify that the source string is null-terminated. In this case, if LCMapString is being used in its string-mapping mode, the function calculates the string length itself, and null-terminates the mapped string indicated by lpDestStr.
The application cannot set this parameter to 0.
- lpDestStr [out, optional]
Pointer to a buffer in which this function retrieves the mapped string or a sort key. When the application uses this function to generate a sort key, the destination string can contain an odd number of bytes. The LCMAP_BYTEREV flag only reverses an even number of bytes. The last byte (odd-positioned) in the sort key is not reversed.
Note The destination string can be the same as the source string only if LCMAP_UPPERCASE or LCMAP_LOWERCASE is set. Otherwise, the strings cannot be the same. If they are, the function fails.
Note Upon failure of the function, the destination buffer might contain either partial results or no results at all. In this case, it is recommended for your application to consider any results invalid.
- cchDest [in]
Size, in characters, of the destination string indicated by lpDestStr. If the application is using the function for string mapping, it supplies a character count for this parameter. If space for a terminating null character is included in cchSrc, cchDest must also include space for a terminating null character.
If the application is using the function to generate a sort key, it supplies a byte count for the size. This byte count must include space for the sort key 0x00 terminator.
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 or sort key.
Returns the number of characters or bytes in the translated string or sort key, 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 or sort key, 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_FLAGS. The values supplied for flags were not valid.
- ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
See Remarks for LCMapStringEx.
The ANSI version of LCMapString maps strings to and from Unicode based on the default Windows (ANSI) code page associated with the specified locale. When the ANSI version of this function is used with a Unicode-only locale, the function can succeed because the operating system uses the CP_ACP value, representing the system default Windows ANSI code page. However, characters that are undefined in the system code page appear in the string as a question mark (?).
Minimum supported client
|Windows 2000 Professional [desktop apps only]|
Minimum supported server
|Windows 2000 Server [desktop apps only]|
Unicode and ANSI names
|LCMapStringW (Unicode) and LCMapStringA (ANSI)|
- National Language Support
- National Language Support Functions
- Handling Sorting in Your Applications