Namespaces
Variants

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

From cppreference.net
C++
Strings library
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 ) 个字符。
这些重载仅在满足以下所有条件时参与重载决议：
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 开始的所有字符。
    • 否则，追加 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::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)
向末尾追加一个字符范围
(公开成员函数)
向末尾追加字符
(公开成员函数)
连接两个字符串
(函数)
连接两个字符串的指定数量字符
(函数)
将一个宽字符串的副本追加到另一个宽字符串
(函数)
将一个宽字符串的指定数量宽字符追加到另一个宽字符串
(函数)