`strcoll` functions

Article
01/31/2023

Each of the strcoll and wcscoll functions compares two strings according to the LC_COLLATE category setting of the locale code page currently in use. Each of the _mbscoll functions compares two strings according to the multibyte code page currently in use. Use the coll functions for string comparisons when there's a difference between the character set order and the lexicographic character order in the current code page if the difference is of interest for the comparison. Use the corresponding cmp functions to test only for string equality.

strcoll Functions

SBCS	Unicode	MBCS	Description
`strcoll`	`wcscoll`	`_mbscoll`	Collate two strings
`_stricoll`	`_wcsicoll`	`_mbsicoll`	Collate two strings (case insensitive)
`_strncoll`	`_wcsncoll`	`_mbsncoll`	Collate first `count` characters of two strings
`_strnicoll`	`_wcsnicoll`	`_mbsnicoll`	Collate first `count` characters of two strings (case-insensitive)

Remarks

The single-byte character (SBCS) versions of these functions (strcoll, stricoll, _strncoll, and _strnicoll) compare string1 and string2 according to the LC_COLLATE category setting of the current locale. These functions differ from the corresponding strcmp functions in that the strcoll functions use locale code page information that provides collating sequences. For string comparisons in locales in which the character set order and the lexicographic character order differ, the strcoll functions should be used rather than the corresponding strcmp functions. For more information on LC_COLLATE, see setlocale.

For some code pages and corresponding character sets, the order of characters in the character set may differ from the lexicographic character order. In the "C" locale, it isn't the case: the order of characters in the ASCII character set is the same as the lexicographic order of the characters. However, in certain European code pages, for example, the character 'a' (value 0x61) precedes the character 'ä' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. To perform a lexicographic comparison in such an instance, use strcoll rather than strcmp. Alternatively, you can use strxfrm on the original strings, then use strcmp on the resulting strings.

strcoll, stricoll, _strncoll, and _strnicoll automatically handle multibyte-character strings according to the locale code page currently in use, as do their wide-character (Unicode) counterparts. The multibyte-character (MBCS) versions of these functions, however, collate strings on a character basis according to the multibyte code page currently in use.

Because the coll functions collate strings lexicographically for comparison, whereas the cmp functions simply test for string equality, the coll functions are much slower than the corresponding cmp versions. Therefore, the coll functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison.

`strcoll` functions