wcscoll(3)						     Library Functions Manual							wcscoll(3)

NAME

       wcscoll - Compares wide-character strings by using collation information

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       #include <wchar.h>

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

STANDARDS

       Interfaces documented on this reference page conform to industry standards 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
       specified 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  out-
       side 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 collating 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
       characters in the string for each level of a multilevel collation. In comparison, the collation function stops comparing characters at  the
       first inequality. These tradeoffs make the most efficient method for a specific 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-charac-
       ter 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.

RELATED INFORMATION

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

       Standards: standards(5) delim off

																	wcscoll(3)