strcoll

strcoll

Compare Two Character Strings Using Collating Sequence

Portability: ISO/ANSI C conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTIONS
IMPLEMENTATION
EXAMPLE

SYNOPSIS

#include <string.h>

int strcoll(const char *str1, const char *str2);

DESCRIPTION

strcoll compares two character strings ( str1 and str2 ) using the collating sequence or routines (or both) defined by the LC_COLLATE category of the current locale. The return value has the same relationship to 0 as str1 has to str2 . If two strings are equal up to the point where one of them terminates (that is, contains a null character), the longer string is considered greater.

Note that when the "POSIX" locale is in effect, either explicitly or by default, strcoll compares the strings according to the ASCII collating order rather than the EBCDIC order.

RETURN VALUE

The return value from strcoll is one of the following:

0 is returned if the two strings are equal.

less than 0 is returned if str1 compares less than str2 .

greater than 0 is returned if str1 compares greater than str2 .

No other assumptions should be made about the value returned by strcoll . In the " S370 " locale, the strcoll return value is the same as if the strcmp function were used to compare the strings.

CAUTIONS

If one of the arguments of strcoll is not properly terminated, a protection or addressing exception may occur.

IMPLEMENTATION

strcoll uses the following logic when comparing two strings:

strcoll calls the locale's strcoll function equivalent, if available, and returns its value. See LOCALE strcoll EQUIVALENT.
strcoll calls the locale's strxfrm function equivalent, if available, to transform the strings for a character-by-character comparison. See LOCALE strxfrm EQUIVALENT.
strcoll calls the library's double-byte collation routine with a standard double-byte collating sequence if the locale is a double-byte locale as determined from the LC_COLLATE category, no locale strcoll or strxfrm function is available, and no collation table is supplied.
strcoll uses a collation table to compare the two strings (which are then compared character by character) if the locale is a single-byte locale and has a collation table available.
strcoll calls the strcmp function to compare the strings and returns its value if none of the above are true.

EXAMPLE

#include <locale.h>
#include <string.h>
#include <stdio.h>

main()
{
   char *s1, *s2, *lcn;
   int result;

      /* Obtain locale name. */
   lcn = setlocale(LC_COLLATE, NULL);
   s1 = " A B C D";
   s2 = " A C B";

   result = strcoll(s1, s2);

   if (result == 0)
      printf("%s = %s in the "%s" locale", s1, s2, lcn);
   else
      if (result < 0)
         printf("%s < %s in the "%s" locale", s1, s2, lcn);
      else
         printf("%s > %s in the "%s" locale", s1, s2, lcn);
}

Chapter Contents
Previous
Next
Top of Page

`0`	is returned if the two strings are equal.
less than `0`	is returned if `str1` compares less than `str2` .
greater than `0`	is returned if `str1` compares greater than `str2` .