Locale-Sensitive C/C++ Collation Function

int strcoll(const char *string1, const char *string2);

int wcscoll(const wchar_t *string1, const wchar_t *string2);

int _mbscoll(const unsigned char *string1, const unsigned char *string2);

int _tcscoll(const _TXCHAR *string1, const _TXCHAR *string2);

Internationalization (I18n) Function Overview

The strcoll function compares two null-terminated strings, interpreting the strings according to the LC_COLLATE category of the current locale. It returns zero if the strings are equal, a negative number if string1 is less than string2 and a positive number if string1 is greater than string2.

wcscoll is the wide character version of strcoll. It compares the two wide-character string arguments.

Supported on Windows platforms only, _mbscoll is the multibyte version of strcoll. It compares two multibyte-character strings, using the current multibyte code page.

_tcscoll is the Windows-only Generic version of the function; with the _MBCS or _UNICODE compiler flags determining its mapping to either _mbscoll or wcscoll.

I18n Issues

Use the appropriate version of the function as required for internationalization support, noting the following:

On Windows, the single-byte version of the function, strcoll, should not be used for collation because it will only work with single-byte characters. Instead, the appropriate multibyte or generic version should be called.

The locale for which this function draws its collation rules can be set via setlocale.

In the case of the Windows-only _mbscoll function or its generic representation, _tcscoll, ensure that the multibyte code page is set correctly. See _setmbcp for more information on setting up the multibyte code page.

Recommended Replacements*

ANSI UTF-8	strcoll
ANSI UTF-16	wcscoll
Microsoft Windows MBCS	_mbscoll
Microsoft Windows Unicode	wcscoll
Microsoft Windows Generic	_tcscoll

Performance Issues

Although use of a strcoll function is the simplest way to internationalize existing collation-based strcmp calls, there is a disadvantage. The *coll() functions are typically slower than the *cmp() functions because they often rely on tables of collation information.

If you can't or don't want to pay the performance price, consider using a strxfrm function instead. This function transforms data and returns strings of characters that can then be passed into a strcmp function to be sorted. In effect, it assigns numeric values to characters using the current locale's sorting rules so that a strcmp function can do numeric comparisons.

Collation Functions