[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

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

National Language Support Overview for Programming, Subroutines Overview, Understanding Wide Character String Collation Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]