# std::basic_string<CharT,Traits,Allocator>::compare

From cppreference.com
< cpp‎ | string‎ | basic string

| (1) |
int compare( const basic_string& str ) const; |  | (until C++11)
int compare( const basic_string& str ) const noexcept; |  | (since C++11)
int compare( size_type pos1, size_type count1, const basic_string& str ) const; | (2) |
| (3) |
int compare( size_type pos1, size_type count1, const basic_string& str, size_type pos2, size_type count2 ) const; |  | (until C++14)
int compare( size_type pos1, size_type count1, const basic_string& str, size_type pos2, size_type count2 = npos ) const; |  | (since C++14)
int compare( const CharT* s ) const; | (4) |
int compare( size_type pos1, size_type count1, const CharT* s ) const; | (5) |
int compare( size_type pos1, size_type count1, const CharT* s, size_type count2 ) const; | (6) |
template < class T > int compare( const T& t ) const noexcept(/* see below */); | (7) | (since C++17)
template < class T > int compare( size_type pos1, size_type count1, const T& t ) const; | (8) | (since C++17)
template < class T > int compare( size_type pos1, size_type count1, const T& t, size_type pos2, size_type count2 = npos) const; | (9) | (since C++17)

Compares two character sequences.

1) Compares this string to str.
2) Compares a `[pos1, pos1+count1)` substring of this string to str. If count1 > size() - pos1 the substring is `[pos1, size())`.
3) Compares a `[pos1, pos1+count1)` substring of this string to a substring `[pos2, pos2+count2)` of str. If count1 > size() - pos1 the first substring is `[pos1, size())`. Likewise, count2 > str.size() - pos2 the second substring is `[pos2, str.size())`.
4) Compares this string to the null-terminated character sequence beginning at the character pointed to by s with length `Traits::length(s)`.
5) Compares a `[pos1, pos1+count1)` substring of this string to the null-terminated character sequence beginning at the character pointed to by s with length `Traits::length(s)` If count1 > size() - pos1 the substring is `[pos1, size())`.
6) Compares a `[pos1, pos1+count1)` substring of this string to the characters in the range `[s, s + count2)`. If count1 > size() - pos1 the substring is `[pos1, size())`. (Note: the characters in the range `[s, s + count2)` may include null characters.)
7) Implicitly converts `t` to a string view `sv` as if by std::basic_string_view<CharT, Traits> sv = t;, then compares this string to `sv`. This overload only participates in overload resolution if std::is_convertible_v<const T&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const T&, const CharT*> is false.
8) Implicitly converts `t` to a string view `sv` as if by std::basic_string_view<CharT, Traits> sv = t;, then compares a `[pos1, pos1+count1)` substring of this string to `sv`, as if by std::basic_string_view<CharT, Traits>(*this).substr(pos1, count1).compare(sv). This overload only participates in overload resolution if std::is_convertible_v<const T&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const T&, const CharT*> is false.
9) Implicitly converts `t` to a string view `sv` as if by std::basic_string_view<CharT, Traits> sv = t;, then compares a `[pos1, pos1+count1)` substring of this string to a substring `[pos2, pos2+count2)` of `sv` as if by std::basic_string_view<CharT, Traits>(*this).substr(pos1, count1).compare(sv.substr(pos2, count2)). This overload only participates in overload resolution if std::is_convertible_v<const T&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const T&, const CharT*> is false.

A character sequence consisting of `count1` characters starting at `data1` is compared to a character sequence consisting of `count2` characters starting at `data2` as follows. First, calculate the number of characters to compare, as if by size_type rlen = std::min(count1, count2). Then compare the sequences by calling Traits::compare(data1, data2, rlen). For standard strings this function performs character-by-character lexicographical comparison. If the result is zero (the character sequences are equal so far), then their sizes are compared as follows:

Condition | Result | Return value
--- | --- | ---
`Traits::compare(data1, data2, rlen) < 0` | data1 is less than data2 | <0
`Traits::compare(data1, data2, rlen) == 0` | size1 < size2 | data1 is less than data2 | <0
size1 == size2 | data1 is equal to data2 | ​0​
size1 > size2 | data1 is greater than data2 | >0
`Traits::compare(data1, data2, rlen) > 0` | data1 is greater than data2 | >0

### Parameters

str | - | other string to compare to
s | - | pointer to the character string to compare to
count1 | - | number of characters of this string to compare
pos1 | - | position of the first character in this string to compare
count2 | - | number of characters of the given string to compare
pos2 | - | position of the first character of the given string to compare
t | - | object (convertible to std::basic_string_view) to compare to

### Return value

negative value if *this appears before the character sequence specified by the arguments, in lexicographical order

zero if both character sequences compare equivalent

positive value if *this appears after the character sequence specified by the arguments, in lexicographical order

### Exceptions

The overloads taking parameters named `pos1` or `pos2` throws std::out_of_range if the argument is out of range.

7)
`noexcept` specification:
noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>)
8-9) Throws anything thrown by the conversion to `basic_string_view`.

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
LWG 2946 | C++17 | `string_view` overload causes ambiguity in some cases | avoided by making it a template

### Possible implementation

    template<class CharT, class Traits, class Alloc>
    int basic_string<CharT, Traits, Alloc>::compare(const std::basic_string& s) const noexcept
    {
        size_type lhs_sz = size();
        size_type rhs_sz = s.size();
        int result = traits_type::compare(data(), s.data(), std::min(lhs_sz, rhs_sz));
        if (result != 0)
            return result;
        if (lhs_sz < rhs_sz)
            return -1;
        if (lhs_sz > rhs_sz)
            return 1;
        return 0;
    }

### Notes

For the situations when three-way comparison is not required, std::basic_string provides the usual relational operators (`<`, `<=`, `==`, `>`, etc).

By default (with the default std::char_traits), this function is not locale-sensitive. See std::collate::compare for locale-aware three-way string comparison.

### Example

Run this code

    #include <cassert>
    #include <string>
    #include <iostream>

    int main()
    {
        // 1) Compare with other string
        {
            int compare_value{
                std::string{"Batman"}.compare(std::string{"Superman"})
            };
            std::cout << (
                compare_value < 0 ? "Batman comes before Superman\n" :
                compare_value > 0 ? "Superman comes before Batman\n" :
                "Superman and Batman are the same.\n"
            );
        }

        // 2) Compare substring with other string
        {
            int compare_value{
                std::string{"Batman"}.compare(3, 3, std::string{"Superman"})
            };
            std::cout << (
                compare_value < 0 ? "man comes before Superman\n" :
                compare_value > 0 ? "Superman comes before man\n" :
                "man and Superman are the same.\n"
            );
        }

        // 3) Compare substring with other substring
        {
            std::string a{"Batman"};
            std::string b{"Superman"};

            int compare_value{a.compare(3, 3, b, 5, 3)};

            std::cout << (
                compare_value < 0 ? "man comes before man\n" :
                compare_value > 0 ? "man comes before man\n" :
                "man and man are the same.\n"
            );
            // Compare substring with other substring
            // defaulting to end of other string
            assert(compare_value == a.compare(3, 3, b, 5));
        }

        // 4) Compare with char pointer
        {
            int compare_value{std::string{"Batman"}.compare("Superman")};

            std::cout << (
                compare_value < 0 ? "Batman comes before Superman\n" :
                compare_value > 0 ? "Superman comes before Batman\n" :
                "Superman and Batman are the same.\n"
            );
        }

        // 5) Compare substring with char pointer
        {
            int compare_value{std::string{"Batman"}.compare(3, 3, "Superman")};

            std::cout << (
                compare_value < 0 ? "man comes before Superman\n" :
                compare_value > 0 ? "Superman comes before man\n" :
                "man and Superman are the same.\n"
            );
        }

        // 6) Compare substring with char pointer substring
        {
            int compare_value{std::string{"Batman"}.compare(0, 3, "Superman", 5)};

            std::cout << (
                compare_value < 0 ? "Bat comes before Super\n" :
                compare_value > 0 ? "Super comes before Bat\n" :
                "Super and Bat are the same.\n"
            );
        }
    }

Output:

    Batman comes before Superman
    Superman comes before man
    man and man are the same.
    Batman comes before Superman
    Superman comes before man
    Bat comes before Super

### See also

operator==operator!=operator<operator>operator<=operator>= | lexicographically compares two strings (function template)
substr | returns a substring (public member function)
collate | defines lexicographical comparison and hashing of strings (class template)
strcoll | compares two strings in accordance to the current locale (function)
lexicographical_compare | returns true if one range is lexicographically less than another (function template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/compare&oldid=107742"