STRCOLL(3,L) AIX Technical Reference STRCOLL(3,L)
-------------------------------------------------------------------------------
strcoll, strncoll, strxfrm, mbscoll, mbsncoll, wcscoll, wcsncoll
PURPOSE
Perform string and array comparisons using collating information.
SYNTAX
#include <string.h>
int strcoll (s1, s2) int mbsncoll (s1, s2)
const char *s1, *s2; const char *s1, *s2;
int strncoll (s1, s2, n) int wcscoll (s1, s2)
const char *s1, *s2; const wchar_t *s1, *s2;
size_t n;
int wcsncoll (s1, s2, n)
size_t strxfrm (s1, s2, n); const wchar_t *s1, *s2;
char *s1; size_t n;
const char *s2;
size_t n;
int mbscoll (s1, s2)
const char *s1, *s2;
DESCRIPTION
All of these subroutines except strxfrm perform file code and process code
string and array comparisons using collating information. The strxfrm
subroutine transforms strings. The s1 and s2 variables are pointers to file
code strings.
The strcoll subroutine compares the string pointed to by s1 to the string
pointed to by s2, when both are interpreted according to the LC_COLLATE
category of the current locale.
The strncoll subroutine compares the string pointed to by s1 to the string
pointed to by s2 up to n characters, or when a terminating NULL is reached,
when both strings are interpreted according to the LC_COLLATE category of the
current locale.
The strcoll and the strncoll subroutines are identical to the wcscoll and the
wcsncoll subroutines except that the latter compare process code strings
instead of file code strings.
Processed November 7, 1990 STRCOLL(3,L) 1
STRCOLL(3,L) AIX Technical Reference STRCOLL(3,L)
The strxfrm subroutine transforms the string pointed to by s2 and places the
resulting string into the array pointed to by s1. If the strcmp subroutine is
called to compare the two transformed strings, strxfrm returns a value greater
than, equal to or less than zero. This value corresponds to the result
produced by calling the strcoll subroutine to compare the same two original
strings. No more than n characters are placed into the resulting array pointed
to by s1, including the terminating NULL character. If n is zero, s1 is
permitted to be a NULL pointer. If copying takes place between objects that
overlap, the behavior is undefined.
The mbscoll subroutine compares the multibyte string pointed to by s1 to the
multibyte string pointed to by s2, when both are interpreted according to the
LC_COLLATE category of the current locale.
The mbsncoll subroutine compares the multibyte string pointed to by s1 to the
multibyte string pointed to by s2 up to n characters, or if a terminating NULL
is reached, when both are interpreted according to the LC_COLLATE category of
the current locale.
The mbscoll and mbsncoll subroutines have no shift states. Both input strings
must begin in the initial shift state.
The mbscoll and mbsncoll subroutines are identical to the wcscoll and wcsncoll
subroutines except that the latter compare process code strings instead of file
code strings.
The wcscoll subroutine compares the array pointed to by s1 to the array pointed
to by s2, both interpreted as wide character codes converted from multibyte
characters and in accordance with the LC_COLLATE category of the current
locale.
The wcsncoll subroutine compares the array pointed to by s1 to the array
pointed to by s2 up to n characters. Both strings are interpreted as wide
character codes, converted from multibyte characters and in accordance with the
LC_COLLATE category of the current locale.
RETURN VALUE
The strcoll, strncoll, mbscoll, and mbsncoll subroutines return an integer
greater than, equal to, or less than zero depending on whether the string
pointed to by s1 is greater than, equal to or less than the string pointed to
by s2 when both are interpreted according to the LC_COLLATE category of the
current locale.
The strxfrm subroutine returns the length of the transformed string (not
including the terminating NULL character). If the value returned is n or more,
the contents of the array pointed to by s1 are indeterminate.
The wcscoll and wcsncoll subroutines return an integer greater than, equal to,
or less than zero depending on whether the array pointed to by s1 is greater
than, equal to or less than the wide character array pointed to by s2, when
Processed November 7, 1990 STRCOLL(3,L) 2
STRCOLL(3,L) AIX Technical Reference STRCOLL(3,L)
both are interpreted according to the LC_COLLATE category of the current
locale.
ERROR CONDITIONS
The strcoll, strncoll, and strxform subroutines will fail if the following is
true:
EINVAL The s1 and s2 arguments contain characters outside the domain of the
collating sequence.
RELATED INFORMATION
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 STRCOLL(3,L) 3