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

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

将字符插入到字符串中。

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

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 指向的元素（如果有）之前插入字符 ch 的 count 份副本。

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

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

(since 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 上的有效迭代器，则行为未定义。

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 的要求。

[编辑] 返回值

1-5) *this

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

10,11) *this

[编辑] 异常

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 抛出异常，则重新抛出该异常。

(since C++20)

如果由于任何原因抛出异常，则此函数不起作用（强异常安全保证）。

[编辑] 示例

运行此代码

#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);
}

[编辑] 缺陷报告

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

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

[编辑] 参见

insert_range (C++23)	插入字符范围 (public member function) [编辑]
append	将字符追加到末尾 (public member function) [编辑]
push_back	将字符追加到末尾 (public member function) [编辑]

编译器支持
独立式和宿主式
语言
标准库
标准库头文件
具名要求
Feature test macros (C++20)
语言支持库
Concepts library (C++20)
诊断库
内存管理库
Metaprogramming library (C++11)
通用工具库
容器库
迭代器库
Ranges library (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
技术规范
符号索引
外部库

cppreference.cn

命名空间

变体

视图

操作