C++ Reference: Standard C++ Library reference: Containers: map: map: insert

C++官网参考链接：https://cplusplus.com/reference/map/map/insert/

公有成员函数
<map>
std::map::insert
C++98
single element (1)    
pair<iterator,bool> insert (const value_type& val);
with hint (2)    
iterator insert (iterator position, const value_type& val);
range (3)    
template <class InputIterator>  void insert (InputIterator first, InputIterator last);
C++11
single element (1)    
pair<iterator,bool> insert (const value_type& val);
template <class P> pair<iterator,bool> insert (P&& val);
with hint (2)    
iterator insert (const_iterator position, const value_type& val);
template <class P> iterator insert (const_iterator position, P&& val);
range (3)    
template <class InputIterator>  void insert (InputIterator first, InputIterator last);
initializer list (4)    
void insert (initializer_list<value_type> il);
插入元素
通过插入新元素扩展容器，有效地通过插入元素的数量增加容器的size。
因为map中的元素键是唯一的，所以插入操作检查每个插入的元素是否具有与容器中已存在的元素的键相等的键，如果是，则不插入元素，并返回指向该现有元素的iterator（如果函数返回一个值）。
有关允许重复元素的类似容器，请参阅multimap。
在map中插入元素的另一种方法是使用成员函数map::operator[]。
在内部，map容器按照其比较对象（comparison object）指定的标准按键对所有元素进行排序。元素总是按此顺序插入到其各自的位置。
形参决定插入多少元素以及初始化它们的值： 

形参 
val 
值要复制到（或移动作为）插入的元素。
成员类型value_type是容器中元素的类型，在map中定义为pair<const key_type,mapped_type>（参见map成员类型（map member types））。
C++98
模板形参P应该是可转换为value_type的类型。
C++14
只有当std::is_constructible<value_type, p&&>为true时，接受实参类型为P&&的签名才会被调用。

如果P被实例化为引用类型，则复制实参。

position 
提示可以插入元素的位置。
C++98
如果position指向插入元素之前的元素，则该函数优化其插入时间。
C++11
如果position指向插入元素之后的元素（如果是最后一个元素，则指向end ），则函数优化其插入时间。
请注意，这只是一个提示，并不强制将新元素插入到map容器中的该位置（map中的元素总是按照特定的顺序，这取决于它们的键）。
成员类型iterator和const_iterator在map中定义为指向元素的双向iterator（bidirectional iterator）类型。
first,last 
指定元素范围的iterator。在容器中插入范围[first,last)中的元素的副本。
注意，该范围包括first和last之间的所有元素，包括first指向的元素，但不包括last指向的元素。
函数模板实参InputIterator应该是一个输入iterator（input iterator）类型，它指向可以构造value_type对象的类型元素。
il 
一个initializer_list对象。插入这些元素的副本。
这些对象是由初始化器列表声明器自动构造的。
成员类型value_type是容器中包含的元素类型，在map中定义为pair<const key_type,mapped_type>（参见map成员类型（map member types））。

返回值
单元素版本(1)返回一个pair，其成员pair::first设置为一个iterator，该iterator指向新插入的元素或map中具有等价键的元素。如果插入了新元素，pair::second将被设置为true；如果已经存在等价的键，则设置为false。
带有提示(2)的版本返回一个iterator，该iterator指向新插入的元素或在map中已经有等价键的元素。
成员类型iterator是指向元素的双向iterator（bidirectional iterator）类型。
pair是在<utility>中声明的类模板（参见pair）。

用例
// 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;
}
输出： 

复杂度
如果插入单个元素，一般为size中的对数，但如果给出提示且给出的position是最佳的，则为平摊常量。
C++98
如果插入N个元素，一般为Nlog(size+N)，但如果元素已经按照容器使用的相同排序标准排序，则为size+N中的线性。
C++11
如果插入N个元素，则为Nlog(size+N)。
如果范围已经排序，则实现可能会优化。

iterator的有效性
没有变化。

数据竞争
完成容器的修改。
同时访问现有的元素是安全的，但是迭代容器中的范围就不安全了。

异常安全
如果要插入单个元素，在异常情况下容器中不会有任何变化（强保证）。
否则，保证容器以有效状态结束（基本保证）。
如果元素结构的适当实参不支持allocator_traits::construct，或者如果指定了无效的position，则会导致未定义的行为。