std::unordered_map<Key,T,Hash,KeyEqual,Allocator>::insert
来自 cppreference.cn
| 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) |
