std::basic_string::compare

string (1)	int compare (const basic_string& str) const;
substrings (2)	int compare (size_type pos, size_type len, const basic_string& str) const;int compare (size_type pos, size_type len, const basic_string& str, size_type subpos, size_type sublen) const;
c-string (3)	int compare (const charT* s) const;int compare (size_type pos, size_type len, const charT* s) const;
buffer (4)	int compare (size_type pos, size_type len, const charT* s, size_type n) const;

string (1)	int compare (const basic_string& str) const noexcept;
substrings (2)	int compare (size_type pos, size_type len, const basic_string& str) const;int compare (size_type pos, size_type len, const basic_string& str, size_type subpos, size_type sublen) const;
c-string (3)	int compare (const charT* s) const;int compare (size_type pos, size_type len, const charT* s) const;
buffer (4)	int compare (size_type pos, size_type len, const charT* s, size_type n) const;

string (1)	int compare (const basic_string& str) const noexcept;
substrings (2)	int compare (size_type pos, size_type len, const basic_string& str) const;int compare (size_type pos, size_type len, const basic_string& str, size_type subpos, size_type sublen = npos) const;
c-string (3)	int compare (const charT* s) const;int compare (size_type pos, size_type len, const charT* s) const;
buffer (4)	int compare (size_type pos, size_type len, const charT* s, size_type n) const;

Compare strings

Compares the value of the basic_string object (or a substring) to the sequence of characters specified by its arguments.

The compared string is the value of the basic_string object or -if the signature used has a pos and a len parameters- the substring that begins at its character in position pos and spans len characters.

This string is compared to a comparing string, which is determined by the other arguments passed to the function.

The sequences are compared using traits_type::compare.

Parameters

str: Another basic_string object of the same type (with the same class template arguments charT, traits and Alloc), used entirely (or partially) as the comparing string.
pos: Position of the first character in the compared string.
If this is greater than the string length, it throws out_of_range.
Note: The first character is denoted by a value of 0 (not 1).
len: Length of compared string (if the string is shorter, as many characters as possible).
A value of basic_string::npos indicates all characters until the end of the string.
subpos, sublen: Same as pos and len above, but for the comparing string.
s: Pointer to an array of characters.
If argument n is specified (4), the first n characters in the array are used as the comparing string.
Otherwise (3), a null-terminated sequence is expected: the length of the sequence with the characters to use as comparing string is determined by the first occurrence of a null character.
n: Number of characters to compare.

charT is basic_string's character type (i.e., its first template parameter).
Member type size_type is an unsigned integral type.

Return Value

Returns a signed integral indicating the relation between the strings:

value	relation between compared string and comparing string
`0`	They compare equal
`<0`	Either the value of the first character that does not match is lower in the compared string, or all compared characters match but the compared string is shorter.
`>0`	Either the value of the first character that does not match is greater in the compared string, or all compared characters match but the compared string is longer.

Example

// comparing apples with apples
#include <iostream>
#include <string>
int main ()
{
 std::string str1 ("green apple");
 std::string str2 ("red apple");
 if (str1.compare(str2) != 0)
 std::cout << str1 << " is not " << str2 << '\n';
 if (str1.compare(6,5,"apple") == 0)
 std::cout << "still, " << str1 << " is an apple\n";
 if (str2.compare(str2.size()-5,5,"apple") == 0)
 std::cout << "and " << str2 << " is also an apple\n";
 if (str1.compare(6,5,str2,4,5) == 0)
 std::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

Complexity

Unspecified, but generally up to linear in both the compared and comparing string's lengths.

Iterator validity

No changes.

Data races

The object is accessed.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the basic_string (except (1), which is guaranteed to not throw).

If s does not point to an array long enough, it causes undefined behavior.

If pos is greater than the string length, or if subpos is greater than str's length, an out_of_range exception is thrown.

C++

Reference

C library:

Containers:

Input/Output:

Multi-threading:

Other:

<string>

class templates

classes

functions

basic_string

member functions

member constants

non-member overloads