wcscoll - Compare wide-character strings by using collation
const wchar_t *wcs1,
const wchar_t *wcs2 );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Points to a wide-character string. Points to a wide-character
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
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.
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.
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
Functions: strcoll(3), wcscmp(3), wcsxfrm(3)
[ Back ]