strcoll() — Compare strings

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3	both

Format

#include <string.h>

int strcoll(const char *string1, const char *string2);

General description

Compares the string pointed to by string1 against the string pointed to by string2, both interpreted according to the information in the LC_COLLATE category of the current locale.

Returned value

strcoll() returns a value indicating the relationship between the strings, as listed below.

Value: Meaning
< 0: string pointed to by string1 less than string pointed to by string2
= 0: string pointed to by string1 equivalent to string pointed to by string2
> 0: string pointed to by string1 greater than string pointed to by string2

Notes:

The strcoll() function may need to allocate additional memory to perform the comparison algorithm specified in the LC_COLLATE. If the memory request cannot be satisfied (by malloc()), strcoll() fails.
If the locale supports double-byte characters (MB_CUR_MAX specified as 4), the strcoll() function validates the multibyte characters, whereas previously the strcoll() function did not validate the string. The strcoll() function will fail if the string contains invalid multibyte characters.
If MB_CUR_MAX is specified as 4, but the charmap file does not specify the DBCS characters, the DBCS characters will collate after the single-byte characters.

Example

CELEBS37

⁄* CELEBS37                                      

   This example compares the two strings passed to main.                        
                                                                                
 *⁄                                                                             
#include <stdio.h>                                                              
#include <string.h>                                                             
                                                                                
int main(int argc, char ** argv)                                                
{                                                                               
  int  result;                                                                  
                                                                                
  if ( argc != 3 ) {                                                            
    printf( "Usage: %s string1 string2\n", argv[0] );                           
  }                                                                             
  else {                                                                        
                                                                                
    result = strcoll( argv[1], argv[2] );                                       
                                                                                
    if ( result == 0 )                                                          
      printf( "\"%s\" is identical to \"%s\"\n", argv[1], argv[2] );            
    else if ( result < 0 )                                                      
      printf( "\"%s\" is less than \"%s\"\n", argv[1], argv[2] );               
    else                                                                        
      printf( "\"%s\" is greater than \"%s\"\n", argv[1], argv[2] );            
  }                                                                             
}

Output

If the input is the strings “firststring” and “secondstring”, then the expected output is:

"firststring" is less than "secondstring"