public member function
<map>

std::map::insert

单个元素 (1)
pair<iterator,bool> insert (const value_type& val);
带提示 (2)
iterator insert (iterator position, const value_type& val);
范围 (3)
template <class InputIterator>  void insert (InputIterator first, InputIterator last);
单个元素 (1)
pair<iterator,bool> insert (const value_type& val);template <class P> pair<iterator,bool> insert (P&& val);
带提示 (2)
iterator insert (const_iterator position, const value_type& val);template <class P> iterator insert (const_iterator position, P&& val);
范围 (3)
template <class InputIterator>  void insert (InputIterator first, InputIterator last);
初始化列表 (4)
void insert (initializer_list<value_type> il);
插入元素
通过插入新元素来扩展容器,从而有效地增加容器的 size

由于 map 中的元素键是唯一的,插入操作会检查每个插入的元素是否具有与容器中已存在的元素等效的键,如果存在,则不插入该元素,并返回指向该现有元素的迭代器(如果函数返回一个值)。

有关允许重复元素的类似容器,请参阅 multimap

插入 map 元素的另一种方法是使用成员函数 map::operator[]

在内部, map 容器根据其 比较对象 指定的标准,按键对所有元素进行排序。元素始终按照该排序插入到其相应的位置。

参数决定了插入多少元素以及它们被初始化为哪个值。

参数

val
要复制(或移动)到插入元素的值。
成员类型value_type是容器中元素的类型,在 map 中定义为pair<const key_type,mapped_type>(请参阅 map 成员类型)。
模板参数P应为可转换为value_type.
接受 P&& 参数的签名仅在 std::is_constructible<value_type,P&&>true 时调用。
如果已知P被实例化为引用类型,将复制参数。
position
元素可插入位置的提示。
如果 *position* 指向将 **前置** 插入元素,则该函数优化其插入时间。
如果 *position* 指向将 **跟在** 插入元素之后(或指向 end,如果它是最后一个),则该函数优化其插入时间。
请注意,这只是一个提示,不会强制新元素插入到 map 容器中的该位置(map 中的元素始终遵循根据其键确定的特定顺序)。
成员类型iteratorconst_iteratormap 中定义为指向元素的 双向迭代器 类型。
first, last
指定元素范围的迭代器。范围中元素的副本[first,last)被插入到容器中。
请注意,范围包括 first 和 last 之间的所有元素,包括 first 指向的元素,但不包括 last 指向的元素。
函数模板参数InputIterator应为指向元素类型的 输入迭代器 类型,这些元素来自value_type对象的类型的元素。
il
一个 initializer_list 对象。将插入这些元素的副本。
这些对象是从初始化列表声明符自动构造的。
成员类型value_type是容器中包含的元素的类型,在 map 中定义为pair<const key_type,mapped_type>(请参阅 map 成员类型)。

返回值

单个元素版本 (1) 返回一个 pair,其成员pair::first设置为指向新插入元素或 map 中具有等效键的元素的迭代器。该pair::second成员设置为true如果插入了新元素,或者false如果已存在等效键。

带有提示的版本 (2) 返回指向新插入元素或 map 中已具有等效键的元素的迭代器。

成员类型iterator是指向元素的双向迭代器类型。
pair是声明在<utility>中的类模板(参见pair)。

示例

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
35
36
37
38
39
// map::insert (C++98)
#include <iostream>
#include <map>

int main ()
{
  std::map<char,int> mymap;

  // first insert function version (single parameter):
  mymap.insert ( std::pair<char,int>('a',100) );
  mymap.insert ( std::pair<char,int>('z',200) );

  std::pair<std::map<char,int>::iterator,bool> ret;
  ret = mymap.insert ( std::pair<char,int>('z',500) );
  if (ret.second==false) {
    std::cout << "element 'z' already existed";
    std::cout << " with a value of " << ret.first->second << '\n';
  }

  // second insert function version (with hint position):
  std::map<char,int>::iterator it = mymap.begin();
  mymap.insert (it, std::pair<char,int>('b',300));  // max efficiency inserting
  mymap.insert (it, std::pair<char,int>('c',400));  // no max efficiency inserting

  // third insert function version (range insertion):
  std::map<char,int> anothermap;
  anothermap.insert(mymap.begin(),mymap.find('c'));

  // showing contents:
  std::cout << "mymap contains:\n";
  for (it=mymap.begin(); it!=mymap.end(); ++it)
    std::cout << it->first << " => " << it->second << '\n';

  std::cout << "anothermap contains:\n";
  for (it=anothermap.begin(); it!=anothermap.end(); ++it)
    std::cout << it->first << " => " << it->second << '\n';

  return 0;
}
输出
element 'z' already existed with a value of 200
mymap contains:
a => 100
b => 300
c => 400
z => 200
anothermap contains:
a => 100
b => 300


复杂度

如果插入单个元素,通常是 log(size),但如果提供了提示且提示的位置是最佳的,则为摊还常数。

如果插入 N 个元素,Nlog(size+N)通常,但线性于size+N如果元素已根据容器使用的排序标准进行排序。
如果插入 N 个元素,Nlog(size+N).
如果范围已排序,实现可能会进行优化。

迭代器有效性

没有变化。

数据竞争

容器已修改。
并发访问现有元素是安全的,但迭代容器中的范围则不是。

异常安全

如果插入单个元素,在发生异常的情况下,容器不会发生变化(强异常安全保证)。
否则,容器保证最终处于有效状态(基本异常安全保证)。
如果不支持带有元素构造适当参数的 allocator_traits::construct,或者指定了无效的position,则会导致未定义行为

另见