C++

参考

<string>

basic_string

public member function
<string>

std::basic_string::insert

string (1)
basic_string& insert (size_type pos, const basic_string& str);
substring (2)
basic_string& insert (size_type pos, const basic_string& str,                      size_type subpos, size_type sublen);
c-string (3)
basic_string& insert (size_type pos, const charT* s);
buffer (4)
basic_string& insert (size_type pos, const charT* s, size_type n);
fill (5)
basic_string& insert (size_type pos, size_type n, charT c);         void insert (iterator p,     size_type n, charT c);
single character (6)
     iterator insert (iterator p, charT c);
range (7)
template <class InputIterator>         void insert (iterator p, InputIterator first, InputIterator last);
string (1)
basic_string& insert (size_type pos, const basic_string& str);
substring (2)
basic_string& insert (size_type pos, const basic_string& str,                      size_type subpos, size_type sublen);
c-string (3)
basic_string& insert (size_type pos, const charT* s);
buffer (4)
basic_string& insert (size_type pos, const charT* s, size_type n);
fill (5)
basic_string& insert (size_type pos,   size_type n, charT c);     iterator insert (const_iterator p, size_type n, charT c);
single character (6)
     iterator insert (const_iterator p, charT c);
range (7)
template <class InputIterator>     iterator insert (iterator p, InputIterator first, InputIterator last);
initializer list (8)
basic_string& insert (const_iterator p, initializer_list<charT> il);
string (1)
basic_string& insert (size_type pos, const basic_string& str);
substring (2)
basic_string& insert (size_type pos, const basic_string& str,                      size_type subpos, size_type sublen = npos);
c-string (3)
basic_string& insert (size_type pos, const charT* s);
buffer (4)
basic_string& insert (size_type pos, const charT* s, size_type n);
fill (5)
basic_string& insert (size_type pos,   size_type n, charT c);     iterator insert (const_iterator p, size_type n, charT c);
single character (6)
     iterator insert (const_iterator p, charT c);
range (7)
template <class InputIterator>     iterator insert (iterator p, InputIterator first, InputIterator last);
initializer list (8)
basic_string& insert (const_iterator p, initializer_list<charT> il);
插入到字符串中
将额外的字符插入到 pos (或 p) 所指示的字符之前的 basic_string 中

(1) string
插入 str 的副本。
(2) substring
插入 str 的子字符串的副本。子字符串是 str 中从字符位置 subpos 开始，跨越 sublen 个字符的部分（或者直到 str 的末尾，如果 str 太短或者 sublen 是 npos）。
(3) c-string
插入由 s 指向的以 null 结尾的字符序列（C 字符串）形成的字符串的副本。
此字符序列的长度由调用确定traits_type::length(s).
(4) buffer
插入由 s 指向的字符数组中的前 n 个字符的副本。
(5) fill
插入字符 c 的 n 个连续副本。
(6) single character
插入字符 c。
(7) range
插入范围内的字符序列的副本[first,last)，以相同的顺序。
(8) initializer list
按相同顺序插入 il 中的每个字符的副本。

参数

pos
插入点：新内容插入在位置 pos 处的字符之前。
如果它大于对象的 length，则会抛出 out_of_range。
注意：第一个字符用值表示0(不是1).
str
另一个具有相同类型的basic_string对象（具有相同的类模板参数charT, 特性 (traits)和Alloc).
subpos
str 中作为子字符串插入到对象中的第一个字符的位置。
如果它大于str的长度，则抛出out_of_range。
注意：str中的第一个字符用值表示0(不是1).
sublen
要复制的子字符串的长度（如果字符串较短，则会复制尽可能多的字符）。
npos 的值表示直到 str 结尾的所有字符。
s
指向字符数组的指针（例如c-string）。
n
要插入的字符数。
c
字符值。
p
指向插入点的迭代器：新内容插入在 p 指向的字符之前。
iterator是一个成员类型，定义为指向 basic_string 字符的 随机访问迭代器类型。
first, last
指向范围内初始位置和最终位置的输入迭代器。 使用的范围是[first,last)，其中包括first和last之间的所有字符，包括first指向的字符，但不包括last指向的字符。
函数模板参数InputIterator应为指向可转换为charT.
il
il
这些对象是从初始化列表声明符自动构造的。

charT是 basic_string 的字符类型（即，它的第一个模板参数）。
成员类型size_type是一种无符号整型类型。

返回值

返回对 basic_string 的引用的签名，返回*this.
那些返回一个iterator的函数，返回一个指向第一个插入字符的迭代器。

成员类型iterator是指向 basic_string 的字符的 随机访问迭代器类型。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
// inserting into a string
#include <iostream>
#include <string>

int main ()
{
  std::string str="to be question";
  std::string str2="the ";
  std::string str3="or not to be";
  std::string::iterator it;

  // used in the same order as described above:
  str.insert(6,str2);                 // to be (the )question
  str.insert(6,str3,3,4);             // to be (not )the question
  str.insert(10,"that is cool",8);    // to be not (that is )the question
  str.insert(10,"to be ");            // to be not (to be )that is the question
  str.insert(15,1,':');               // to be not to be(:) that is the question
  it = str.insert(str.begin()+5,','); // to be(,) not to be: that is the question
  str.insert (str.end(),3,'.');       // to be, not to be: that is the question(...)
  str.insert (it+2,str3.begin(),str3.begin()+3); // (or )

  std::cout << str << '\n';
  return 0;
}
输出
to be, or not to be: that is the question...


复杂度

未指定，但通常最多与新的 字符串长度 成线性关系。

迭代器有效性

与此对象相关的任何迭代器、指针和引用都可能失效。

数据竞争

对象被修改。

异常安全

强保证： 如果抛出异常，则 basic_string 中没有任何更改。

如果已知s未指向足够长的数组，或者 p 或指定范围之一由[first,last)无效，则会导致未定义行为。

如果pos大于字符串长度，或者subpos大于str的长度，则会抛出out_of_range异常。
如果结果 字符串长度 超过 max_size，则会抛出 length_error 异常。
如果该类型使用默认分配器，如果函数需要分配存储空间但失败，则会抛出bad_alloc异常。

另见

basic_string::append
附加到字符串 (public member function)
basic_string::replace
替换字符串的一部分 (public member function)
basic_string::substr
生成子字符串 (公共成员函数)
basic_string::operator=
字符串赋值 (公共成员函数)
basic_string::operator+=
附加到字符串 (public member function)