std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::insert
來自 cppreference.com
| std::pair<iterator, bool> insert( const value_type& value ); |
(1) | (C++11 起) |
| std::pair<iterator, bool> insert( value_type&& value ); |
(2) | (C++17 起) |
| template< class P > std::pair<iterator, bool> insert( P&& value ); |
(3) | (C++11 起) |
| iterator insert( const_iterator hint, const value_type& value ); |
(4) | (C++11 起) |
| iterator insert( const_iterator hint, value_type&& value ); |
(5) | (C++17 起) |
| template< class P > iterator insert( const_iterator hint, P&& value ); |
(6) | (C++11 起) |
| template< class InputIt > void insert( InputIt first, InputIt last ); |
(7) | (C++11 起) |
| void insert( std::initializer_list<value_type> ilist ); |
(8) | (C++11 起) |
| insert_return_type insert( node_type&& nh ); |
(9) | (C++17 起) |
| iterator insert( const_iterator hint, node_type&& nh ); |
(10) | (C++17 起) |
如果容器中尚不包含具有等效鍵的元素，則將元素插入容器中。
1-3) 插入 value。
過載 (3) 等價於 emplace(std::forward<P>(value)) 且僅當 std::is_constructible<value_type, P&&>::value == true 時參與過載決議。
4-6) 插入 value，使用 hint 作為非強制性提示以指示搜尋起始位置。
過載 (6) 等價於 emplace_hint(hint, std::forward<P>(value)) 且僅當 std::is_constructible<value_type, P&&>::value == true 時參與過載決議。
9) 如果 nh 是一個空的節點控制代碼，則不執行任何操作。否則，如果容器中還沒有一個鍵等同於 nh.key() 的元素，則插入 nh 所擁有的元素到容器中。如果 nh 非空且 get_allocator() != nh.get_allocator()，則行為未定義。
10) 如果 nh 是一個空的節點控制代碼，則不執行任何操作並返回末尾迭代器。否則，如果容器中還沒有一個鍵等同於 nh.key() 的元素，則插入 nh 所擁有的元素到容器中，並返回指向鍵等同於 nh.key() 的元素的迭代器（無論插入成功或失敗）。如果插入成功，則從 nh 移動，否則它保留對元素的所有權。hint 被用作非強制性提示以指示搜尋起始位置。如果 nh 非空且 get_allocator() != nh.get_allocator()，則行為未定義。
如果操作後元素的新數量大於舊的 max_load_factor() * bucket_count()，則會發生重雜湊。
如果（由於插入而）發生重雜湊，則所有迭代器都將失效。否則（不重雜湊），迭代器不會失效。如果插入成功，則在節點控制代碼中持有時獲取的元素指標和引用將失效，並且在提取前獲取的元素指標和引用將變為有效。(C++17 起)
目錄 |
[編輯] 引數
| hint | - | 迭代器，用作插入內容的建議位置 |
| value | - | 要插入的元素值 |
| first, last | - | 定義要插入的元素源範圍的迭代器對 |
| ilist | - | 要從中插入值的初始化列表 |
| nh | - | 相容的節點控制代碼 |
| 型別要求 | ||
-InputIt 必須滿足 LegacyInputIterator 的要求。 | ||
[編輯] 返回值
4-6) 一個指向已插入元素或阻止插入的元素的迭代器。
7,8) （無）
9) 一個
insert_return_type 型別的物件，其成員初始化如下：- 如果 nh 為空，則
inserted為 false，position為 end()，且node為空。 - 否則，如果插入發生，則
inserted為 true，position指向插入的元素，且node為空。 - 如果插入失敗，則
inserted為 false，node具有 nh 的前一個值，且position指向一個鍵等同於 nh.key() 的元素。
10) 如果 nh 為空，則為末尾迭代器；如果插入發生，則為指向已插入元素的迭代器；如果插入失敗，則為指向鍵等同於 nh.key() 的元素的迭代器。
[編輯] 異常
1-6) 如果因任何原因丟擲異常，這些函式沒有效果（強異常安全保證）。
7,8) 無異常安全保證。
9,10) 如果因任何原因丟擲異常，這些函式沒有效果（強異常安全保證）。
[編輯] 複雜度
1-6) 平均情況：
O(1)，最壞情況：O(size())。7,8) 平均情況：
O(N)，其中 N 為要插入的元素數量。最壞情況：O(N * size() + N)。9,10) 平均情況：
O(1)，最壞情況：O(size())。[編輯] 注意
帶提示的插入 (4-6) 不返回布林值，以便與順序容器（例如 std::vector::insert）的位置插入簽名相容。這使得建立泛型插入器（例如 std::inserter）成為可能。檢查帶提示插入成功的一種方法是比較插入前後 size() 的值。
[編輯] 示例
執行此程式碼
#include <iostream> #include <string> #include <unordered_map> int main () { std::unordered_map<int, std::string> dict = {{1, "one"}, {2, "two"}}; dict.insert({3, "three"}); dict.insert(std::make_pair(4, "four")); dict.insert({{4, "another four"}, {5, "five"}}); const bool ok = dict.insert({1, "another one"}).second; std::cout << "inserting 1 => \"another one\" " << (ok ? "succeeded" : "failed") << '\n'; std::cout << "contents:\n"; for (auto& p : dict) std::cout << ' ' << p.first << " => " << p.second << '\n'; }
可能的輸出
inserting 1 => "another one" failed contents: 5 => five 1 => one 2 => two 3 => three 4 => four
[編輯] 缺陷報告
下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。
| 缺陷報告 | 應用於 | 釋出時的行為 | 正確的行為 |
|---|---|---|---|
| LWG 2005 | C++11 | 過載 (3,6) 僅在 P可隱式轉換為 value_type 時參與過載 |
決議 僅當 value_type 可從 P&& 構造時才參與 |
[編輯] 參閱
| 就地構造元素 (public member function) | |
| 使用提示就地構造元素 (public member function) | |
| (C++17) |
插入元素或如果鍵已存在則賦值給當前元素 (public member function) |
| 建立從引數推斷型別的std::insert_iterator (function template) |
