CompareStringA

int CompareStringA(

LCID  lcid,

DWORD  dwCmpFlags,

LPCSTR  lpString1,

integer  cchCount1,

LPCSTR  lpString2,

integer  cchCount2,

);


Compares two character strings of the same locale according to the supplied LCID.

Parameters

lcid
Locale context for the comparison. The strings are assumed to be represented in the default ANSI code page for this locale.
dwCmpFlags
Flags that indicate the character traits to use or ignore when comparing the two strings. Several flags can be combined , or none can be used. (In the case of this function, there are no illegal combinations of flags.) Compare flags include the following.
Value Meaning
NORM_IGNORECASE Ignore case. Default is Off.
NORM_IGNOREKANATYPE Ignore Japanese hiragana/katakana character differences. Default is Off.
NORM_IGNORENONSPACE Ignore nonspacing marks (accents, diacritics, and vowel marks). Default is Off.
NORM_IGNORESYMBOLS Ignore symbols. Default is Off.
NORM_IGNOREWIDTH Ignore character width. Default is Off.

lpString1 and lpString2
The two strings to be compared.
cchCount1 and cchCount2
The character counts of the two strings. The count does not include the null-terminator (if any). If either cchCount1 or cchCount2 is –1, the corresponding string is assumed to be null-terminated, and the length is calculated automatically.

Return Value

Value Meaning
0 Failure.
1 lpString1 is less than lpString2.
2 lpString1 is equal to lpString2.
3 lpString1 is greater than lpString2.

Comments

When used without any flags, this function uses the same sorting algorithm as lstrcmp in the given locale. When used with NORM_IGNORECASE, the same algorithm as lstrcmpi is used.

For double-byte character set (DBCS) locales, the flag NORM_IGNORECASE has an effect on all the wide (two-byte) characters as well as the narrow (one-byte) characters. This includes the wide Greek and Cyrillic characters.

In Chinese Simplified, the sorting order used to compare the strings is based on the following sequence: symbols, digit numbers, English letters, and Chinese Simplified characters. The characters within each group sort in character-code order.

In Chinese Traditional, the sorting order used to compare the strings is based on the number of strokes in the characters. Symbols, digit numbers, and English characters are considered to have zero strokes. The sort sequence is symbols, digit numbers, English letters, and Chinese Traditional characters. The characters within each stroke-number group sort in character-code order.

In Japanese, the sorting order used to compare the strings is based on the Japanese 50-on sorting sequence. The Kanji ideographic characters sort in character-code order.

In Japanese, the flag NORM_IGNORENONSPACE has an effect on the daku-on, handaku-on, chou-on, you-on, and soku-on modifiers, and on the repeat kana/kanji characters.

In Korean, the sort order is based on the sequence: symbols, digit numbers, Jaso and Hangeul, Hanja, and English. Within the Jaso-Hangeul group, each Jaso character is followed by the Hangeuls that start with that Jaso. Hanja characters are sorted in Hangeul pronunciation order. Where multiple Hanja have the same Hangeul pronunciation, they are sorted in character-code order.

The NORM_IGNORENONSPACE flag only has an effect for the locales in which accented characters are sorted in a second pass from main characters. All characters in the string are first compared without regard to accents and (if the strings are equal) a second pass over the strings to compare accents is performed. In this case, this flag causes the second pass to not be performed. Some locales sort accented characters in the first pass, in which case this flag will have no effect.

If the return value is 2, the two strings are equal in the collation sense, though not necessarily identical (the case might be ignored, and so on).

If the two strings are of different lengths, they are compared up to the length of the shortest one. If they are equal to that point, the return value will indicate that the longer string is greater.

To maintain the C run-time convention of comparing strings, the value 2 can be subtracted from a non-zero return value. The meaning of < 0, == 0, and > 0 is then consistent with the C run-time conventions.