Content-type: text/html Man page of wcscoll

wcscoll

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

wcscoll - Compares wide-character strings by using collation information  

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 standards as follows:

wcscoll(): ISO C, XPG4

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 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 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

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.  

RELATED INFORMATION

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

Standards: standards(5) delim off


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:32 GMT, October 02, 2010