|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| Yes
| Win32s
| Yes
| Import Library
| kernel32.lib
| Header File
| winnls.h
| Unicode
| WinNT
| Platform Notes
| None
|
|
|
LCMapString
The
LCMapString function maps one character string to another, performing a specified
locale-dependent transformation. The function can also be used to generate a sort key
for the input string.
int LCMapString(
LCID Locale,
| // locale identifier
|
DWORD dwMapFlags,
| // mapping transformation type
|
LPCTSTR lpSrcStr,
| // address of source string
|
int cchSrc,
| // number of characters in source string
|
LPTSTR lpDestStr,
| // address of destination buffer
|
int cchDest
| // size of destination buffer
|
);
|
|
Parameters
Locale
Specifies a 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
A set of flags that indicate 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 mapping options are defined; restrictions are noted following
the table:
Option
| Meaning
|
LCMAP_BYTEREV
| Windows NT only: Use byte reversal. For example, if you pass in 0x3450 0x4822 the result is
0x5034 0x2248.
|
LCMAP_FULLWIDTH
| Map single-byte characters to double-byte characters.
|
LCMAP_HALFWIDTH
| Map double-byte characters to single-byte characters.
|
LCMAP_HIRAGANA
| Map double-byte Katakana characters to double-byte Hiragana characters.
|
LCMAP_KATAKANA
| Map double-byte Hiragana characters to double-byte Katakana characters.
|
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 the
LCMAP_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_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:
- All LCMAP_* options are invalid, with the sole exception of LCMAP_BYTEREV. In
other words, LCMAP_SORTKEY is mutually exclusive with all other LCMAP_* flags,
with the sole exception of LCMAP_BYTEREV. LCMAP_BYTEREV is valid for Windows NT
only.
lpSrcStr
Pointer to a source string that the function maps or uses for sort key
generation.
cchSrc
Specifies the number of bytes (ANSI version) or characters (Unicode version)
in 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
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
Specifies the size in bytes (ANSI version) or characters (Unicode version) 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 Values
If the function succeeds, and the value of
cchDest is nonzero, the return value is the number of characters, or bytes if
LCMAP_SORTKEY is specified, written to the buffer. This count includes room for a NULL
terminator.
If the function succeeds, and the value of
cchDest is zero, the return value is the size of the buffer in characters, or bytes
if LCMAP_SORTKEY is specified, required to receive the translated string or sort
key. This size includes room for a NULL terminator.
If the function fails, the return value is 0. To get extended error
information, call
GetLastError.
GetLastError may return one of the following error codes:
ERROR_INSUFFICIENT_BUFFER
ERROR_INVALID_FLAGS
ERROR_INVALID_PARAMETER
Remarks
The mapped string is null terminated if the source string is null terminated.
The
A version of this function maps strings to and from Unicode based on the
specified LCID's default ANSI code page.
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 if the wide-character Unicode version of this function is called, 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 containing 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. See
CompareString for a more detailed discussion of this issue.
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 (Windows NT
only) 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.
See Also
CompareString,
FoldString,
MAKELCID
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database