LCMapStringA

int LCMapStringA(

LCID  lcid,

DWORD  dwMapFlags,

LPCSTR  lpSrcStr,

int  cchSrc,

LPSTR  lpDestStr,

int  cchDest,

);

Transforms the case or sort order of a string.

Parameters

lcid

Locale ID context for mapping. The strings are assumed to be represented in the default ANSI code page for this locale.

dwMapFlags

Flags that indicate what type of transformation is to occur during mapping. Several flags can be combined on a single transformation (though some combinations are illegal). Mapping options include the following.

Name	Meaning
LCMAP_LOWERCASE	Lowercase.
LCMAP_UPPERCASE	Uppercase.
LCMAP_SORTKEY	Character sort key.
LCMAP_HALFWIDTH	Narrow characters (where applicable).
LCMAP_FULLWIDTH	Wide characters (where applicable).
LCMAP_HIRAGANA	Hiragana.
LCMAP_KATAKANA	Katakana.
NORM_IGNORECASE	Ignore case. Default is Off.
NORM_IGNORENONSPACE	Ignore nonspacing. Default is Off.
NORM_IGNOREWIDTH	Ignore character width. Default is Off.
NORM_IGNOREKANATYPE	Ignore Japanese hiragana/katakana character differences. Default is Off.
NORM_IGNORESYMBOLS	Ignore symbols. Default is Off.

The latter five options (NORM_IGNORECASE, NORM_IGNORENONSPACE, NORM_IGNOREWIDTH, NORM_IGNOREKANATYPE, and NORM_IGNORESYMBOLS) are normalization options that can only be used in combination with the LCMAP_SORTKEY conversion option.

Conversion options can be combined only when they are taken from the following three groups, and then only when there is no more than one option from each group:

• Casing options (LCMAP_LOWERCASE, LCMAP_UPPERCASE)
• Width options (LCMAP_HALFWIDTH, LCMAP_FULLWIDTH)
• Kana options (LCMAP_HIRAGANA, LCMAP_KATAKANA)

lpSrcStr

Pointer to the supplied string to be mapped.

cchSrc

Character count of the input string buffer. If –1, lpSrcStr is assumed to be null-terminated and the length is calculated automatically.

lpDestStr

Pointer to the memory buffer that stores the resulting mapped string.

cchDest

Character count of the memory buffer pointed to by lpDestStr. If cchDest is 0, then the return value of this function is the number of characters required to hold the mapped string. In this case, the lpDestStr pointer is not referenced.

Return Value

Comments

LCMapStringA maps one character string to another, performing the specified locale-dependent translation.

The flag LCMAP_UPPER produces the same result as AnsiUpper in the given locale. The flag LCMAP_LOWER produces the same result as AnsiLower. This function always maps a single character to a single character.

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

When used with LCMAP_UPPER and LCMAP_LOWER, the lpSrcStr and lpDestStr may be the same to produce an in-place mapping. When LCMAP_SORTKEY is used, the lpSrcStr and lpDestStr pointers may not be the same. In this case, an error will result.

The LCMAP_SORTKEY transforms two strings so that when they are compared with the standard C library function strcmp (by strict numerical valuation of their characters), the same order will result, as if the original strings were compared with CompareStringA. When LCMAP_SORTKEY is specified, the output string is a string (without Nulls, except for the terminator), but the character values will not be meaningful display values. This is similar behavior to the ANSI C function strxfrm.