CompareStringOrdinal function (stringapiset.h)

Compares two Unicode strings to test binary equivalence.

Syntax

int CompareStringOrdinal(
  [in] _In_NLS_string_(cchCount1)LPCWCH lpString1,
  [in] int                              cchCount1,
  [in] _In_NLS_string_(cchCount2)LPCWCH lpString2,
  [in] int                              cchCount2,
  [in] BOOL                             bIgnoreCase
);

Parameters

[in] lpString1

Pointer to the first string to compare.

[in] cchCount1

Length of the string indicated by lpString1. The application supplies -1 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. The application supplies -1 if the string is null-terminated. In this case, the function determines the length automatically.

[in] bIgnoreCase

TRUE if the function is to perform a case-insensitive comparison, using the operating system uppercase table information. The application sets this parameter to FALSE if the function is to compare the strings exactly as they are passed in. Note that 1 is the only numeric value that can be used to specify a true value for this boolean parameter that does not result an invalid parameter error. Boolean values for this parameter work as expected.

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 value indicated by lpString1 is less than the value indicated by lpString2.
  • CSTR_EQUAL. The value indicated by lpString1 equals the value indicated by lpString2.
  • CSTR_GREATER_THAN. The value indicated by lpString1 is greater than the value 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_PARAMETER. Any of the parameter values was invalid.

Remarks

This function tests for binary equality, not linguistic equality. For information about the use of the function for ordinal sorting, see Handling Sorting in Your Applications.

Applications that are concerned with linguistic equality should use CompareString, CompareStringEx, lstrcmp, or lstrcmpi. For more information about linguistic sorting, see Handling Sorting in Your Applications

Starting with Windows 8: CompareStringOrdinal is declared in Stringapiset.h. Before Windows 8, it was declared in Winnls.h.

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

CompareString

CompareStringEx

Handling Sorting in Your Applications

National Language Support

National Language Support Functions

Security Considerations: International Features

Using Unicode Normalization to Represent Strings