View source for cpp/string/basic string/compare

You do not have permission to edit this page, for the following reasons:

The action you have requested is limited to users in one of the groups: Users, Administrators.

Due to recent vandalism, editing of this page is temporarily disabled for new users.If you want to suggest a change, please leave a message on the suggestions page for new users instead (don't be surprised if that page appears vandalized!).

You can view and copy the source of this page.

{{cpp/string/basic_string/title|compare}}
{{cpp/string/basic_string/navbar}}
{{dcl begin}}
{{dcla|num=1|noexcept=c++11|constexpr=c++20|1=
int compare( const basic_string& str ) const;
}}
{{dcla|anchor=no|num=2|constexpr=c++20|
int compare( size_type pos1, size_type count1,
             const basic_string& str ) const;
}}
{{dcl rev multi|num=3
|dcl1=
int compare( size_type pos1, size_type count1,
             const basic_string& str,
             size_type pos2, size_type count2 ) const;
|since2=c++14|notes2={{mark constexpr since c++20}}|dcl2=
int compare( size_type pos1, size_type count1,
             const basic_string& str,
             size_type pos2, size_type count2 = npos ) const;
}}
{{dcla|anchor=no|num=4|constexpr=c++20|
int compare( const CharT* s ) const;
}}
{{dcla|anchor=no|num=5|constexpr=c++20|
int compare( size_type pos1, size_type count1,
             const CharT* s ) const;
}}
{{dcla|anchor=no|num=6|constexpr=c++20|
int compare( size_type pos1, size_type count1,
             const CharT* s, size_type count2 ) const;
}}
{{dcla|anchor=no|num=7|since=c++17|constexpr=c++20|
template< class StringViewLike >
int compare( const StringViewLike& t ) const noexcept(/* see below */);
}}
{{dcla|anchor=no|num=8|since=c++17|constexpr=c++20|
template< class StringViewLike >
int compare( size_type pos1, size_type count1,
             const StringViewLike& t ) const;
}}
{{dcla|anchor=no|num=9|since=c++17|constexpr=c++20|1=
template< class StringViewLike >
int compare( size_type pos1, size_type count1,
             const StringViewLike& t,
             size_type pos2, size_type count2 = npos) const;
}}
{{dcl end}}

Compares two character sequences.

@1@ Compares this string to {{c|str}}.

@2@ Compares a {{range|pos1|pos1 + count1}} substring of this string to {{c|str}}.
* If {{c|count1 > size() - pos1}}, the substring is {{range|pos1|size()}}.

@3@ Compares a {{range|pos1|pos1 + count1}} substring of this string to a substring {{range|pos2|pos2 + count2}} of {{c|str}}.
* If {{c|count1 > size() - pos1}}, the first substring is {{range|pos1|size()}}.
* If {{c|count2 > str.size() - pos2}}, the second substring is {{range|pos2|str.size()}}.

@4@ Compares this string to the null-terminated character sequence beginning at the character pointed to by {{c|s}} with length {{c|Traits::length(s)}}.

@5@ Compares a {{range|pos1|pos1 + count1}} substring of this string to the null-terminated character sequence beginning at the character pointed to by {{c|s}} with length {{c|Traits::length(s)}}.
* If {{c|count1 > size() - pos1}}, the substring is {{range|pos1|size()}}.

@6@ Compares a {{range|pos1|pos1 + count1}} substring of this string to the characters in the range {{range|s|s + count2}}. The characters in {{range|s|s + count2}} may include null characters.
* If {{c|count1 > size() - pos1}}, the substring is {{range|pos1|size()}}.

@7-9@ {{cpp/string/sv hack|plural=yes|
:@7@ compares this string to {{c|sv}};
:@8@ compares a {{range|pos1|pos1 + count1}} substring of this string to {{c|sv}}, as if by {{c|std::basic_string_view<CharT, Traits>(*this).substr(pos1, count1).compare(sv)}};
:@9@ compares a {{range|pos1|pos1 + count1}} substring of this string to a substring {{range|pos2|pos2 + count2}} of {{c|sv}}, as if by {{c multi|
std::basic_string_view<CharT, Traits>(*this)|
    .substr(pos1, count1).compare(sv.substr(pos2, count2))}}}}.

A character sequence consisting of {{c|count1}} characters starting at {{c|data1}} is compared to a character sequence consisting of {{c|count2}} characters starting at {{c|data2}} as follows:
* First, calculate the number of characters to compare, as if by {{c|1=size_type rlen = std::min(count1, count2)}}.
* Then compare the sequences by calling {{c|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:

{|class="wikitable" style="text-align:center;"
!colspan=2|Condition
!Result
!Return value
|-
|colspan=2 style="text-align:left;"|{{tt|Traits::compare({{spar|data1}}, {{spar|data2}}, {{spar|rlen}}) < 0}}
|{{spar|data1}} is ''less'' than {{spar|data2}}
|{{c|<0}}
|-
|rowspan=3|{{tt|Traits::compare({{spar|data1}}, {{spar|data2}}, {{spar|rlen}}) {{==}} 0}}
|{{spar|size1}} < {{spar|size2}}
|{{spar|data1}} is ''less'' than {{spar|data2}}
|{{c|<0}}
|-
<!---->
|{{spar|size1}} {{==}} {{spar|size2}}
|{{spar|data1}} is ''equal'' to {{spar|data2}}
|{{c|0}}
|-
<!---->
|{{spar|size1}} > {{spar|size2}}
|{{spar|data1}} is ''greater'' than {{spar|data2}}
|{{c|>0}}
|-
|colspan=2 style="text-align:left;"|{{tt|Traits::compare({{spar|data1}}, {{spar|data2}}, {{spar|rlen}}) > 0}}
|{{spar|data1}} is ''greater'' than {{spar|data2}}
|{{c|>0}}
|}

===Parameters===
{{par begin}}
{{par|str|other string to compare to}}
{{par|s|pointer to the character string to compare to}}
{{par|count1|number of characters of this string to compare}}
{{par|pos1|position of the first character in this string to compare}}
{{par|count2|number of characters of the given string to compare}}
{{par|pos2|position of the first character of the given string to compare}}
{{par|t|object (convertible to {{lc|std::basic_string_view}}) to compare to}}
{{par end}}

===Return value===
* Negative value if {{c|*this}} appears before the character sequence specified by the arguments, in lexicographical order.
* Zero if both character sequences compare equivalent.
* Positive value if {{c|*this}} appears after the character sequence specified by the arguments, in lexicographical order.

===Exceptions===
The overloads taking parameters named {{c|pos1}} or {{c|pos2}} throws {{lc|std::out_of_range}} if the argument is out of range.

@7@ {{noexcept|std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>}}
@8,9@ Throws anything thrown by the conversion to {{lc|std::basic_string_view}}.

{{cpp/strong exception safety guarantee}}

===Possible implementation===
{{eq impl
|title1=overload (1)|ver1=1|1=
template<class CharT, class Traits, class Alloc>
int std::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, {{lc|std::basic_string}} provides the usual {{rlp|operator cmp|relational operators}} ({{tt|<}}, {{tt|1=<=}}, {{tt|1===}}, {{tt|>}}, etc).

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

===Example===
{{example
|code=
#include <cassert>
#include <iomanip>
#include <iostream>
#include <string>
#include <string_view>

void print_compare_result(std::string_view str1,
                          std::string_view str2,
                          int compare_result)
{
    if (compare_result < 0)
        std::cout << std::quoted(str1) << " comes before "
                  << std::quoted(str2) << ".\n";
    else if (compare_result > 0)
        std::cout << std::quoted(str2) << " comes before "
                  << std::quoted(str1) << ".\n";
    else
        std::cout << std::quoted(str1) << " and "
                  << std::quoted(str2) << " are the same.\n";
}

int main()
{
    std::string batman{"Batman"};
    std::string superman{"Superman"};
    int compare_result{0};
    
    // 1) Compare with other string
    compare_result = batman.compare(superman);
    std::cout << "1) ";
    print_compare_result("Batman", "Superman", compare_result);
    
    // 2) Compare substring with other string
    compare_result = batman.compare(3, 3, superman);
    std::cout << "2) ";
    print_compare_result("man", "Superman", compare_result);
    
    // 3) Compare substring with other substring
    compare_result = batman.compare(3, 3, superman, 5, 3);
    std::cout << "3) ";
    print_compare_result("man", "man", compare_result);
    
    // Compare substring with other substring
    // defaulting to end of other string
    assert(compare_result == batman.compare(3, 3, superman, 5));
    
    // 4) Compare with char pointer
    compare_result = batman.compare("Superman");
    std::cout << "4) ";
    print_compare_result("Batman", "Superman", compare_result);
    
    // 5) Compare substring with char pointer
    compare_result = batman.compare(3, 3, "Superman");
    std::cout << "5) ";
    print_compare_result("man", "Superman", compare_result);
    
    // 6) Compare substring with char pointer substring
    compare_result = batman.compare(0, 3, "Superman", 5);
    std::cout << "6) ";
    print_compare_result("Bat", "Super", compare_result);
}
|output=
1) "Batman" comes before "Superman".
2) "Superman" comes before "man".
3) "man" and "man" are the same.
4) "Batman" comes before "Superman".
5) "Superman" comes before "man".
6) "Bat" comes before "Super".
}}

===Defect reports===
{{dr list begin}}
{{dr list item|wg=lwg|dr=5|std=C++98|before=the parameter {{c|count2}} of overload {{v|6}}<br>had a default argument {{c|npos}}|after=default argument removed,<br>split to overloads {{v|5}} and {{v|6}}}}
{{dr list item|wg=lwg|dr=847|std=C++98|before=there was no exception safety guarantee|after=added strong exception safety guarantee}}
{{dr list item|wg=lwg|dr=2946|std=C++17|before=overload {{v|7}} caused ambiguity in some cases|after=avoided by making it a template}}
{{dr list item|paper=P1148R0|std=C++17|before=noexcept for overload {{v|7}} was accidentally<br>dropped by the resolution of LWG2946|after=restored}}
{{dr list end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/string/basic_string/dsc operator cmp}}
{{dsc inc|cpp/string/basic_string/dsc substr}}
{{dsc inc|cpp/locale/dsc collate}}
{{dsc inc|cpp/string/byte/dsc strcoll}}
{{dsc inc|cpp/algorithm/dsc lexicographical_compare}}
{{dsc inc|cpp/string/basic_string_view/dsc compare}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pl|pt|ru|zh}}

Templates used on this page:

Template:!- (view source)
Template:== (view source)
Template:anchor (view source)
Template:box (view source)
Template:box/core (view source)
Template:c (view source) (protected)
Template:c/core (view source) (protected)
Template:c multi (view source)
Template:cc (view source)
Template:cpp/algorithm/dsc lexicographical compare (view source)
Template:cpp/enable if (view source)
Template:cpp/locale/dsc collate (view source)
Template:cpp/navbar content (view source)
Template:cpp/navbar heading (view source)
Template:cpp/string/basic string/dsc operator cmp (view source)
Template:cpp/string/basic string/dsc substr (view source)
Template:cpp/string/basic string/navbar (view source)
Template:cpp/string/basic string/navbar content (view source)
Template:cpp/string/basic string/navbar heading (view source)
Template:cpp/string/basic string/title (view source)
Template:cpp/string/basic string view/dsc compare (view source)
Template:cpp/string/basic string view/title (view source)
Template:cpp/string/byte/dsc strcoll (view source)
Template:cpp/string/navbar content (view source)
Template:cpp/string/navbar heading (view source)
Template:cpp/string/sv hack (view source)
Template:cpp/strong exception safety guarantee (view source)
Template:cpp/title (view source) (protected)
Template:ctitle (view source) (protected)
Template:dcl (view source) (protected)
Template:dcl/std (view source) (semi-protected)
Template:dcl begin (view source) (protected)
Template:dcl end (view source) (protected)
Template:dcl rev begin (view source)
Template:dcl rev end (

cppreference.com

Search

Namespaces

Variants

Views

Actions

View source for cpp/string/basic string/compare