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

basic_string& insert( size_type index, size_type count, CharT ch );	(1)	(自 C++20 起为 constexpr)
basic_string& insert( size_type index, const CharT* s );	(2)	(自 C++20 起为 constexpr)
basic_string& insert( size_type index, const CharT* s, size_type count );	(3)	(自 C++20 起为 constexpr)
basic_string& insert( size_type index, const basic_string& str );	(4)	(自 C++20 起为 constexpr)
	(5)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count );			(直到 C++14)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count = npos );			(自 C++14 起) (自 C++20 起为 constexpr)
		(6)
iterator insert( iterator pos, CharT ch );				(直到 C++11)
iterator insert( const_iterator pos, CharT ch );				(自 C++11 起) (自 C++20 起为 constexpr)
			(7)
void insert( iterator pos, size_type count, CharT ch );					(直到 C++11)
iterator insert( const_iterator pos, size_type count, CharT ch );					(自 C++11 起) (自 C++20 起为 constexpr)
				(8)
template< class InputIt > void insert( iterator pos, InputIt first, InputIt last );						(直到 C++11)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last );						(自 C++11 起) (自 C++20 起为 constexpr)
iterator insert( const_iterator pos, std::initializer_list<CharT> ilist );					(9)	(自 C++11 起) (自 C++20 起为 constexpr)
template< class StringViewLike > basic_string& insert( size_type index, const StringViewLike& t );					(10)	(自 C++17 起) (自 C++20 起为 constexpr)
template< class StringViewLike > basic_string& insert( size_type index, const StringViewLike& t, size_type t_index, size_type count = npos );					(11)	(自 C++17 起) (自 C++20 起为 constexpr)

在字符串中插入字符。

1) 在位置 index 插入 count 个字符 ch 的副本。

2) 在位置 index 插入 s 指向的以空字符结尾的字符串。使用 Traits::length(s) 确定字符串的长度，直到第一个空字符。

3) 在位置 index 插入范围 [s, s + count) 中的字符。范围可以包含空字符。

4) 在位置 index 插入字符串 str。

5) 在位置 index 插入一个字符串，该字符串通过 str.substr(s_index, count) 获得。

6) 在 pos 指向的字符之前插入字符 ch。

7) 在 pos 指向的元素（如果有）之前插入 count 个字符 ch 的副本。

8) 在 pos 指向的元素（如果有）之前插入范围 [first, last) 中的字符，如同使用 insert(pos - begin(), basic_string(first, last, get_allocator()))。

如果 InputIt 不满足 LegacyInputIterator，则此重载不会参与重载解析。

(自 C++11 起)

9) 在 pos 指向的元素（如果有）之前插入来自初始化列表 ilist 的元素。

10) 隐式将 t 转换为字符串视图 sv，如同使用 std::basic_string_view<CharT, Traits> sv = t;，然后在 index 指向的元素（如果有）之前插入来自 sv 的元素，如同使用 insert(index, sv.data(), sv.size())。

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

11) 隐式将 t 转换为字符串视图 sv ，如同使用 std::basic_string_view<CharT, Traits> sv = t; 一样，然后在由 index 指向的元素（如果有）之前插入来自 sv 的子视图 [t_index, t_index + count) 中的字符。

如果请求的子视图超过 sv 的末尾，或者如果 count == npos，则生成的子视图为 [t_index, sv.size())。
如果 t_index > sv.size()，或者如果 index > 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 时参与重载解析。

如果 pos 不是 *this 上的有效迭代器，则行为未定义。

[edit] 参数

index	-	插入内容的位置
pos	-	要插入字符之前的迭代器
ch	-	要插入的字符
count	-	要插入的字符数量
s	-	指向要插入的字符字符串的指针
str	-	要插入的字符串
first, last	-	定义要插入的字符的范围
s_index	-	要插入的 str 中第一个字符的位置
ilist	-	std::initializer_list，用于插入其中的字符
t	-	对象（可转换为 std::basic_string_view），用于插入其中的字符
t_index	-	要插入的 t 中第一个字符的位置
类型要求
- `InputIt` 必须满足 LegacyInputIterator 的要求。

[edit] 返回值

1-5) *this

6-9) 指向第一个插入字符的副本的迭代器，或者如果未插入任何字符（count == 0 或 first == last 或 ilist.size() == 0），则为 pos

10,11) *this

[edit] 异常

1-4,10) 如果 index > size()，则抛出 std::out_of_range。

5) 如果 index > size() 或者如果 s_index > str.size()，则抛出 std::out_of_range。

11) 如果 index > size() 或者如果 t_index > sv.size()，则抛出 std::out_of_range。

在所有情况下，如果 size() + ins_count > max_size()，其中 ins_count 是将要插入的字符数量，则抛出 std::length_error。

在所有情况下，如果 std::allocator_traits<Allocator>::allocate 抛出异常，则会重新抛出该异常。

(自 C++20 起)

如果由于任何原因抛出异常，则此函数将不产生任何效果（强异常安全保证）。

[edit] 示例

运行此代码

#include <cassert>
#include <iterator>
#include <string>
 
using namespace std::string_literals;
 
int main()
{
    std::string s = "xmplr";
 
    // insert(size_type index, size_type count, char ch)
    s.insert(0, 1, 'E');
    assert("Exmplr" == s);
 
    // insert(size_type index, const char* s)
    s.insert(2, "e");
    assert("Exemplr" == s);
 
    // insert(size_type index, string const& str)
    s.insert(6, "a"s);
    assert("Exemplar" == s);
 
    // insert(size_type index, string const& str,
    //        size_type s_index, size_type count)
    s.insert(8, " is an example string."s, 0, 14);
    assert("Exemplar is an example" == s);
 
    // insert(const_iterator pos, char ch)
    s.insert(s.cbegin() + s.find_first_of('n') + 1, ':');
    assert("Exemplar is an: example" == s);
 
    // insert(const_iterator pos, size_type count, char ch)
    s.insert(s.cbegin() + s.find_first_of(':') + 1, 2, '=');
    assert("Exemplar is an:== example" == s);
 
    // insert(const_iterator pos, InputIt first, InputIt last)
    {
        std::string seq = " string";
        s.insert(s.begin() + s.find_last_of('e') + 1,
            std::begin(seq), std::end(seq));
        assert("Exemplar is an:== example string" == s);
    }
 
    // insert(const_iterator pos, std::initializer_list<char>)
    s.insert(s.cbegin() + s.find_first_of('g') + 1, {'.'});
    assert("Exemplar is an:== example string." == s);
}

[edit] 缺陷报告

以下更改行为的缺陷报告已追溯应用于先前发布的 C++ 标准。

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

[edit] 另请参阅

insert_range (C++23)	插入一系列字符 (公有成员函数) [edit]
append	将字符追加到末尾 (公有成员函数) [edit]
push_back	将字符追加到末尾 (公有成员函数) [edit]

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

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

cppreference.com

命名空间

变体

视图

操作