std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::insert

從 cppreference.com
 
C++
 
容器庫
 
std::unordered_map
成員類型
成員函數
非成員函數
推導指引(C++17)
 
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 時才會參與重載決議。
7) 插入來自範圍 [first, last) 的元素。如果範圍中的多個元素的鍵比較相等，那麼未指定哪個元素會被插入（參考待決的 LWG2844）。
如果 [first, last) 不是有效範圍，或者 first 和/或 last 是指向 *this 中的迭代器，那麼行為未定義。
8) 插入來自初始化式列表 ilist 的元素。如果範圍中的多個元素的鍵比較相等，那麼未指定哪個元素會被插入（參考待決的 LWG2844）。
9) 如果 nh 是空的節點句柄，那麼什麼都不做。否則插入 nh 所擁有的元素到容器，如果容器尚未含有擁有等價於 nh.key() 的鍵的元素。如果 nh 非空且 get_allocator() != nh.get_allocator()，那麼行為未定義。
10) 如果 nh 是空的節點句柄，那麼什麼都不做並返回尾迭代器。否則，插入 nh 所擁有的元素到容器，如果容器尚未含有擁有等價於 nh.key() 的鍵的元素，並返回指向擁有等於 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) 。

[編輯] 返回值

1-3) 由一個指向被插入元素（或指向妨礙插入的元素）的迭代器和一個當且僅當發生插入時被設為 true 的 bool 值構成的對偶。
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) 和 (10)) 不返回布爾值，這是為了與順序容器上的定位插入，如 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 << "插入 1 => \"another one\" " 
              << (ok ? "成功" : "失败") << '\n';
 
    std::cout << "内容：\n";
    for (auto& p : dict)
        std::cout << ' ' << p.first << " => " << p.second << '\n';
}

可能的輸出： 

插入 1 -> "another one" 失败
内容：
 5 => five
 1 => one
 2 => two
 3 => three
 4 => four

[編輯] 缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告 應用於 出版時的行為 正確行為
LWG 2005 C++11 重載 (3) 和 (6) 只有在 P 可以隱式轉換value_type 時才會參與重載決議 只有在 value_type 可以從 P&& 構造時才會參與

[編輯] 參閱

 原位構造元素
(公開成員函數) [編輯]
使用提示原位構造元素
(公開成員函數) [編輯]
(C++17)
 插入元素，或若鍵已存在則賦值給當前元素
(公開成員函數) [編輯]
創建擁有從實參推出的類型的 std::insert_iterator
(函數模板) [編輯]
取自「https://zh.cppreference.com/mwiki/index.php?title=cpp/container/unordered_map/insert&oldid=101082」