public member function
<locale>
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:
value | description |
-1 | The first sequence is less than the second (i.e., the first goes before the second in alphabetical order). |
0 | Both sequences are considered equal. |
1 | The 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.