wcscoll() — Language Collation String Comparison

Format

#include <wchar.h>
int wcscoll (const wchar_t *wcs1, const wchar_t *wcs2);

Language Level

XPG4

Threadsafe

Yes

Locale Sensitive

The behavior of this function might be affected by the LC_COLLATE category of the current locale if LOCALETYPE(*LOCALE) is specified on the compilation command. The behavior of this function might also be affected by the LC_UNI_COLLATE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Wide Character Function

See Wide Characters for more information.

Description

The wcscoll() function compares the wide-character strings pointed to by wcs1 and wcs2, both interpreted as appropriate to the LC_COLLATE category of the current locale (or the LC_UNI_COLLATE category if a UNICODE LOCALETYPE was specified).

Return Value

The wcscoll() function returns an integer value indicating the relationship between the strings, as follows:

Table 1. Return values of `wcscoll()`
Value	Meaning
Less than 0	wcs1 less than wcs2
0	wcs1 equivalent to wcs2
Greater than 0	wcs1 greater than wcs2

If wcs1 or wcs2 contain characters outside the domain of the collating sequence, the wcscoll() function sets errno to EINVAL. If an error occurs, the wcscoll() function sets errno to an nonzero value. There is no error return value.

Example

This example uses the default locale.

#include <stdio.h>
#include <wchar.h>
 
int main(void)
{
   int result;
   wchar_t *wcs1 = L"first_wide_string";
   wchar_t *wcs2 = L"second_wide_string";
 
   result = wcscoll(wcs1, wcs2);
 
   if ( result == 0)
      printf("\"%S\" is identical to \"%S\"\n", wcs1, wcs2);
   else if ( result < 0)
      printf("\"%S\" is less than \"%S\"\n", wcs1, wcs2);
   else
      printf("\"%S\" is greater than \"%S\"\n", wcs1, wcs2);
}