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)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count );	(5)	(至 C++14)
basic_string& insert( size_type index, const basic_string& str, size_type s_index, size_type count = npos );	(5)		(自 C++14 起) (自 C++20 起为 constexpr)
iterator insert( iterator pos, CharT ch );	(6)	(至 C++11)
iterator insert( const_iterator pos, CharT ch );	(6)		(自 C++11 起) (自 C++20 起为 constexpr)
void insert( iterator pos, size_type count, CharT ch );	(7)	(至 C++11)
iterator insert( const_iterator pos, size_type count, CharT ch );	(7)		(自 C++11 起) (自 C++20 起为 constexpr)
template< class InputIt > void insert( iterator pos, InputIt first, InputIt last );	(8)	(至 C++11)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last );	(8)		(自 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) 在位置 count 处插入字符 ch 的 index 个副本。

2) 在位置 s 处插入由 index 指向的空终止字符序列。字符串长度通过 Traits::length(s) 由第一个空字符确定。

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

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

5) 在位置 str.substr(s_index, count) 处插入由 index 得到的字符串。

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

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

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

若 InputIt 不满足 LegacyInputIterator，则此重载不参与重载决议。

(自 C++11 起)

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

10) 隐式转换 t 为字符串视图 sv，效果如同 std::basic_string_view<CharT, Traits> sv = t;，然后在迭代器 sv 指向的元素（如果有）之前插入 index 中的元素，效果如同 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 指向的元素（如果有）之前插入 [t_index, t_index + count) 的子视图 sv 中的字符。

若请求的子视图超出 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) 指向首个插入字符副本的迭代器，若未插入字符则返回 pos （ count == 0 或 first == last 或 ilist. size ( ) == 0 时）

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 ( ) 则抛出 std::length_error ，其中 ins_count 表示将要插入的字符数量。

在所有情况下，如果 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++标准。

缺陷报告	适用标准	发布时的行为	正确行为
LWG 7	C++98	重载 (8) 引用了不存在的重载版本	正确引用重载 (4)
LWG 847	C++98	未提供异常安全保证	增加强异常安全保证
LWG 2946	C++17	重载 (10) 在某些情况下会导致歧义	通过将其设为模板来避免歧义

参见

insert_range (C++23)	插入字符范围 (公开成员函数)
append	向末尾追加字符 (公开成员函数)
push_back	向末尾追加单个字符 (公开成员函数)

编译器支持
独立环境与托管环境
语言
标准库
标准库头文件
具名要求
特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期与时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (C++26)
技术规范
符号索引
外部库

zh.cppreference.net

Namespaces

Variants

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

目录

参数

返回值

异常

示例

缺陷报告

参见