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)