Namespaces
Variants
Views
Actions

std::basic_string::compare

From cppreference.com
< cpp‎ | string‎ | basic string
 
 
 
std::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)
int compare( size_type pos1, size_type count1,

             std::basic_string_view<CharT, Traits> sv,

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

Contents

[edit] 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

[edit] 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

[edit] 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)

[edit] 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;
}

[edit] 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.

[edit] Example

[edit] See also

lexicographically compares two strings
(function template) [edit]
returns a substring
(public member function) [edit]
defines lexicographical comparison and hashing of strings
(class template) [edit]
compares two strings in accordance to the current locale
(function) [edit]
returns true if one range is lexicographically less than another
(function template) [edit]