C++

參考

<unordered_map>

unordered_map

public member function
<unordered_map>

std::unordered_map::insert

(1)
pair<iterator,bool> insert ( const value_type& val );
(2)
template <class P>    pair<iterator,bool> insert ( P&& val );
(3)
iterator insert ( const_iterator hint, const value_type& val );
(4)
template <class P>    iterator insert ( const_iterator hint, P&& val );
(5)
template <class InputIterator>    void insert ( InputIterator first, InputIterator last );
(6)
void insert ( initializer_list<value_type> il );
插入元素
在 unordered_map 中插入新元素。

僅當其鍵不等於容器中任何其他元素鍵時，才插入每個元素（unordered_map 中的鍵是唯一的）。

這將有效地將容器 size 增加已插入元素的數量。

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

引數

val
要複製到（或移動作為）新元素的值的物件。
版本 (1) 和 (3) 複製元素（即，val保留其內容，容器保留副本）。
版本 (2) 和 (4) 移動元素（即，val失去其內容，該內容被容器中的新元素獲取）。
成員型別value_type是容器中元素的型別，在 unordered_map 中定義為pair<const key_type,mapped_type>，其中成員型別key_type是第一個模板引數（鍵型別）的別名，而mapped_type是第二個模板引數（對映型別，T).
僅當引數型別為 P&& 的簽名被呼叫P可以隱式轉換為value_type.
接受 P&& 引數的簽名僅在 std::is_constructible<value_type,P&&> 為 true 時呼叫。
hint
指向一個位置的迭代器，該位置被建議作為搜尋合適插入點的提示。容器可能會也可能不會使用此值來最佳化操作。無論傳遞的是什麼，元素都將儲存在其相應的桶中。hint.
成員型別const_iterator是一個 forward iterator 型別。
first, last
指定元素範圍的迭代器。範圍中元素的副本[first,last)將插入到 unordered_map 容器中。
請注意，範圍包括 first 和 last 之間的所有元素，包括 first 指向的元素，但不包括 last 指向的元素。
neitherfirstnorlast應該是目標容器中的迭代器。
模板型別可以是任何 input iterator。
il
一個 initializer_list 物件。編譯器將自動從初始化列表宣告器建立此類物件。
成員型別value_type是容器中元素的型別，在 unordered_map 中定義為pair<const key_type,mapped_type>，其中成員型別key_type是第一個模板引數（鍵型別）的別名，而mapped_type是第二個模板引數（對映型別，T).

返回值

在版本 (1) 和 (2) 中，該函式返回一個 pair 物件，其第一個元素是一個迭代器，指向容器中新插入的元素或鍵等效的元素，以及一個bool值，指示元素是否成功插入。

在版本 (3) 和 (4) 中，該函式返回一個迭代器，指向容器中新插入的元素或鍵等效的元素。

版本 (5) 和 (6) 不返回值。

成員型別iterator是一個 forward iterator 型別。

新元素的儲存使用allocator_traits<allocator_type>::construct()分配，這在失敗時可能會丟擲異常（對於預設的 allocator，bad_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
 
// unordered_map::insert
#include <iostream>
#include <string>
#include <unordered_map>

int main ()
{
  std::unordered_map<std::string,double>
              myrecipe,
              mypantry = {{"milk",2.0},{"flour",1.5}};

  std::pair<std::string,double> myshopping ("baking powder",0.3);

  myrecipe.insert (myshopping);                        // copy insertion
  myrecipe.insert (std::make_pair<std::string,double>("eggs",6.0)); // move insertion
  myrecipe.insert (mypantry.begin(), mypantry.end());  // range insertion
  myrecipe.insert ( {{"sugar",0.8},{"salt",0.1}} );    // initializer list insertion

  std::cout << "myrecipe contains:" << std::endl;
  for (auto& x: myrecipe)
    std::cout << x.first << ": " << x.second << std::endl;

  std::cout << std::endl;
  return 0;
}

可能的輸出
myrecipe contains:
salt: 0.1
eggs: 6
sugar: 0.8
baking powder: 0.3
flour: 1.5
milk: 2


複雜度

單元素插入
平均情況：常量。
最壞情況：容器大小的線性。
多元素插入
平均情況：已插入元素數量的線性。
最壞情況N*(size+1)：插入的元素數量乘以容器大小加一。
可能會觸發 rehash（不包含在上述複雜度中）。

迭代器有效性

在大多數情況下，插入後容器中的所有迭代器都保持有效。唯一的例外是當容器的增長強制重新雜湊時。在這種情況下，容器中的所有迭代器都將失效。

如果插入操作後新容器的 size 將超過其容量閾值（計算為容器的 bucket_count 乘以其 max_load_factor），則會強制執行 rehash。

無論如何，指向 unordered_map 容器中元素的引用都保持有效，即使在 rehash 之後也是如此。

另見

unordered_map::emplace
構造並插入元素 (公開成員函式)
unordered_map::emplace_hint
帶提示地構造並插入元素 (公共成員函式)
unordered_map::operator[]
訪問元素 (公開成員函式)
unordered_map::at
訪問元素 (公開成員函式)