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

basic_string& append( size_type count, CharT ch );	(1)	(从 C++20 开始为 constexpr)
basic_string& append( const basic_string& str );	(2)	(从 C++20 开始为 constexpr)
	(3)
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)
basic_string& append( const CharT* s, size_type count );		(4)	(从 C++20 开始为 constexpr)
basic_string& append( const CharT* s );		(5)	(从 C++20 开始为 constexpr)
template< class InputIt > basic_string& append( InputIt first, InputIt last );		(6)	(从 C++20 开始为 constexpr)
basic_string& append( std::initializer_list<CharT> ilist );		(7)	(从 C++11 开始) (从 C++20 开始为 constexpr)
template< class StringViewLike > basic_string& append( const StringViewLike& t );		(8)	(从 C++17 开始) (从 C++20 开始为 constexpr)
template< class StringViewLike > basic_string& append( const StringViewLike& t, size_type pos, size_type count = npos );		(9)	(从 C++17 开始) (从 C++20 开始为 constexpr)

将额外的字符追加到字符串。

1) 追加 count 个字符 ch 的副本。

2) 追加字符串 str。

3) 追加 str 的子字符串 [pos, pos + count)。

如果请求的子字符串超过字符串的末尾，或者如果 count == npos，则追加的子字符串为 [pos, size())。
如果 pos > str.size()，则抛出 std::out_of_range。

4) 追加范围 [s, s + count) 中的字符。此范围可以包含空字符。

如果 [s, s + count) 不是一个有效范围，则行为未定义。

5) 追加 s 指向的以 null 结尾的字符字符串，就像使用 append(s, Traits::length(s)) 一样。

6) 追加范围 [first, last) 中的字符。

如果 `InputIt` 是一个整数类型，则此重载的效果与重载 (1) 相同。	(直到 C++11)
只有当 `InputIt` 符合 LegacyInputIterator 时，此重载才参与重载解析。	(从 C++11 开始)

7) 追加来自初始化列表 ilist 的字符。

8) 隐式地将 t 转换为字符串视图 sv，就像使用 std::basic_string_view<CharT, Traits> sv = t; 一样，然后像使用 append(sv.data(), sv.size()) 一样追加来自 sv 的所有字符。

此重载仅在 std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> 为 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 为 false 时，才参与重载解析。

9) 隐式地将 t 转换为字符串视图 sv，如同使用 std::basic_string_view<CharT, Traits> sv = t;，然后追加来自 sv 的子视图 [pos, pos + count) 中的字符。

如果请求的子视图超出了 sv 的结尾，或者如果 count == npos，则追加的子视图为 [pos, sv.size())。
如果 pos >= sv.size()，则抛出 std::out_of_range。

此重载仅在 std::is_convertible_v<const StringViewLike&,
std::basic_string_view<CharT, Traits>> 为 true 且 std::is_convertible_v<const StringViewLike&, const CharT*> 为 false 时，才参与重载解析。

[编辑] 参数

count	-	要追加的字符数量
pos	-	要追加的第一个字符的索引
ch	-	要追加的字符值
first, last	-	要追加的字符范围
str	-	要追加的字符串
s	-	指向要追加的字符字符串的指针
ilist	-	包含要追加的字符的初始化列表
t	-	可转换为 std::basic_string_view 的对象，包含要追加的字符

[编辑] 返回值

*this

[编辑] 复杂度

没有标准的复杂度保证，典型的实现行为类似于 std::vector::insert()。

[编辑] 异常

如果操作会导致 size() > max_size()，则抛出 std::length_error。

如果由于任何原因抛出异常，则此函数没有效果 (强异常安全保证)。

[编辑] 示例

运行此代码

#include <iostream>
#include <string>
 
int main()
{
    std::basic_string<char> str = "string";
    const char* cptr = "C-string";
    const char carr[] = "Two and one";
 
    std::string output;
 
    // 1) Append a char 3 times. 
    // Notice, this is the only overload accepting chars.
    output.append(3, '*');
    std::cout << "1) " << output << '\n';
 
    // 2) Append a whole string
    output.append(str);
    std::cout << "2) " << output << '\n';
 
    // 3) Append part of a string (last 3 letters, in this case)
    output.append(str, 3, 3);
    std::cout << "3) " << output << '\n';
 
    // 4) Append part of a C-string
    // Notice, because `append` returns *this, we can chain calls together
    output.append(1, ' ').append(carr, 4);
    std::cout << "4) " << output << '\n';
 
    // 5) Append a whole C-string
    output.append(cptr);
    std::cout << "5) " << output << '\n';
 
    // 6) Append range
    output.append(&carr[3], std::end(carr));
    std::cout << "6) " << output << '\n';
 
    // 7) Append initializer list
    output.append({' ', 'l', 'i', 's', 't'});
    std::cout << "7) " << output << '\n';
}

输出

1) ***
2) ***string
3) ***stringing
4) ***stringing Two 
5) ***stringing Two C-string
6) ***stringing Two C-string and one
7) ***stringing Two C-string and one list

[编辑] 缺陷报告

以下行为改变的缺陷报告被追溯地应用于以前发布的 C++ 标准。

DR	应用于	已发布的行为	正确行为
LWG 847	C++98	没有异常安全保证	添加强异常安全保证
LWG 2946	C++17	重载 (8) 在某些情况下会导致歧义	通过将其设为模板避免

[编辑] 参见

append_range (C++23)	将一系列字符追加到末尾 (公有成员函数) [编辑]
operator+=	将字符追加到末尾 (公有成员函数) [编辑]
strcat	连接两个字符串 (函数) [编辑]
strncat	连接两个字符串的特定数量的字符 (函数) [编辑]
wcscat	将一个宽字符串的副本追加到另一个宽字符串 (函数) [编辑]
wcsncat	将一个宽字符串的特定数量的宽字符追加到另一个宽字符串 (函数) [编辑]

编译器支持
独立和宿主
语言
标准库
标准库头文件
命名要求
功能测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用实用程序库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
执行支持库 (C++26)
技术规范
符号索引
外部库

以 null 结尾的字符串
字节字符串
多字节字符串
宽字符串
类
basic_string
basic_string_view (C++17)
char_traits

cppreference.com

命名空间

变体

视图

操作