# std::basic_string::compare

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

int compare( const basic_string& str ) const; | (1) |
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) |
int compare( std::basic_string_view<CharT, Traits> sv) const; | (7) | (since C++17)
int compare( size_type pos1, size_type count1, std::basic_string_view<CharT, Traits> sv) 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. First, calculates the number of characters to compare, as if by size_type rlen = std::min(size(), str.size()). Then compares by calling Traits::compare(data(), str.data(), rlen). For standard strings this function performs character-by-character lexicographical comparison. If the result is zero (the strings are equal so far), then their sizes are compared as follows:

Condition | Result | Return value
--- | --- | ---
`Traits::compare(data, arg, rlen) < 0` | data is less than arg | <0
`Traits::compare(data, arg, rlen) == 0` | `size(data) < size(arg)` | data is less than arg | <0
`size(data) == size(arg)` | data is equal to arg | ​0​
`size(data) > size(arg)` | data is greater than arg | >0
`Traits::compare(data, arg, rlen) > 0` | data is greater than arg | >0

2) Compares a `[pos1, pos1+count1)` substring of this string to str as if by basic_string(*this, pos1, count1).compare(str) (until C++17)compare(pos1, count1, std::basic_string_view<CharT, Traits>(str)) (since C++17)
3) Compares a `[pos1, pos1+count1)` substring of this string to a substring `[pos2, pos2+count2)` of str as if by basic_string(*this, pos1, count1).compare(basic_string(str, pos2, count2)) (until C++17)compare(pos1, count1, std::basic_string_view<CharT, Traits>(str), pos2, count2) (since C++17)
4) Compares this string to the null-terminated character sequence beginning at the character pointed to by s, as if by compare(basic_string(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, as if by basic_string(*this, pos, count1).compare(basic_string(s))
6) Compares a `[pos1, pos1+count1)` substring of this string to the first `count2` characters of the character array whose first character is pointed to by s, as if by basic_string(*this, pos, count1).compare(basic_string(s, count2)). (Note: the characters from `s` to `s+count2` may include null characters))
7) Compares this string to `sv`, similar to (1) except for using sv.size() and sv.data() instead of str.size() and str.data()
8) Compares a `[pos1, pos1+count1)` substring of this string to `sv`, as if by std::basic_string_view<CharT, Traits>(data(), size()).substr(pos1, count1).compare(sv)
9) 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>(data(), size()).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.

### 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
sv | - | std::basic_string_view to compare to
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

1)

(none) | (until C++11)
`noexcept` specification: noexcept | (since C++11)

2-6) May throw the exceptions thrown by the corresponding `basic_string` constructors.

7) `noexcept` specification: noexcept | (since C++17)

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

| This section is incomplete Reason: no example

### 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 "http://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/compare&oldid=91660"
Categories:

- unconditionally noexcept
- Todo no example

Hidden categories:

- Pages with unreviewed unconditional noexcept template
- Pages with unreviewed noexcept template