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*或范围,则会导致*未定义行为*。

另见