FindStringOrdinal function

Locates a Unicode string (wide characters) in another Unicode string for a non-linguistic comparison.

Syntax

int FindStringOrdinal(
  DWORD   dwFindStringOrdinalFlags,
  LPCWSTR lpStringSource,
  int     cchSource,
  LPCWSTR lpStringValue,
  int     cchValue,
  BOOL    bIgnoreCase
);

Parameters

dwFindStringOrdinalFlags

Flags specifying details of the find operation. These flags are mutually exclusive, with FIND_FROMSTART being the default. The application can specify just one of the find flags.

Value Meaning
FIND_FROMSTART
Search the string, starting with the first character of the string.
FIND_FROMEND
Search the string in the reverse direction, starting with the last character of the string.
FIND_STARTSWITH
Test to find out if the value specified by lpStringValue is the first value in the source string indicated by lpStringSource.
FIND_ENDSWITH
Test to find out if the value specified by lpStringValue is the last value in the source string indicated by lpStringSource.

lpStringSource

Pointer to the source string, in which the function searches for the string specified by lpStringValue.

cchSource

Size, in characters excluding the terminating null character, of the string indicated by lpStringSource. The application must normally specify a positive number, or 0. The application can specify -1 if the source string is null-terminated and the function should calculate the size automatically.

lpStringValue

Pointer to the search string for which the function searches in the source string.

cchValue

Size, in characters excluding the terminating null character, of the string indicated by lpStringValue. The application must normally specify a positive number, or 0. The application can specify -1 if the string is null-terminated and the function should calculate the size automatically.

bIgnoreCase

TRUE if the function is to perform a case-insensitive comparison, and FALSE otherwise. The comparison is not a linguistic operation and is not appropriate for all locales and languages. Its behavior is similar to that for English.

Return Value

Returns a 0-based index into the source string indicated by lpStringSource if successful. If the function succeeds, the found string is the same size as the value of lpStringValue. A return value of 0 indicates that the function found a match at the beginning of the source string.

The function returns -1 if it does not succeed or if it does not find the search string. 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 not valid.
  • ERROR_INVALID_PARAMETER. Any of the parameter values was invalid.
  • ERROR_SUCCESS. The action completed successfully but yielded no results.

Remarks

Since FindStringOrdinal provides a binary comparison, it does not return linguistically appropriate results. The ordinal comparison might be mistaken for English sorting behavior. However, it does not find matches when characters vary by linguistically insignificant amounts. See Sorting for information about choosing an appropriate sorting function.

In contrast to NLS functions that return 0 for failure, this function returns -1 if it fails. On success, it returns a 0-based index. Use of this index helps the function avoid off-by-one errors and one-character buffer overruns.

This function is one of the few NLS functions that calls SetLastError even when it succeeds. It makes this call to clear the last error in a thread when it fails to match the search string. This clears the value returned by GetLastError.

Starting with Windows 8: FindStringOrdinal is declared in Libloaderapi.h. Before Windows 8, it was declared in Winnls.h.

Requirements

   
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 R2 [desktop apps | UWP apps]
Target Platform Windows
Header libloaderapi.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See Also

FindNLSString

FindNLSStringEx

Handling Sorting in Your Applications

National Language Support

National Language Support Functions