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

出自cppreference.com
 
C++
 
字符串庫
 
std::basic_string
 
basic_string& append( size_type count, CharT ch );
(1) (C++20 起為 constexpr) 
basic_string& append( const CharT* s, size_type count );
(2) (C++20 起為 constexpr) 
basic_string& append( const CharT* s );
(3) (C++20 起為 constexpr) 
template< class SV >
basic_string& append( const SV& t );
(4) (C++17 起)
(C++20 起為 constexpr)		 
template< class SV >
basic_string& append( const SV& t, size_type pos,
                      size_type count = npos );
(5) (C++17 起)
(C++20 起為 constexpr)		 
basic_string& append( const basic_string& str );
(6) (C++20 起為 constexpr)
(7) 
basic_string& append( const basic_string& str,
                      size_type pos, size_type count );
(C++14 前) 
basic_string& append( const basic_string& str,
                      size_type pos, size_type count = npos );
(C++14 起)
(C++20 起為 constexpr)		 
template< class InputIt >
basic_string& append( InputIt first, InputIt last );
(8) (C++20 起為 constexpr) 
basic_string& append( std::initializer_list<CharT> ilist );
(9) (C++11 起)
(C++20 起為 constexpr)

後附額外字符到字符串。

1) 後附 count 個 ch 的副本。
2) 後附範圍 [s, s + count) 中的字符。
如果 [s, s + count) 不是有效範圍，那麼行為未定義。
3) 等價於 return append(s, Traits::length(s));。
4,5) 後附從 t 構造的字符串視圖 sv 中的字符。
  • 如果只提供了 t，那麼就會後附 sv 中的所有字符。
  • 如果也提供了 pos：
    • 如果 count 是 npos，那麼就會後附 sv 中從 pos 處開始的所有字符。
    • 否則會後附 sv 中從 pos 處開始的 std::min(count, sv.size() - pos) 個字符。
這些重載只有在滿足以下所有條件時才會參與重載決議：
  • std::is_convertible_v<const SV&, std::basic_string_view<CharT, Traits>> 是 true。
  • std::is_convertible_v<const SV&, const CharT*> 是 false。
4) 等價於 std::basic_string_view<CharT, Traits> sv = t;
return append(sv.data(), sv.size());。
5) 等價於 std::basic_string_view<CharT, Traits> sv = t;
return append(sv.substr(pos, count));。
6,7) 後附另一字符串 str 中的字符。
  • 如果只提供了 str，那麼就會後附 str 中的所有字符。
  • 如果也提供了 pos：
    • 如果 count 是 npos，那麼就會後附 str 中從 pos 處開始的所有字符。
    • 否則會後附 str 中從 pos 處開始的 std::min(count, str.size() - pos) 個字符。
6) 等價於 return append(str.data(), str.size());。
7) 等價於 return append(std::basic_string_view<CharT, Traits>
(str).substr(pos, count));。
(C++20 起)
8) 等價於 return append(basic_string(first, last, get_allocator()));。

如果 InputIt 為整數類型，那麼此重載與重載 (1) 擁有相同效果。

(C++11 前)

此重載只有在 InputIt 滿足 老式輸入迭代器 (LegacyInputIterator) 的要求時才會參與重載決議。

(C++11 起)
9) 等價於 return append(ilist.begin(), ilist.size());。

參數

count - 要後附的字符數
ch - 要後附的字符值
s - 指向要後附的字符串的指針
t - 可轉換為帶要後附的字符的可以轉換到 std::basic_string_view 的對象
pos - 要後附的首個字符下標
str - 要後附的字符串
first, last - 要後附的字符範圍
ilist - 擁有要後附的字符的初始化器列表

返回值

*this

複雜度

無標準複雜度保證，典型實現表現類似 std::vector::insert()。

異常

如果操作會導致 size() 超出 max_size()，那麼就會拋出 std::length_error。

5) 如果 pos > sv.size() 是 true，那麼就會拋出 std::out_of_range。
7) 如果 pos > str.size() 是 true，那麼就會拋出 std::out_of_range。

如果因為任何原因拋出了異常，那麼此函數無效果（強異常安全保證）。

示例

運行此代碼
#include <cassert>
#include <string>

int main()
{
    std::basic_string<char> str = "string";
    const char* cptr = "C-string";
    const char carr[] = "Two and one";

    std::string result;

    // 1) 后附 char 3 次。
    // 注意：这是仅有的接受 “CharT” 的重载。
    result.append(3, '*');
    assert(result == "***");

    // 2) 后附定长 C 风格字符串
    result.append(cptr, 5);
    assert(result == "***C-str");

    // 3) 后附空终止 C 风格字符串
    // 注意：因为 “append” 返回 *this，所以我们能一同链式调用。
    result.append(1, ' ').append(cptr);
    assert(result == "***C-str C-string");

    // 6) 后附整个字符串
    result.append(1, ' ').append(str);
    assert(result == "***C-str C-string std::string");

    // 7) 后附字符串的一部分
    result.append(str, 3, 2);
    assert(result == "***C-str C-string std::string::");

    // 8) 后附范围
    result.append(&carr[2], &carr[3]);
    assert(result == "***C-str C-string std::string::n");

    // 9) 后附初始化器列表
    result.append({'p', 'o', 's'});
    assert(result == "***C-str C-string std::string::npos");
}

缺陷報告

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

缺陷報告 應用於 出版時的行為 正確行為
LWG 847 C++98 沒有異常安全保證 添加強異常安全保證
LWG 2250 C++98 pos > str.size() 是 true 時重載 (7) 的行為未定義 此時始終會拋出異常
LWG 2788 C++98 重載 (8) 使用默認構造的分配器來構造臨時字符串 從 get_allocator() 獲取分配器
LWG 2946 C++17 重載 (4) 在某些情況下會導致歧義 通過使之為模板來避免

參閱

(C++23)
 後附範圍內的字符到結尾
(公開成員函數) [編輯]
後附字符到結尾
(公開成員函數) [編輯]
連接兩個字符串
(函數) [編輯]
連接兩個字符串的一定量字符
(函數) [編輯]
追加寬字符串的副本到另一個
(函數) [編輯]
追加來自寬字符串的一定量寬字符到另一個
(函數) [編輯]