Compares two Unicode (wide character) strings, for a locale specified by name.
Caution Using CompareStringEx incorrectly can compromise the security of your application. Strings that are not compared correctly can produce invalid input. Test strings to make sure they are valid before using them, and provide error handlers. For more information, see Security Considerations: International Features.
Note The application should call this function in preference to CompareString if designed to run only on Windows Vista and later.
int CompareStringEx( _In_opt_ LPCWSTR lpLocaleName, _In_ DWORD dwCmpFlags, _In_ LPCWSTR lpString1, _In_ int cchCount1, _In_ LPCWSTR lpString2, _In_ int cchCount2, _In_opt_ LPNLSVERSIONINFO lpVersionInformation, _In_opt_ LPVOID lpReserved, _In_opt_ LPARAM lParam );
- lpLocaleName [in, optional]
Pointer to a locale name, or one of the following predefined values.
- dwCmpFlags [in]
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.
- lpString1 [in]
Pointer to the first string to compare.
- cchCount1 [in]
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.
- lpString2 [in]
Pointer to the second string to compare.
- cchCount2 [in]
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.
- lpVersionInformation [in, optional]
Reserved; must set to NULL.
- lpReserved [in, optional]
Reserved; must set to NULL.
- lParam [in, optional]
Reserved; must be set to 0.
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.
The function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError, which can return one of the following error codes:
- ERROR_INVALID_FLAGS. The values supplied for flags were invalid.
- ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
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: CompareStringEx is declared in Stringapiset.h. Before Windows 8, it was declared in Winnls.h.
Note The behavior of sorting can change between Windows releases. For example, there may be new Unicode code points created. Use GetNlsVersionEx to discover if the sort version has changed.
Windows Phone 8: This API is supported.
An example showing the use of this function can be found in NLS: Name-based APIs Sample.
Minimum supported client
|Windows Vista [desktop apps | Windows Store apps]|
Minimum supported server
|Windows Server 2008 [desktop apps | Windows Store apps]|
- National Language Support
- National Language Support Functions
- Custom Locales
- Handling Sorting in Your Applications
- Using Unicode Normalization to Represent Strings
- Security Considerations: International Features