Namespaces
Variants

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

    来自 zh.cppreference.net
     
    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) 
    basic_string& append( const basic_string& str,
                      size_type pos, size_type count );
    		(7) (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) 追加由 sv 构造的字符串视图 t 中的字符。
    • 如果只提供 t，则追加 sv 中的所有字符。
    • 如果同时提供了 pos：
      • 如果 count 为 npos，则追加 sv 中从 pos 开始的所有字符。
      • 否则，追加 std::min(count, sv.size() - pos) 中从 sv 开始的 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，则追加其中的所有字符。
    • 如果同时提供了 pos：
      • 如果 count 为 npos，则追加 str 中从 pos 开始的所有字符。
      • 否则，追加 std::min(count, str.size() - pos) 中从 str 开始的 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()));。

    如果 是整数类型，则此重载与重载 (1)InputIt 具有相同效果。

    		(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::string str = "std::string";
    const char* cptr = "C-string";
    const char carr[] = "range";
    std::string result;
    // 1) 重复追加字符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 当 (7) 重载中 pos > str. size ( ) 为 true 时
    行为未定义     		此情况下始终抛出异常
    LWG 2788 C++98 (8) 重载使用默认构造的分配器
    来构造临时字符串     		从 get_allocator()
    获取分配器
    LWG 2946 C++17 (4) 重载在某些情况下会导致歧义 通过将其设为模板来避免

    参见

    (C++23)
    		向末尾追加一个字符范围
    (公开成员函数)
    		向末尾追加字符
    (公开成员函数)
    		连接两个字符串
    (函数)
    		连接两个字符串的指定数量字符
    (函数)
    		将一个宽字符串的副本追加到另一个宽字符串
    (函数)
    		将一个宽字符串的指定数量宽字符追加到另一个宽字符串
    (函数)