C++ <cstring> - strcoll() Function

The C++ <cstring> strcoll() function is used to compare two null-terminated byte strings according to the current locale as defined by the LC_COLLATE category. The function starts comparing the first pair of characters of each string and continues comparing until the pair of characters are different or until a terminating null-character is reached.

LC_COLLATE is used to select collation order of the C locale. The collation order is the dictionary order. Different languages around the world use different schemes for sorting or ordering textual values. For example, "ch" in Czech follows "h" and precedes "i", and "dzs" in Hungarian follows "dz" and precedes "g".

Syntax

int strcoll ( const char * lhs, const char * rhs );

Parameters

`lhs`	Specify pointer to the first null-terminated byte string to compare.
`rhs`	Specify pointer to the second null-terminated byte string to compare.

Return Value

Based on the value of lhs and rhs, the function returns the following:

Negative value if lhs appears before rhs.
Zero if lhs and rhs compare equal.
Positive value if lhs appears after rhs.

Example: Value returned by function = 0

The example below shows the usage of strcoll() function.

#include <iostream>
#include <clocale>
#include <cstring>
using namespace std;
 
int main (){
  char str1[20] = "Hello";
  char str2[20] = "Hello";
  
  //using LC_COLLATE of Environment's 
  //default locale
  setlocale(LC_COLLATE,"");

  //comparing str1 and str2
  int retval = strcoll(str1, str2);

  //displaying the result
  if(retval != 0)
    cout<<"str1 and str2 are not equal.\n";
  else
    cout<<"str1 and str2 are equal.\n";
 
  cout<<"Value returned by the function: "<<retval<<"\n";

  return 0;
}

The output of the above code will be:

str1 and str2 are equal.
Value returned by the function: 0

Example: Value returned by function < 0

Lets consider this example where the returned value is less than zero.

#include <iostream>
#include <clocale>
#include <cstring>
using namespace std;
 
int main (){
  char str1[20] = "Hello";
  char str2[20] = "World";
  
  //using LC_COLLATE of Environment's 
  //default locale
  setlocale(LC_COLLATE,"");

  //comparing str1 and str2
  int retval = strcoll(str1, str2);

  //displaying the result
  if(retval != 0)
    cout<<"str1 and str2 are not equal.\n";
  else
    cout<<"str1 and str2 are equal.\n";

  cout<<"Value returned by the function: "<<retval<<"\n";

  return 0;
}

The output of the above code will be:

str1 and str2 are not equal.
Value returned by the function: -15

Example: Value returned by function > 0

Lets consider another example where the returned value is greater than zero.

#include <iostream>
#include <clocale>
#include <cstring>
using namespace std;
 
int main (){
  char str1[20] = "Hello";
  char str2[20] = "Apple";
  
  //using LC_COLLATE of Environment's 
  //default locale
  setlocale(LC_COLLATE,"");

  //comparing str1 and str2
  int retval = strcoll(str1, str2);

  //displaying the result
  if(retval != 0)
    cout<<"str1 and str2 are not equal.\n";
  else
    cout<<"str1 and str2 are equal.\n";

  cout<<"Value returned by the function: "<<retval<<"\n";

  return 0;
}

The output of the above code will be:

str1 and str2 are not equal.
Value returned by the function: 7

❮ C++ <cstring> Library