C in a Nutshell

Name

wcscoll

Synopsis

Collates two wide strings

#include <wchar.h>
intwcscoll( const wchar_t *s1, const wchar_t *s2 );

Like wcscmp(), the wcscoll() function performs a wide-character-by-wide-character comparison of the two strings, s1 and s2. However, where wcscmp() just compares unsigned character values, wcscoll() can apply a locale-specific set of rules in comparing strings. The value of the locale information category LC_COLLATE determines the applicable rule set, and can be changed by the setlocale() function. The return value of wcscoll() indicates the relation between the two wide strings as follows. If the return value is:

Zero

The two string are equal.

Greater than zero

The string addressed by s1 is greater than that addressed by s2.

Less than zero

The string addressed by s1 is less than that addressed by s2.

Example

wchar_t *samples[ ] = { L"anejo", L"añeja",};

setlocale( LC_COLLATE, "es_US.UTF-8" );

int result = wcscoll( samples[0], samples[1] );

wprintf( L"In the locale %s, ", setlocale( LC_COLLATE, NULL ));

if ( result == 0 )
  wprintf( L"the wide strings \"%ls\" and \"%ls\" are alphabetically "
           "equivalent.\n", samples[0], samples[1] );
else if ( result < 0 )
  wprintf( L"the wide string \"%ls\" precedes \"%ls\" alphabetically.\n",
           samples[0], samples[1] );
else if ( result > 0 )
  wprintf( L"the wide string \"%ls\" comes after \"%ls\" alphabetically.\n",
           samples[0], samples[1] );

See Also

wcscmp(), wcsncmp(), and wcsxfrm(); strcoll(), strcmp(), strncmp(), and strxfrm()