wcscmp(S)

wcscoll, wcscmp, wcsncmp -- compare two wide character strings

Syntax

cc . . . -lc

#include <wchar.h>

int wcscoll(const wchar_t *ws1, const wchar_t *ws2);
int wcscmp(const wchar_t *ws1, const wchar_t *ws2);
int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);

Description

All these routines compare the two wide character strings pointed to by ws1 and ws2 and report which is greater if they are not identical.

wcsncmp(S) compares only the first n pairs of wide characters in the two wide character strings when both strings are more than n wide characters long; otherwise comparison stops when a terminating null is encountered in either string. The null wide character is always compared when encountered.

If the two strings are not identical, the first pair of mismatched wide-character codes found in the comparison determines the sign of the return value. For wcscmp(S) and wcsncmp( ), the encoding of characters in wide characters in a given locale and implementation determines the ordering of wide characters; For wcscoll(S), the ordering of wide characters is affected by the LC_COLLATE category of the current locale in the native language wide character set. In the "C" locale, wcscoll( ) is equivalent to wcscmp( ).

Return values

Upon successful completion, wcscoll( ) returns an integer greater than, equal to or less than zero, if the wide character string pointed to by ws1 is greater than, equal to or less than the wide character string pointed to by ws2 respectively in the native language wide character set.

When there is an error, wcscoll( ) may set errno, but no error return code is reserved.

Upon successful completion, wcscmp( ) returns an integer greater than, equal to or less than zero, if the wide character string pointed to by ws1 is greater than, equal to or less than the wide character string pointed to by ws2 respectively.

Upon successful completion, wcsncmp( ) returns an integer greater than, equal to or less than zero, if the substring of first n wide characters in the string pointed to by ws1 is greater than, equal to or less than that in the wide character string pointed to by ws2 respectively.

Diagnostics

wcscoll( ) will fail if:

[ENOSYS]: The routine is not supported.

Notes

To check if there is an error during the call to wcscoll( ), set errno to zero before the routine is called and check errno after returning from wcscoll( ). Assume that there is an error if errno is non-zero.

Standards conformance

wcscmp( ), wcsncmp( ) and wcscoll( ) are conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992.