wcscoll(3)							    wcscoll(3)

NAME
       wcscoll - Compare wide-character strings by using collation information

SYNOPSIS
       #include <wchar.h>

       int wcscoll(
	       const wchar_t *wcs1,
	       const wchar_t *wcs2 );

LIBRARY
       Standard C Library (libc)

STANDARDS
       Interfaces  documented on this reference page conform to industry stan‐
       dards as follows:

       wcscoll(): XSH5.0

       Refer to the standards(5) reference page	 for  more  information	 about
       industry standards and associated tags.

PARAMETERS
       Points to a wide-character string.  Points to a wide-character string.

DESCRIPTION
       The  wcscoll() function compares the two wide-character strings pointed
       to by the wcs1 and wcs2 parameters based on the collation values speci‐
       fied by the LC_COLLATE category of the program's current locale.

       The  wcscoll()  function	 may  be  unsuccessful	if  the wide-character
       strings specified by the wcs1 or	 wcs2  parameters  contain  characters
       outside the domain of the current collating sequence.

NOTES
       The  wcscoll()  function differs from the wcscmp() function in that the
       former compares wide characters	based  on  locale-dependent  collating
       order,  while the latter compares wide characters based on machine col‐
       lating order. The wcscoll() function is more expensive in terms of time
       than  the  wcscmp()  function  because of the overhead of obtaining the
       collation values from the current locale.

       If an application  does	multiple  comparisons  based  on  the  current
       locale's	 collation  values  and uses the same set of text strings, the
       wcsxfrm() transformation function  in  conjunction  with	 the  wcscmp()
       function	 may  be more efficient than the wcscoll() collation function.
       This is because the string is transformed based on  the	locale	tables
       only  once. However, the transformation function must convert all char‐
       acters in the string for each level of a multilevel collation. In  com‐
       parison, the collation function stops comparing characters at the first
       inequality. These tradeoffs make the most efficient method for  a  spe‐
       cific  application  dependent  on the number of repeated comparisons of
       strings within the set, the number of collation levels for the  current
       locale, and the values of the strings within the set.

RETURN VALUES
       On  successful  completion,  the	 wcscoll() function returns an integer
       whose value is greater than 0 (zero) if	wcs1  is  greater  than	 wcs2,
       returns	0 (zero) if the strings are equivalent, and returns an integer
       whose value is less than 0 (zero) if wcs1 is less than wcs2.  The  sign
       of  a  nonzero return value is determined by the sign of the difference
       between the collation weights of the first pair of wide-character codes
       that differ in the objects being compared.

       The  wcscoll()  function	 indicates  error conditions by setting errno;
       however, there is no return value to indicate an error.	To  check  for
       errors,	errno should be set to 0 (zero), then checked upon return from
       the wcscoll()  function.	 If  errno  has	 a  nonzero  value,  an	 error
       occurred.

ERRORS
       If the following condition occurs, the wcscoll() function sets errno to
       the corresponding value: The wide-character string pointed  to  by  the
       wcs1  or	 wcs2 string contained characters outside of the domain of the
       collating sequence.

SEE ALSO
       Functions: strcoll(3), wcscmp(3), wcsxfrm(3)

       Standards: standards(5)

								    wcscoll(3)

Vote for polarhome