Open System Services Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

OSS Library Calls (w - z) wcscoll(3)
NAME
wcscoll - Compares wide-character strings using collation information
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL
G-series native OSS processes: /G/system/sysnn/zcrtlsrl
H-series and J-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
32-bit H-series and J-series OSS processes: /G/system/zdllnnn/zcrtldll
64-bit H-series and J-series OSS processes: /G/system/zdllnnn/ycrtldll
SYNOPSIS
#include <wchar.h>
int wcscoll(
const wchar_t *wcs1,
const wchar_t *wcs2);
PARAMETERS
wcs1 Points to a wide-character string.
wcs2 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 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 their collation values, while the latter compares wide characters based on
their ordinal values. 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 you are doing multiple comparisons based on the current locale’s collation values using the
same set of text strings, the wcsxfrm( ) transformation function in conjunction with the
wcscmp( ) function may be more efficient than using the wcscoll( ) collation function 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 multi-level collation. In comparison,
the collation function stops comparing characters at the first inequality. These efficiency
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
Upon 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.
527187-017 Hewlett-Packard Company 8−7