NAME    [Toc]    [Back]

       wcscoll  -  Compare wide-character strings by using collation
 information

SYNOPSIS    [Toc]    [Back]

       #include <wchar.h>

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

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       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    [Toc]    [Back]

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

DESCRIPTION    [Toc]    [Back]

       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  widecharacter
 strings specified by the wcs1 or wcs2 parameters
       contain characters outside the domain of the current  collating
 sequence.

NOTES    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

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

       Standards: standards(5)



                                                       wcscoll(3)