public member function
<locale>

std::collate::compare

int compare (const char_type* low1, const char_type* high1             const char_type* low2, const char_type* high2) const;
Compare character sequences
Compares the character sequence in the range [low1,high1) to the one in [low2,high2), returning 1 if the whole first sequence is considered greater than the second one, or -1 if it is considered less. Otherwise, if neither is considered greater o less than the other, they are considered equal and a value of 0 is returned.

Internally, this function simply calls the virtual protected member do_compare, which by default performs a simple lexicographical comparison for the standard specializations (comparing the char or wchar_t values directly).

A lexicographical comparison is the kind of comparison generally used to sort words alphabetically in dictionaries; It involves comparing sequentially the elements that have the same position in both ranges against each other until one element is not equivalent to the other. The result of comparing these first non-matching elements is the result of the lexicographical comparison.

Parameters

low1, high1
Pointer to the beginning and ending characters of the first sequence. The range used is [low1,high1), which contains all the characters between low1 and high1, including the character pointed by low1 but not the character pointed by high.
low2, high2
Pointer to the beginning and ending characters of the second sequence. The range used is [low2,high2).
Note that, for both ranges, null characters (if any) are also compared, and the function proceeds beyond them, until a mismatch is found or one of the ranges is exhausted.
Member type char_type is the facet's character type (defined as an alias of collate's template parameter, charT).

Return value

One of the following values:
valuedescription
-1The first sequence is less than the second (i.e., the first goes before the second in alphabetical order).
0Both sequences are considered equal.
1The first sequence is greater than the second (i.e., the first goes after the second in alphabetical order).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// collate::compare example
#include <iostream>       // std::cout
#include <string>         // std::string
#include <locale>         // std::locale, std::collate, std::use_facet

int main ()
{
  char first[]="STRAWBERRY";       // c-string
  std::string second="BLUEBERRY";  // standard string

  std::locale loc;                 // get "C" locale

  // get collate facet:
  const std::collate<char>& coll = std::use_facet<std::collate<char> >(loc);

  int result = coll.compare (first, first+10,
                             second.data(), second.data()+second.length());
  std::cout << first;
  switch (result) {
    case 1:
      std::cout << " is greater than "; break;
    case 0:
      std::cout << " is equal to "; break;
    case -1:
      std::cout << " is less than "; break;
  }
  std::cout << second << '\n';
  return 0;
}

Output:

STRAWBERRY is greater than BLUEBERRY


Data races

The facet object and up to all the characters in both ranges are accessed.

Exception safety

Strong guarantee: No side effects in case an exception is thrown.

See also