string::compare


public member function
int compare ( const string& str ) const;
int compare ( const char* s ) const;
int compare ( size_t pos1, size_t n1, const string& str ) const;
int compare ( size_t pos1, size_t n1, const char* s) const;
int compare ( size_t pos1, size_t n1, const string& str, size_t pos2, size_t n2 ) const;
int compare ( size_t pos1, size_t n1, const char* s, size_t n2) const;

Compare strings

Compares the content of this object (or a substring of it, known as compared (sub)string) to the content of a comparing string, which is formed according to the arguments passed.

The member function returns 0 if all the characters in the compared contents compare equal, a negative value if the first character that does not match compares to less in the object than in the comparing string, and a positive value in the opposite case.

Notice that for string objects, the result of a character comparison depends only on its character code (i.e., its ASCII code), so the result has some limited alphabetical or numerical ordering meaning.

For other basic_string class instantitations, the comparison depends on the specific traits::compare function, where traits is one of the class template parameters.

Parameters

str
string object with the content to be used as comparing string.
s
Array with a sequence of characters to be used as comparing string.
Except for the last member version, this is a null-terminated character sequence whose length is determined by the first occurrence of a null-character.
In the last member version, the length is not determined by any occurrence of null-characters but by parameter n2.
pos1
Position of the beginning of the compared substring, i.e. the first character in the object (in *this) to be compared against the comparing string.
n1
Length of the compared substring.
pos2
Position of a character in object str which is the beginning of the comparing string.
n2
Length in characters of the comparing string.


Return Value

0 if the compared characters sequences are equal, otherwise a number different from 0 is returned, with its sign indicating whether the object is considered greater than the comparing string passed as parameter (positive sign), or smaller (negative sign).

If either pos1 or pos2 is specified with a position greater than the size of the corresponding string object, an exception of type out_of_range is thrown.

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
 
// comparing apples with apples
#include <iostream>
#include <string>
using namespace std;

int main ()
{
  string str1 ("green apple");
  string str2 ("red apple");

  if (str1.compare(str2) != 0)
    cout << str1 << " is not " << str2 << "\n";

  if (str1.compare(6,5,"apple") == 0)
    cout << "still, " << str1 << " is an apple\n";

  if (str2.compare(str2.size()-5,5,"apple") == 0)
    cout << "and " << str2 << " is also an apple\n";

  if (str1.compare(6,5,str2,4,5) == 0)
    cout << "therefore, both are apples\n";

  return 0;
}


Output:
green apple is not red apple
still, green apple is an apple
and red apple is also an apple
therefore, both are apples


Basic template member declarations

( basic_string<charT,traits,Allocator> )
1
2
3
4
5
6
7
8
9
10
11
12
 
typedef typename Allocator::size_type size_type;
int compare ( const basic_string& str ) const;
int compare ( const charT* s ) const;
int compare ( size_type pos1, size_type n1,
               const basic_string& str ) const;
int compare ( size_type pos1, size_type n1,
               const charT* s) const;
int compare ( size_type pos1, size_type n1,
               const basic_string& str,
                size_t pos2, size_type n2 ) const;
int compare ( size_type pos1, size_type n1,
               const charT* s, size_type n2) const;


See also

string::find Find content in string (public member function)
string::rfind Find last occurrence of content in string (public member function)
string::substr Generate substring (public member function)