Expand Minimize

CompareString function

Compares two character strings, for a locale specified by identifier.

Caution  Using CompareString incorrectly can compromise the security of your application. Strings that are not compared correctly can produce invalid input. For example, the function can raise security issues when used for a non-linguistic comparison, because two strings that are distinct in their binary representation can be linguistically equivalent. The application should test strings for validity before using them, and should provide error handlers. For more information, see Security Considerations: International Features.

Note  For compatibility with Unicode, your applications should prefer CompareStringEx or the Unicode version of CompareString. Another reason for preferring CompareStringEx is that Microsoft is migrating toward the use of locale names instead of locale identifiers for new locales, for interoperability reasons. Any application that will be run only on Windows Vista and later should use CompareStringEx.

Syntax


int CompareString(
  _In_  LCID Locale,
  _In_  DWORD dwCmpFlags,
  _In_  LPCTSTR lpString1,
  _In_  int cchCount1,
  _In_  LPCTSTR lpString2,
  _In_  int cchCount2
);

Parameters

Locale [in]

Locale identifier of the locale used for the comparison. You can use the MAKELCID macro to create a locale identifier or use one of the following predefined values.

dwCmpFlags [in]

Flags that indicate how the function compares the two strings. For detailed definitions, see the dwCmpFlags parameter of CompareStringEx.

lpString1 [in]

Pointer to the first string to compare.

cchCount1 [in]

Length of the string indicated by lpString1, excluding the terminating null character. This value represents bytes for the ANSI version of the function and wide characters for the Unicode version. 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. This value represents bytes for the ANSI version of the function and wide characters for the Unicode version. The application can supply a negative value if the string is null-terminated. In this case, the function determines the length automatically.

Return value

Returns the values described for CompareStringEx.

Remarks

See Remarks for CompareStringEx.

If your application is calling the ANSI version of CompareString, the function converts parameters via the default code page of the supplied locale. Thus, an application can never use CompareString to handle UTF-8 text.

Normally, for case-insensitive comparisons, CompareString maps the lowercase "i" to the uppercase "I", even when the locale is Turkish or Azeri. The NORM_LINGUISTIC_CASING flag overrides this behavior for Turkish or Azeri. If this flag is specified in conjunction with Turkish or Azeri, LATIN SMALL LETTER DOTLESS I (U+0131) is the lowercase form of LATIN CAPITAL LETTER I (U+0049) and LATIN SMALL LETTER I (U+0069) is the lowercase form of LATIN CAPITAL LETTER I WITH DOT ABOVE (U+0130).

Starting with Windows 8: The ANSI version of the function is declared in Winnls.h, and the Unicode version is declared in Stringapiset.h. Before Windows 8, both versions were declared in Winnls.h.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winnls.h (see Remarks) (include Windows.h);
Stringapiset.h (see Remarks) (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

Unicode and ANSI names

CompareStringW (Unicode) and CompareStringA (ANSI)

See also

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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft