wcscoll or wcscoll_l Subroutine

Purpose

Compares wide character strings.

Library

Standard C Library (libc.a)

Syntax

#include <string.h>

int wcscoll ( WcString1,  WcString2)
const wchar_t *WcString1, *WcString2;

int wcscoll_l ( WcString1,  WcString2, Locale)
const wchar_t *WcString1, *WcString2;
locale_t Locale;

Description

The wcscoll and wcscoll _l subroutines compare the two wide-character strings pointed to by the WcString1 and WcString2 parameters based on the collation values specified by the LC_COLLATE environment variable of the current locale or in the locale represented by Locale.

Note: The wcscoll subroutine differs from the wcscmp subroutine in that the wcscoll subroutine compares wide characters based on their collation values, while the wcscmp subroutine compares wide characters based on their ordinal values. The wcscoll subroutine uses more time than the wcscmp subroutine because it obtains the collation values from the current locale.

The wcscoll and wcscoll _l subroutine may be unsuccessful if the wide character strings specified by the WcString1 or WcString2 parameter contains characters outside the domain of the current collating sequence or in the locale represented by the Locale collating sequence.

Parameters

Item Description
WcString1 Points to a wide-character string.
WcString2 Points to a wide-character string.
Locale Specifies the locale in which character has to be converted.

Return Values

The wcscoll and wcscoll _l subroutine returns the following values:

Item Description
< 0 The collation value of the WcString1 parameter is less than that of the WcString2 parameter.
=0 The collation value of the WcString1 parameter is equal to that of the WcString2 parameter.
>0 The collation value of the WcString1 parameter is greater than that of the WcString2 parameter.

The wcscoll and wcscoll _l subroutines indicate error conditions by setting the errno global variable. However, there is no return value to indicate an error. To check for errors, the errno global variable should be set to 0, then checked upon return from the wcscoll, and wcscoll _l subroutines. If the errno global variable is nonzero, an error occurred.

Error Codes

Item Description
EINVAL The WcString1 or WcString2 arguments contain wide-character codes outside the domain of the collating sequence.