ILE C/C++ Run-Time Library Functions


wcscoll() --Language Collation String Comparison

Format

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

Language Level: XPG4

Threadsafe: Yes.

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 LOCALTYPE was specified).

Note:
This function is not available when LOCALETYPE(*CLD) is specified on the compilation command.

The behavior of this wide-character function is affected by the LC_COLLATE category of the current locale (or the LC_UNI_COLLATE category if a UNICODE LOCALTYPE was specified).

Return Value

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

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 that uses wcscoll()

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);
}

Related Information


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]