Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

CompareStringEx function

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.


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.


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]

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.

lpReserved [in, optional]

Reserved; must set to NULL.

lParam [in, optional]

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.

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: 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.

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.


An example showing the use of this function can be found in NLS: Name-based APIs Sample.


Minimum supported client

Windows Vista [desktop apps | UWP apps]

Minimum supported server

Windows Server 2008 [desktop apps | UWP apps]

Minimum supported phone

Windows Phone 8


Stringapiset.h (include Windows.h)





See also

National Language Support
National Language Support Functions
Custom Locales
Handling Sorting in Your Applications
Using Unicode Normalization to Represent Strings
Security Considerations: International Features



© 2018 Microsoft