Namespaces
Variants

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

From cppreference.net
C++
Strings library
std::basic_string
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 ; ，随后将 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 指向的元素（若存在）之前插入 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) 指向首个插入字符副本的迭代器，若未插入字符则返回 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) 在某些情况下会导致歧义 通过将其设为模板来避免歧义

参见

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