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

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

字串庫

類

basic_string

basic_string_view (C++17)

char_traits

 

std::basic_string

成員函式 basic_string::basic_string basic_string::~basic_string basic_string::operator= basic_string::assign basic_string::assign_range (C++23)   basic_string::get_allocator 元素訪問 basic_string::at basic_string::operator[] basic_string::front (DR*) basic_string::back (DR*) basic_string::data basic_string::c_str basic_string::operator  basic_string_view (C++17) 迭代器 basic_string::beginbasic_string::cbegin (C++11) basic_string::endbasic_string::cend (C++11) basic_string::rbeginbasic_string::crbegin (C++11) basic_string::rendbasic_string::crend (C++11) 搜尋 basic_string::find basic_string::rfind basic_string::find_first_of basic_string::find_first_not_of basic_string::find_last_of basic_string::find_last_not_of

修改器 basic_string::clear basic_string::insert basic_string::insert_range (C++23) basic_string::erase basic_string::push_back basic_string::pop_back (DR*) basic_string::append basic_string::append_range (C++23) basic_string::operator+= basic_string::replace basic_string::replace_with_range (C++23) basic_string::copy basic_string::resize basic_string::resize_and_overwrite (C++23)  basic_string::swap 容量 basic_string::empty basic_string::sizebasic_string::length basic_string::max_size basic_string::reserve basic_string::capacity basic_string::shrink_to_fit (DR*) 操作 basic_string::compare basic_string::starts_with (C++20) basic_string::ends_with (C++20) basic_string::contains (C++23) basic_string::substr

常量 basic_string::npos 非成員函式 operator+ swap(std::basic_string) erase(std::basic_string)erase_if(std::basic_string) (C++20)(C++20) I/O operator<<operator>> getline 比較 operator==operator!=operator<operator>operator<=operator>=operator<=> (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20) 數值轉換 stoistolstoll (C++11)(C++11)(C++11) stoulstoull (C++11)(C++11)  stofstodstold (C++11)(C++11)(C++11) to_string (C++11) to_wstring (C++11) 字面量 operator""s (C++14) 輔助類 hash<std::basic_string> (C++11) 推導指南 (C++17)

 

int compare( const basic_string& str ) const;	(1)	(C++11 起無異常丟擲) (C++20 起為 constexpr)
int compare( size_type pos1, size_type count1,              const basic_string& str ) const;	(2)	(C++20 起為 constexpr)
	(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;			(C++14 起) (C++20 起為 constexpr)
int compare( const CharT* s ) const;		(4)	(C++20 起為 constexpr)
int compare( size_type pos1, size_type count1,              const CharT* s ) const;		(5)	(C++20 起為 constexpr)
int compare( size_type pos1, size_type count1,              const CharT* s, size_type count2 ) const;		(6)	(C++20 起為 constexpr)
template< class StringViewLike > int compare( const StringViewLike& t ) const noexcept(/* see below */);		(7)	(C++17 起) (C++20 起為 constexpr)
template< class StringViewLike > int compare( size_type pos1, size_type count1,              const StringViewLike& t ) const;		(8)	(C++17 起) (C++20 起為 constexpr)
template< class StringViewLike > int compare( size_type pos1, size_type count1,              const StringViewLike& t,              size_type pos2, size_type count2 = npos) const;		(9)	(C++17 起) (C++20 起為 constexpr)

比較兩個字元序列。

1) 將此字串與 str 進行比較。

2) 將此字串的 [pos1, pos1 + count1) 子字串與 str 進行比較。

• 如果 count1 > size() - pos1，則子字串為 [pos1, size())。

3) 將此字串的 [pos1, pos1 + count1) 子字串與 str 的子字串 [pos2, pos2 + count2) 進行比較。

• 如果 count1 > size() - pos1，則第一個子字串為 [pos1, size())。
• 如果 count2 > str.size() - pos2，則第二個子字串為 [pos2, str.size())。

4) 將此字串與從 s 指向的字元開始，長度為 Traits::length(s) 的空終止字元序列進行比較。

5) 將此字串的 [pos1, pos1 + count1) 子字串與從 s 指向的字元開始，長度為 Traits::length(s) 的空終止字元序列進行比較。

• 如果 count1 > size() - pos1，則子字串為 [pos1, size())。

6) 將此字串的 [pos1, pos1 + count1) 子字串與範圍 [s, s + count2) 中的字元進行比較。範圍 [s, s + count2) 中的字元可以包含空字元。

• 如果 count1 > size() - pos1，則子字串為 [pos1, size())。

7-9) 將 t 隱式轉換為字串檢視 sv，如同透過 std::basic_string_view<CharT, Traits> sv = t;，然後：

7) 將此字串與 sv 進行比較；

8) 將此字串的 [pos1, pos1 + count1) 子字串與 sv 進行比較，如同透過 std::basic_string_view<CharT, Traits>(*this).substr(pos1, count1).compare(sv)；

9) 將此字串的 [pos1, pos1 + count1) 子字串與 sv 的子字串 [pos2, pos2 + count2) 進行比較，如同透過 std::basic_string_view<CharT, Traits>(*this)
    .substr(pos1, count1).compare(sv.substr(pos2, count2))。

這些過載僅在 std::is_convertible_v<const StringViewLike&,
                      std::basic_string_view<CharT, Traits>> 為 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 為 false 時才參與過載決議。

由 data1 開始的 count1 個字元組成的字元序列與由 data2 開始的 count2 個字元組成的字元序列按如下方式進行比較：

• 首先，計算要比較的字元數，如同透過 size_type rlen = std::min(count1, count2)。
• 然後透過呼叫 Traits::compare(data1, data2, rlen) 比較序列。對於標準字串，此函式執行逐字元的字典序比較。如果結果為零（到目前為止字元序列相等），則按如下方式比較它們的大小：

條件		結果	返回值
Traits::compare(data1, data2, rlen) < 0		data1 小於 data2	<0
Traits::compare(data1, data2, rlen) == 0	size1 < size2	data1 小於 data2	<0
	size1 == size2	data1 等於 data2	​0​
	size1 > size2	data1 大於 data2	>0
Traits::compare(data1, data2, rlen) > 0		data1 大於 data2	>0

引數

str	-	要比較的另一個字串
s	-	指向要比較的字元字串的指標
count1	-	此字串要比較的字元數
pos1	-	此字串中要比較的第一個字元的位置
count2	-	給定字串要比較的字元數
pos2	-	給定字串中要比較的第一個字元的位置
t	-	要比較的物件（可轉換為 std::basic_string_view）

返回值

• 如果 *this 在字典序中出現在引數指定的字元序列之前，則返回負值。
• 如果兩個字元序列比較等價，則返回零。
• 如果 *this 在字典序中出現在引數指定的字元序列之後，則返回正值。

異常

接受名為 pos1 或 pos2 的引數的過載，如果引數超出範圍，則丟擲 std::out_of_range。

7)

noexcept 規範：  

noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>)

8,9) 丟擲轉換為 std::basic_string_view 丟擲的任何異常。

如果由於任何原因丟擲異常，此函式無效果（強異常安全保證）。

可能的實現

過載 (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; }

注意

對於不需要三向比較的情況，std::basic_string 提供常用的關係運算符（<, <=, ==, > 等）。

預設情況下（使用預設的 std::char_traits），此函式不區分割槽域設定。有關區域設定感知的三向字串比較，請參閱 std::collate::compare。

示例

執行此程式碼

#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);
}

輸出

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".

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 5	C++98	過載 (6) 的引數 count2 有一個預設引數 npos	預設引數已移除， 拆分為過載 (5) 和 (6)
LWG 847	C++98	沒有異常安全保證	添加了強異常安全保證
LWG 2946	C++17	過載 (7) 在某些情況下導致歧義	透過使其成為模板來避免
P1148R0	C++17	過載 (7) 的 noexcept 意外地被 LWG2946 的解決方案刪除了 dropped by the resolution of LWG2946	恢復

另請參閱

operator==operator!=operator<operator>operator<=operator>=operator<=> (C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20)	按字典序比較兩個字串 (函式模板)
substr	返回子字串 (公共成員函式)
collate	定義字串的詞法比較和雜湊 (類模板)
strcoll	根據當前區域設定比較兩個字串 (函式)
lexicographical_compare	如果一個範圍在字典上小於另一個範圍，則返回 true (函式模板)
compare	比較兩個檢視 (std::basic_string_view<CharT,Traits> 的公共成員函式)