wcscoll(3)wcscoll(3)NAMEwcscoll - 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)