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,則會導致未定義行為

另見