public member function
<list>

std::list::insert

single element (1)
iterator insert (iterator position, const value_type& val);
fill (2)
    void insert (iterator position, size_type n, const value_type& val);
range (3)
template <class InputIterator>    void insert (iterator position, InputIterator first, InputIterator last);
single element (1)
iterator insert (const_iterator position, const value_type& val);
fill (2)
iterator insert (const_iterator position, size_type n, const value_type& val);
range (3)
template <class InputIterator>iterator insert (const_iterator position, InputIterator first, InputIterator last);
move (4)
iterator insert (const_iterator position, value_type&& val);
initializer list (5)
iterator insert (const_iterator position, initializer_list<value_type> il);
插入元素
該容器透過在指定*position*的元素之前插入新元素來擴充套件。

這會有效地將list大小增加插入元素的數量。

與其他標準序列容器不同,listforward_list容器專門設計用於在任何位置(即使在序列中間)高效地插入和刪除元素。

引數決定了插入多少元素以及它們將被初始化為哪個值。

引數

position
新元素將被插入的容器中的位置。
iterator是一個成員型別,定義為指向元素的 雙向迭代器型別。
val
要複製(或移動)到插入元素的值。
成員型別value_type是容器中元素的型別,在list中定義為第一個模板引數(T).
n
要插入的元素數量。每個元素都將使用*val*的副本進行初始化。
成員型別size_type是一種無符號整型型別。
first, last
指定元素範圍的迭代器。範圍中元素的副本[first,last)將被插入到*position*(按相同順序)。
請注意,範圍包括 first 和 last 之間的所有元素,包括 first 指向的元素,但不包括 last 指向的元素。
函式模板引數InputIterator應為指向型別元素的輸入迭代器,該型別可以被隱式轉換為value_type物件的型別的元素。
il
一個initializer_list物件。這些元素的副本將被插入到*position*(按相同順序)。
這些物件是從初始化列表宣告符自動構造的。
成員型別value_type是容器中元素的型別,在list中定義為第一個模板引數(T).

返回值

指向新插入的第一個元素的迭代器。

成員型別iterator是指向元素的雙向迭代器型別。

新元素的儲存使用容器的 allocator 分配,分配失敗時可能會丟擲異常(對於預設 allocatorbad_alloc如果分配請求不成功,則丟擲)。

示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// inserting into a list
#include <iostream>
#include <list>
#include <vector>

int main ()
{
  std::list<int> mylist;
  std::list<int>::iterator it;

  // set some initial values:
  for (int i=1; i<=5; ++i) mylist.push_back(i); // 1 2 3 4 5

  it = mylist.begin();
  ++it;       // it points now to number 2           ^

  mylist.insert (it,10);                        // 1 10 2 3 4 5

  // "it" still points to number 2                      ^
  mylist.insert (it,2,20);                      // 1 10 20 20 2 3 4 5

  --it;       // it points now to the second 20            ^

  std::vector<int> myvector (2,30);
  mylist.insert (it,myvector.begin(),myvector.end());
                                                // 1 10 20 30 30 20 2 3 4 5
                                                //               ^
  std::cout << "mylist contains:";
  for (it=mylist.begin(); it!=mylist.end(); ++it)
    std::cout << ' ' << *it;
  std::cout << '\n';

  return 0;
}
輸出
mylist contains: 1 10 20 30 30 20 2 3 4 5


複雜度

線性時間複雜度,與插入的元素數量成正比(複製/移動構造)。

迭代器有效性

沒有變化。

資料競爭

容器將被修改。
不會訪問任何已包含的元素。併發訪問或修改不同的元素是安全的,但訪問包含*position*的範圍則不是。

異常安全

強保證:如果丟擲異常,容器沒有發生變化。
如果不支援具有適當引數的allocator_traits::construct進行元素構造,或者指定了無效的*position*或範圍,則會導致*未定義行為*。

另見