CompareStringEx function (stringapiset.h)
Compares two Unicode (wide character) strings, for a locale specified by name.
Syntax
int CompareStringEx(
[in, optional] LPCWSTR lpLocaleName,
[in] DWORD dwCmpFlags,
[in] _In_NLS_string_(cchCount1)LPCWCH lpString1,
[in] int cchCount1,
[in] _In_NLS_string_(cchCount2)LPCWCH lpString2,
[in] int cchCount2,
[in, optional] LPNLSVERSIONINFO lpVersionInformation,
[in, optional] LPVOID lpReserved,
[in, optional] LPARAM lParam
);
Parameters
[in, optional] lpLocaleName
Pointer to a locale name, or one of the following predefined values.
[in] dwCmpFlags
Flags that indicate how the function compares the two strings. By default, these flags are not set. This parameter can specify a combination of any of the following values, or it can be set to 0 to obtain the default behavior.
| Flag | Meaning |
|---|---|
|
Ignore case, as linguistically appropriate. |
|
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.
|
|
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 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 With this flag set, the function ignores the distinction between the wide and narrow forms of the CJK compatibility characters.
|
|
Do not differentiate between hiragana and katakana characters. Corresponding hiragana and katakana characters compare as equal. |
|
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.
Note NORM_IGNORENONSPACE only has an effect for locales in which accented characters are sorted in a second pass from main characters. Normally all characters in the string are first compared without regard to accents and, if the strings are equal, a second pass over the strings is performed to compare accents. This flag causes the second pass to not be performed. For locales that sort accented characters in the first pass, this flag has no effect.
|
|
Ignore symbols and punctuation. |
|
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. |
|
Use the default linguistic rules for casing, instead of file system rules. Note that most scenarios for CompareStringEx use this flag. This flag does not have to be used when your application calls CompareStringOrdinal. |
|
Windows 7: Treat digits as numbers during sorting, for example, sort "2" before "10". |
|
Treat punctuation the same as symbols. |
[in] lpString1
Pointer to the first string to compare.
[in] cchCount1
Length of the string indicated by lpString1, excluding the terminating null character. The application can supply a negative value if the string is null-terminated. In this case, the function determines the length automatically.
[in] lpString2
Pointer to the second string to compare.
[in] cchCount2
Length of the string indicated by lpString2, excluding the terminating null character. The application can supply a negative value if the string is null-terminated. In this case, the function determines the length automatically.
[in, optional] lpVersionInformation
Pointer to an NLSVERSIONINFOEX structure that contains the version information about the relevant NLS capability; usually retrieved from GetNLSVersionEx.
Windows Vista, Windows 7: Reserved; must set to NULL.
[in, optional] lpReserved
Reserved; must set to NULL.
[in, optional] lParam
Reserved; must be set to 0.
Return value
Returns one of the following values if successful. To maintain the C runtime convention of comparing strings, the value 2 can be subtracted from a nonzero return value. Then, the meaning of <0, ==0, and >0 is consistent with the C runtime.
- CSTR_LESS_THAN. The string indicated by lpString1 is less in lexical value than the string indicated by lpString2.
- CSTR_EQUAL. The string indicated by lpString1 is equivalent in lexical value to the string indicated by lpString2. The two strings are equivalent for sorting purposes, although not necessarily identical.
- CSTR_GREATER_THAN. The string indicated by lpString1 is greater in lexical value than the string indicated by lpString2.
- ERROR_INVALID_FLAGS. The values supplied for flags were invalid.
- ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
Remarks
Both CompareString and CompareStringEx are optimized to run at the highest speed when dwCmpFlags is set to 0 or NORM_IGNORECASE, cchCount1 and cchCount2 are set to -1, and the locale does not support any linguistic compressions, as when traditional Spanish sorting treats "ch" as a single character.
Both CompareString and CompareStringEx ignore Arabic kashidas during the comparison. Thus, if two strings are identical except for the presence of kashidas, the function returns CSTR_EQUAL.
When the application uses the NORM_IGNORENONSPACE and NORM_IGNORECASE flags with the sorting function, the flags can sometimes interfere with string comparisons. This situation might result for a locale that does not support non-spacing characters or case, but uses equivalent weight levels to handle other important operations. In such cases, your application should use the LINGUISTIC_IGNOREDIACRITIC and LINGUISTIC_IGNORECASE flags. These flags provide linguistically appropriate results for sorting code points that use case and diacritic marks, and have no impact on other code points.
Beginning in Windows Vista: Both CompareString and CompareStringEx can retrieve 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.
Beginning in Windows 8: CompareStringEx is declared in Stringapiset.h. Before Windows 8, it was declared in Winnls.h.
Examples
An example showing the use of this function can be found in NLS: Name-based APIs Sample.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | stringapiset.h (include Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |
See also
Handling Sorting in Your Applications
National Language Support Functions