For a locale specified by name, maps an input character string to another using a specified transformation, or generates a sort key for the input string.
int LCMapStringEx( LPCWSTR lpLocaleName, DWORD dwMapFlags, LPCWSTR lpSrcStr, int cchSrc, LPWSTR lpDestStr, int cchDest, LPNLSVERSIONINFO lpVersionInformation, LPVOID lpReserved, LPARAM sortHandle );
Pointer to a locale name, or one of the following predefined values.
Flag specifying the type of transformation to use during string mapping or the type of sort key to generate. This parameter can have the following values.
|LCMAP_BYTEREV||Use byte reversal. For example, if the application passes in 0x3450 0x4822, the result is 0x5034 0x2248.|
|LCMAP_FULLWIDTH||Use Unicode (wide) characters where applicable. This flag and LCMAP_HALFWIDTH are mutually exclusive. With this flag, the mapping may use Normalization Form C even if an input character is already full-width. For example, the string "は゛" (which is already full-width) is normalized to "ば". See Unicode normalization forms.|
|LCMAP_HALFWIDTH||Use narrow characters where applicable. This flag and LCMAP_FULLWIDTH are mutually exclusive.|
|LCMAP_HIRAGANA||Map all katakana characters to hiragana. This flag and LCMAP_KATAKANA are mutually exclusive.|
|LCMAP_KATAKANA||Map all hiragana characters to katakana. This flag and LCMAP_HIRAGANA are mutually exclusive.|
|LCMAP_LINGUISTIC_CASING||Use linguistic rules for casing, instead of file system rules (default). This flag is valid with LCMAP_LOWERCASE or LCMAP_UPPERCASE only.|
|LCMAP_LOWERCASE||For locales and scripts capable of handling uppercase and lowercase, map all characters to lowercase.|
|LCMAP_HASH||Return a hash of the raw sort weights of a string.
Strings that appear equivalent typically return the same hash (for example, "hello" and "HELLO" with LCMAP_IGNORECASE). However, some complex cases, such as East Asian languages, can have similar strings with identical weights that compare as equal but do not return the same hash.
LCMAP_HASH requires that the output buffer be of size sizeof(int)
|LCMAP_SIMPLIFIED_CHINESE||Map traditional Chinese characters to simplified Chinese characters. This flag and LCMAP_TRADITIONAL_CHINESE are mutually exclusive.|
The use of a sort handle results in minimal performance improvements and is discouraged.
|Return a token representing the resolved sort parameters for the locale (like locale name), so future calls can pass
LCMAP_SORTHANDLE requires that the output buffer be of size sizeof(lparam)
|LCMAP_SORTKEY||Produce a normalized sort key. If the LCMAP_SORTKEY flag is not specified, the function performs string mapping. For details of sort key generation and string mapping, see the Remarks section.|
|LCMAP_TITLECASE||Windows 7: Map all characters to title case, in which the first letter of each major word is capitalized.|
|LCMAP_TRADITIONAL_CHINESE||Map simplified Chinese characters to traditional Chinese characters. This flag and LCMAP_SIMPLIFIED_CHINESE are mutually exclusive.|
|LCMAP_UPPERCASE||For locales and scripts capable of handling uppercase and lowercase, map all characters to uppercase.|
The following flags can be used alone, with one another, or with the LCMAP_SORTKEY and/or LCMAP_BYTEREV flags. However, they cannot be combined with the other flags listed above.
The flags listed below are used only with the LCMAP_SORTKEY flag.
Pointer to a source string that the function maps or uses for sort key generation. This string cannot have a size of 0.
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 this parameter to any negative value to specify that the source string is null-terminated. In this case, if LCMapStringEx 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.
Pointer to a buffer in which this function retrieves the mapped string or sort key. If the application specifies LCMAP_SORTKEY, the function stores a sort key in the buffer as an opaque array of byte values that can include embedded 0 bytes.
Size, in characters, of the buffer 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.
Windows Vista, Windows 7: Reserved; must set to NULL.
Reserved; must be NULL.
Reserved; must be 0.
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 if the input was null terminated.
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.
The application can use LCMapString or LCMapStringEx to generate a sort key. To do this, the application specifies LCMAP_SORTKEY for the dwMapFlags parameter. For more information, see Handling Sorting in Your Applications.
Another way for your application to use LCMapString or LCMapStringEx is in mapping strings. In this case, the application does not specify LCMAP_SORTKEY for the dwMapFlags parameter, but supplies some other combination of flags. For more information, see Handling Sorting in Your Applications.
Beginning in Windows Vista: This function can handle data from custom locales. Data is not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.
|Minimum supported client||Windows Vista [desktop apps | UWP apps]|
|Minimum supported server||Windows Server 2008 [desktop apps | UWP apps]|
|Header||winnls.h (include Windows.h)|