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

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

// 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

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