Technical Reference: Base Operating System and Extensions, Volume 2

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

Description

The wcscoll subroutine compares 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.

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

Parameters

WcString1	Points to a wide-character string.
WcString2	Points to a wide-character string.

Return Values

The wcscoll subroutine returns the following values:

< 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 subroutine indicates 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 subroutine. If the errno global variable is nonzero, an error occurred.

Error Codes

EINVAL

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

Related Information

The wcscmp (wcscat, wcschr, wcscmp, wcscpy, or wcscspn Subroutine) subroutine.

Subroutines Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview and Understanding Wide Character String Collation Subroutines in AIX 5L Version 5.2 National Language Support Guide and Reference.