intcompare(constbasic_string&str)const; (1)(noexcept since C++11)
(constexpr since C++20)intcompare(size_typepos1,size_typecount1,constbasic_string&str)const; (2)(constexpr since C++20)intcompare(size_typepos1,size_typecount1,constbasic_string&str,size_typepos2,size_typecount2)const; (3)(until C++14)intcompare(size_typepos1,size_typecount1,constbasic_string&str,size_typepos2,size_typecount2=npos)const;(since C++14)
(constexpr since C++20)intcompare(constCharT*s)const; (4)(constexpr since C++20)intcompare(size_typepos1,size_typecount1,constCharT*s)const; (5)(constexpr since C++20)intcompare(size_typepos1,size_typecount1,constCharT*s,size_typecount2)const; (6)(constexpr since C++20)template<classStringViewLike>intcompare(constStringViewLike&t)constnoexcept(/* see below */); (7)(since C++17)
(constexpr since C++20)template<classStringViewLike>intcompare(size_typepos1,size_typecount1,constStringViewLike&t)const; (8)(since C++17)
(constexpr since C++20)template<classStringViewLike>intcompare(size_typepos1,size_typecount1,constStringViewLike&t,size_typepos2,size_typecount2=npos)const; (9)(since C++17)
(constexpr since C++20)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()).
If 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). The characters in [s, s+count2) may include null characters.
If count1>size()-pos1, the substring is [pos1, size()).
7-9) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT,Traits>sv=t;, then
7) compares this string to sv;
8) 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);
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>(*this)
.substr(pos1,count1).compare(sv.substr(pos2,count2)). These overloads participate in overload resolution only if std::is_convertible_v<constStringViewLike&,std::basic_string_view<CharT,Traits>> is true and std::is_convertible_v<constStringViewLike&,constCharT*> 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_typerlen=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) < 0data1 is less than data2<0Traits::compare(data1, data2, rlen) == 0size1 < size2data1 is less than data2<0size1 == size2data1 is equal to data20size1 > size2data1 is greater than data2>0Traits::compare(data1, data2, rlen) > 0data1 is greater than data2>0Parameters
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
) 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
if the argument is out of range.
7)
specification:
noexcept(std::is_nothrow_convertible_v<constT&,std::basic_string_view<CharT,Traits>>)If an exception is thrown for any reason, this function has no effect (
strong exception safety guarantee
).
Possible implementation
template<classCharT,classTraits,classAlloc>intstd::basic_string<CharT,Traits,Alloc>::compare(conststd::basic_string&s)constnoexcept{size_typelhs_sz=size();size_typerhs_sz=s.size();intresult=traits_type::compare(data(),s.data(),std::min(lhs_sz,rhs_sz));if(result!=0)returnresult;if(lhs_sz<rhs_sz)return-1;if(lhs_sz>rhs_sz)return1;return0;}Notes
For the situations when three-way comparison is not required,
provides the usual
(<, <=, ==, >, etc).
By default (with the default
), this function is not locale-sensitive. See
for locale-aware three-way string comparison.
Example
Run this code
#include<cassert>#include<iomanip>#include<iostream>#include<string>#include<string_view>voidprint_compare_result(std::string_viewstr1,std::string_viewstr2,intcompare_result){if(compare_result<0)std::cout<<std::quoted(str1)<<" comes before "<<std::quoted(str2)<<".\n";elseif(compare_result>0)std::cout<<std::quoted(str2)<<" comes before "<<std::quoted(str1)<<".\n";elsestd::cout<<std::quoted(str1)<<" and "<<std::quoted(str2)<<" are the same.\n";}intmain(){std::stringbatman{"Batman"};std::stringsuperman{"Superman"};intcompare_result{0};// 1) Compare with other stringcompare_result=batman.compare(superman);std::cout<<"1) ";print_compare_result("Batman","Superman",compare_result);// 2) Compare substring with other stringcompare_result=batman.compare(3,3,superman);std::cout<<"2) ";print_compare_result("man","Superman",compare_result);// 3) Compare substring with other substringcompare_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 stringassert(compare_result==batman.compare(3,3,superman,5));// 4) Compare with char pointercompare_result=batman.compare("Superman");std::cout<<"4) ";print_compare_result("Batman","Superman",compare_result);// 5) Compare substring with char pointercompare_result=batman.compare(3,3,"Superman");std::cout<<"5) ";print_compare_result("man","Superman",compare_result);// 6) Compare substring with char pointer substringcompare_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
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++98 the parameter count2 of overload (
)
had a default argument nposdefault argument removed,
split to overloads (
) and (
)
C++98 there was no exception safety guarantee added strong exception safety guarantee
C++17 overload (
) caused ambiguity in some cases avoided by making it a template
C++17 noexcept for overload (
) was accidentally
dropped by the resolution of LWG2946 restored See also
operator==operator!=operator<operator>operator<=operator>=operator<=>
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20)
lexicographically compares two strings
(function template)
returns a substring
(public member function)
defines lexicographical comparison and hashing of strings
(class template)
compares two strings in accordance to the current locale
(function)
compares two ranges lexicographically
(function template & algorithm function object)
ranges::lexicographical_compare
(C++20)
compares two views
(public member function of std::basic_string_view<CharT,Traits>)