*** UNIX MANUAL PAGE BROWSER ***

wcscoll(3) Library Functions Manual wcscoll(3) NAME wcscoll - Compares wide-character strings by using collation informa- tion LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <wchar.h> int wcscoll( const wchar_t *wcs1, const wchar_t *wcs2); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: wcscoll(): ISO C, XPG4 Refer to the standards(5) reference page for more information about in- dustry 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 or- der, while the latter compares wide characters based on machine collat- ing 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 lo- cale's collation values and uses the same set of text strings, the wc- sxfrm() transformation function in conjunction with the wcscmp() func- tion 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 inequal- ity. These tradeoffs make the most efficient method for a specific ap- plication 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, re- turns 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 oc- curred. 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)