Expand Minimize

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.

Syntax


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
);

Parameters

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.

FlagMeaning
LINGUISTIC_IGNORECASE

Ignore case, as linguistically appropriate.

LINGUISTIC_IGNOREDIACRITIC

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.

NORM_IGNORECASE

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.

NORM_IGNOREKANATYPE

Do not differentiate between hiragana and katakana characters. Corresponding hiragana and katakana characters compare as equal.

NORM_IGNORENONSPACE

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.

NORM_IGNORESYMBOLS

Ignore symbols and punctuation.

NORM_IGNOREWIDTH

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.

NORM_LINGUISTIC_CASING

Use linguistic rules for casing, instead of file system rules (default).

SORT_DIGITSASNUMBERS

Windows 7: Treat digits as numbers during sorting, for example, sort "2" before "10".

SORT_STRINGSORT

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]

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.

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.

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.

Windows Phone 8.1: This API is supported.

Examples

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

Requirements

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Stringapiset.h (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

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
CompareString

 

 

Community Additions

ADD
Show:
© 2014 Microsoft