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

来自cppreference.com
 
C++
 
容器库
 
std::unordered_map
成员函数
迭代器
容量
修改器
unordered_map::insert
(C++17)
(C++17)
(C++17)
(C++17)
查找
(C++20)
桶接口
哈希策略
观察器
非成员函数
(C++20 前)
(C++20)
推导指引(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) 返回由指向被插入元素（或阻止插入的元素）的迭代器和指代插入是否发生的 bool 组成的 std::pair（true 表示进行了插入，false 表示没有插入）。
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"}});
 
    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++11)
 原位构造元素
(公开成员函数)
(C++11)
 使用提示原位构造元素
(公开成员函数)
(C++17)
 插入元素，或若键已存在则赋值给当前元素
(公开成员函数)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/container/unordered_map/insert&oldid=78499”