Compartilhar via

LCMapString

  • Artigo

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function maps one character string to another, performing a specified locale-dependent transformation. LCMapString can also be used to generate a sort key for the input string.

Note

If you specify a locale with the LCID (Locale ID) parameter and that locale is not installed or available on the Windows® phone, the function fails with ERROR_INVALID_PARAMETER. To determine whether the locale is supported or not, call IsValidLocale.

Syntax

int LCMapString(
  LCID Locale, 
  DWORD dwMapFlags, 
  LPCTSTR lpSrcStr, 
  int cchSrc, 
  LPTSTR lpDestStr, 
  int cchDest 
);

Parameters

  • Locale
    [in] Locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the MAKELCID macro to create a locale identifier.

  • dwMapFlags
    [in] Value that specifies the type of transformation to be used during string mapping or sort key generation. An application can specify more than one of these options on a single transformation, although some combinations are invalid. The following table show both the mapping options and any restrictions.

    Value Description

    LCMAP_BYTEREV

    Use byte reversal. For example, if you pass in 0x3450 0x4822 the result is 0x5034 0x2248.

    LCMAP_FULLWIDTH

    Wide characters (where applicable).

    LCMAP_HALFWIDTH

    Narrow characters (where applicable).

    LCMAP_HIRAGANA

    Hiragana.

    LCMAP_KATAKANA

    Katakana.

    LCMAP_LINGUISTIC_CASING

    Uses linguistic rules for casing, rather than file system rules (the default). Valid with LCMAP_LOWERCASE or LCMAP_UPPERCASE only.

    LCMAP_LOWERCASE

    Use lowercase.

    LCMAP_SORTKEY

    Produce a normalized wide-character sort key.

    LCMAP_UPPERCASE

    Use uppercase.

    NORM_IGNORECASE

    Ignore case.

    NORM_IGNOREKANATYPE

    Do not differentiate between Hiragana and Katakana characters. Corresponding Hiragana and Katakana will compare as equal.

    NORM_IGNORENONSPACE

    Ignore nonspacing. This flag also removes Japanese accent characters.

    NORM_IGNORESYMBOLS

    Ignore symbols.

    NORM_IGNOREWIDTH

    Do not differentiate between a single-byte character and the same character as a double-byte character.

    SORT_STRINGSORT

    Treat punctuation the same as symbols.

    If theLCMAP_SORTKEY flag is not specified, the LCMapString function performs string mapping. In this case the following restrictions apply:

    • LCMAP_LOWERCASE and LCMAP_UPPERCASE are mutually exclusive.
    • LCMAP_HIRAGANA and LCMAP_KATAKANA are mutually exclusive.
    • LCMAP_HALFWIDTH and LCMAP_FULLWIDTH are mutually exclusive.
    • SORT_STRINGSORT, NORM_IGNOREKANATYPE, NORM_IGNOREWIDTH, and NORM_IGNORECASE are not valid.
    • LCMAP_TRADITIONAL_CHINESE and LCMAP_SIMPLIFIED_CHINESE are mutually exclusive.
    • LCMAP_LOWERCASE and LCMAP_UPPERCASE are not valid in combination with any of the following flags: LCMAP_HIRAGANA, LCMAP_KATAKANA, LCMAP_HALFWIDTH, and LCMAP_FULLWIDTH.
      When the LCMAP_SORTKEY flag is specified, the LCMapString function generates a sort key. In this case the following restriction applies:
    • LCMAP_SORTKEY is mutually exclusive with all other LCMAP_* flags, with the sole exception of LCMAP_BYTEREV.
  • lpSrcStr
    [in] Pointer to a source string that the function maps or uses for sort key generation.

  • cchSrc
    [in] Size, in characters, of the string pointed to by the lpSrcStr parameter.

    This count can include the NULL terminator, or not include it. If the NULL terminator is included in the character count, it does not greatly affect the mapping behavior. That is because NULL is considered to be unsortable, and always maps to itself.

    A cchSrc value of –1 specifies that the string pointed to by lpSrcStr is null-terminated. If this is the case, and LCMapString is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into *lpDestStr.

  • lpDestStr
    [out] Long pointer to a buffer into which the function stores the mapped string or sort key.

    If LCMAP_SORTKEY is specified, LCMapString stores a sort key into the buffer. The sort key is stored as an array of byte values in the following format:

    [all Unicode sort weights] 0x01 [all Diacritic weights] 
0x01 [all Case weights] 0x01 [all Special weights] 0x00

    Note that the sort key is null-terminated. This is true regardless of the value of cchSrc. Also note that, even if some of the sort weights are absent from the sort key, due to the presence of one or more ignore flags in dwMapFlags, the 0x01 separators and the 0x00 terminator are still present.

  • cchDest
    [in] Size, in characters, of the buffer pointed to by lpDestStr.

    If the function is being used for string mapping, the size is a character count. If space for a NULL terminator is included in cchSrc, then cchDest must also include space for a NULL terminator.

    If the function is being used to generate a sort key, the size is a byte count. This byte count must include space for the sort key 0x00 terminator.

    If cchDest is zero, the function's return value is the number of characters, or bytes if LCMAP_SORTKEY is specified, required to hold the mapped string or sort key. In this case, the buffer pointed to by lpDestStr is not used.

Return Value

If the value of cchDest is nonzero, the number of characters, or bytes if LCMAP_SORTKEY is specified, written to the buffer indicates success. This count includes room for a NULL terminator.

If the value of cchDest is zero, the size of the buffer in characters, or bytes if LCMAP_SORTKEY is specified, required to receive the translated string or sort key indicates success. This size includes room for a NULL terminator. Zero indicates failure.

To get extended error information, call the GetLastError function. The following table shows possible values for GetLastError.

Value Description

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

ERROR_INVALID_FLAGS

The flags are invalid.

ERROR_INVALID_PARAMETER

The parameter is incorrect, or the specified LCID is not supported on the device.

Remarks

The mapped string is null terminated if the source string is null terminated.

If the LCMAP_HIRAGANA flag is specified to map Katakana characters to Hiragana characters, and LCMAP_FULLWIDTH is not specified, the function only maps full-width characters to Hiragana. In this case, any half-width Katakana characters are placed as-is in the output string, with no mapping to Hiragana. An application must specify LCMAP_FULLWIDTH if it wants half-width Katakana characters mapped to Hiragana.

The lpSrcStr and lpDestStr pointers must not be the same. If they are the same, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

Even though Windows Embedded CE supports only the Unicode version of this function, the output string is only in WCHAR or CHAR format if the string-mapping mode of LCMapString is used. If the sort key generation mode is used, specified by LCMAP_SORTKEY, the output is an array of byte values. An application can compare sort keys by using a byte-by-byte comparison.

An application can call the function with the NORM_IGNORENONSPACE and NORM_IGNORESYMBOLS flags set, and all other options flags cleared, in order to simply strip characters from the input string. If this is done with an input string that is not null-terminated, it is possible for LCMapString to return an empty string and not return an error.

The LCMapString function ignores the Arabic Kashida. If an application calls the function to create a sort key for a string that contains an Arabic Kashida, there will be no sort key value for the Kashida.

The function treats the hyphen and apostrophe a bit differently than other punctuation symbols, so that words like coop and co-op stay together in a list. All punctuation symbols other than the hyphen and apostrophe sort before the alphanumeric characters. An application can change this behavior by setting the SORT_STRINGSORT flag. For a more detailed discussion of this issue, see the CompareString function.

When LCMapString is used to generate a sort key, by setting the LC_MAPSORTKEY flag, the sort key stored into *lpDestStr may contain an odd number of bytes. The LCMAP_BYTEREV option only reverses an even number of bytes. If both options are chosen, the last (odd-positioned) byte in the sort key is not reversed. If the terminating 0x00 byte is an odd-positioned byte, then it remains the last byte in the sort key. If the terminating 0x00 byte is an even-positioned byte, it exchanges positions with the byte that precedes it.

For more information about LCID, see National Language support (NLS) Locale Identifiers.

Requirements

Header winnls.h
Library Coreloc.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

CompareString
FoldString
MAKELCID

Other Resources

National Language Support (NLS) Locale Identifiers