C++

參考

<string>

string

public member function
<string>

std::string::insert

string (1)
 string& insert (size_t pos, const string& str);
substring (2)
 string& insert (size_t pos, const string& str, size_t subpos, size_t sublen);
c-string (3)
 string& insert (size_t pos, const char* s);
buffer (4)
 string& insert (size_t pos, const char* s, size_t n);
fill (5)
 string& insert (size_t pos, size_t n, char c);    void insert (iterator p, size_t n, char c);
single character (6)
iterator insert (iterator p, char c);
range (7)
template <class InputIterator>   void insert (iterator p, InputIterator first, InputIterator last);
string (1)
 string& insert (size_t pos, const string& str);
substring (2)
 string& insert (size_t pos, const string& str, size_t subpos, size_t sublen);
c-string (3)
 string& insert (size_t pos, const char* s);
buffer (4)
 string& insert (size_t pos, const char* s, size_t n);
fill (5)
 string& insert (size_t pos,   size_t n, char c);iterator insert (const_iterator p, size_t n, char c);
single character (6)
iterator insert (const_iterator p, char c);
range (7)
template <class InputIterator>iterator insert (iterator p, InputIterator first, InputIterator last);
initializer list (8)
 string& insert (const_iterator p, initializer_list<char> il);
string (1)
 string& insert (size_t pos, const string& str);
substring (2)
 string& insert (size_t pos, const string& str, size_t subpos, size_t sublen = npos);
c-string (3)
 string& insert (size_t pos, const char* s);
buffer (4)
 string& insert (size_t pos, const char* s, size_t n);
fill (5)
 string& insert (size_t pos,   size_t n, char c);iterator insert (const_iterator p, size_t n, char c);
single character (6)
iterator insert (const_iterator p, char c);
range (7)
template <class InputIterator>iterator insert (iterator p, InputIterator first, InputIterator last);
initializer list (8)
 string& insert (const_iterator p, initializer_list<char> il);
插入字串
在由pos (或 p) 指示的字元之前，將附加字元插入到字串中。

(1) string
插入str的副本。
(2) substring
插入str的子字串的副本。 子字串是以字元位置subpos開始並跨越sublen個字元的部分（或者直到str的末尾，如果str太短或sublen為npos）。
(3) c-string
插入由s指向的以null結尾的字元序列（C字串）形成的字串的副本。
(4) buffer
插入由s指向的字元陣列中的前n個字元的副本。
(5) fill
插入n個字元c的連續副本。
(6) single character
插入字元c。
(7) range
插入範圍內的字元序列的副本[first,last)，以相同的順序。
(8) initializer list
以相同順序插入il中每個字元的副本。

size_t 是一個無符號整數型別（與成員型別 string::size_type 相同）。

引數

pos
插入點：新內容插入到位置pos的字元之前。
如果它大於物件的length，則會丟擲out_of_range。
注意：第一個字元用值表示0(不是1).
str
另一個string物件。
subpos
str中作為子字串插入到物件中的第一個字元的位置。
如果它大於str的length，則會丟擲out_of_range。
注意：str中的第一個字元用值表示0(不是1).
sublen
要複製的子字串的長度（如果字串較短，則會複製儘可能多的字元）。
值為npos表示直到str末尾的所有字元。
s
指向字元陣列的指標（例如c-string）。
n
要插入的字元數。
c
字元值。
p
指向插入點的迭代器：新內容插入到p指向的字元之前。
iterator是一個成員型別，定義為指向字串字元的隨機訪問迭代器型別。
first, last
指向範圍內初始位置和最終位置的輸入迭代器。 使用的範圍是[first,last)，其中包括first和last之間的所有字元，包括first指向的字元，但不包括last指向的字元。
函式模板引數InputIterator應為指向可轉換為char.
型別的元素的輸入迭代器型別。
il
這些物件是從初始化列表宣告符自動構造的。

返回值

返回對string的引用的簽名，返回*this.
那些返回一個iterator，返回一個指向插入的第一個字元的迭代器。

成員型別iterator是指向字串字元的隨機訪問迭代器型別。

示例

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...


複雜度

未指定，但通常最多為新字串長度的線性比例。

迭代器有效性

與此物件相關的任何迭代器、指標和引用都可能失效。

資料競爭

物件被修改。

異常安全

強保證： 如果丟擲異常，string 中不會有任何更改。

如果已知s未指向足夠長的陣列，或者如果p或範圍指定的[first,last)無效，則會導致未定義行為。

如果pos大於字串長度，或者如果subpos大於str的長度，則會丟擲out_of_range異常。
如果結果字串長度將超過max_size，則會丟擲length_error異常。
如果函式需要分配儲存空間但失敗，則會丟擲 bad_alloc 異常。

另見

string::append
將字串追加到字串 (公共成員函式)
string::replace
替換字串的一部分 (public member function)
string::substr
生成子字串 (公共成員函式)
string::operator=
字串賦值 (公共成員函式)
string::operator+=
將字串追加到字串 (公共成員函式)