Expand Minimize

LCMapStringEx function

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.

Note  The application should call this function in preference to LCMapString if designed to run only on Windows Vista and later.

Syntax


int LCMapStringEx(
  _In_opt_   LPCWSTR lpLocaleName,
  _In_       DWORD dwMapFlags,
  _In_       LPCWSTR lpSrcStr,
  _In_       int cchSrc,
  _Out_opt_  LPWSTR lpDestStr,
  _In_       int cchDest,
  _In_opt_   LPNLSVERSIONINFO lpVersionInformation,
  _In_opt_   LPVOID lpReserved,
  _In_opt_   LPARAM sortHandle
);

Parameters

lpLocaleName [in, optional]

Pointer to a locale name, or one of the following predefined values.

dwMapFlags [in]

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.

FlagMeaning
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.

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_SIMPLIFIED_CHINESE

Map traditional Chinese characters to simplified Chinese characters. This flag and LCMAP_TRADITIONAL_CHINESE are mutually exclusive.

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.

FlagMeaning
NORM_IGNORENONSPACE

Ignore nonspacing characters. For many scripts (notably Latin scripts), NORM_IGNORENONSPACE coincides with LINGUISTIC_IGNOREDIACRITIC.

Note  NORM_IGNORENONSPACE ignores any secondary distinction, whether it is a diacritic or not. Scripts for Korean, Japanese, Chinese, and Indic languages, among others, use this distinction for purposes other than diacritics. LINGUISTIC_IGNOREDIACRITIC causes the function to ignore only actual diacritics, instead of ignoring the second sorting weight.

NORM_IGNORESYMBOLS

Ignore symbols and punctuation.

 

The flags listed below are used only with the LCMAP_SORTKEY flag.

FlagMeaning
LINGUISTIC_IGNORECASE

Ignore case, as linguistically appropriate.

LINGUISTIC_IGNOREDIACRITIC

Ignore nonspacing characters, as linguistically appropriate.

Note  This flag does not always produce predictable results when used with decomposed characters, that is, characters in which a base character and one or more nonspacing characters each have distinct code point values.

NORM_IGNORECASE

Ignore case. For many scripts (notably Latin scripts), NORM_IGNORECASE coincides with LINGUISTIC_IGNORECASE.

Note  NORM_IGNORECASE ignores any tertiary distinction, whether it is actually linguistic case or not. For example, in Arabic and Indic scripts, this flag distinguishes alternate forms of a character, but the differences do not correspond to linguistic case. LINGUISTIC_IGNORECASE causes the function to ignore only actual linguistic casing, instead of ignoring the third sorting weight.

Note  For double-byte character set (DBCS) locales, NORM_IGNORECASE has an effect on all Unicode characters as well as narrow (one-byte) characters, including Greek and Cyrillic characters.

NORM_IGNOREKANATYPE

Do not differentiate between hiragana and katakana characters. Corresponding hiragana and katakana characters compare as equal.

NORM_IGNOREWIDTH

Ignore the difference between half-width and full-width characters, for example, C a t == cat. The full-width form is a formatting distinction used in Chinese and Japanese scripts.

NORM_LINGUISTIC_CASING

Use linguistic rules for casing, instead of file system rules (default).

SORT_DIGITSASNUMBERS

Windows 7: Treat digits as numbers during sorting, for example, sort "2" before "10".

SORT_STRINGSORT

Treat punctuation the same as symbols.

 

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 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.

lpDestStr [out, optional]

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.

Note  If the function fails, 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 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.

lpVersionInformation [in, optional]

Reserved; must be NULL.

lpReserved [in, optional]

Reserved; must be NULL.

sortHandle [in, optional]

Reserved; must be 0.

Return value

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.

Remarks

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.

Beginning in Windows 8: If your app passes language tags to this function from the Windows.Globalization namespace, it must first convert the tags by calling ResolveLocaleName.

Windows Phone 8.1: This API is supported.

Requirements

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Winnls.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

National Language Support
National Language Support Functions
Handling Sorting in Your Applications
CompareString
FindNLSStringEx
GetNLSVersionEx
LCMapString

 

 

Community Additions

ADD
Show:
© 2014 Microsoft