std::unordered_map
| 
 在标头  
<unordered_map> 定义 | 
||
| 
 template< 
    class Key,  | 
(1) | (C++11 起) | 
| 
 namespace pmr { 
    template<  | 
(2) | (C++17 起) | 
std::unordered_map 是一种关联容器,含有带唯一键的键-值对。搜索、插入和元素移除拥有平均常数时间复杂度。
元素在内部不以任何特定顺序排序,而是组织进桶中。元素放进哪个桶完全依赖于对应键的散列。具有相同散列码的键出现于同一个桶。这允许对单独元素的快速访问,因为一旦计算其散列,它即代表元素所放进的确切的桶。
如果映射的键相等性谓词在传递两个键时返回 true,则它们被认为 等价。如果两个键等价,则散列函数必须对它们返回相同的值。
std::unordered_map 满足容器 (Container) 、知分配器容器 (AllocatorAwareContainer) 和无序关联容器 (UnorderedAssociativeContainer) 的要求。
迭代器失效
| 操作 | 失效 | 
|---|---|
| 所有只读操作、swap、std::swap | 决不 | 
| clear、rehash、reserve、operator= | 始终 | 
| insert、emplace、emplace_hint、operator[] | 仅限重散列的情况 | 
| erase | 仅限指向被擦除元素的迭代器 | 
注解
- swap 函数不会使容器内的任何迭代器失效,但它们会使标记交换区域结尾的迭代器失效。
 
- 指向在容器中存储的键或数据的引用和指针只会因为擦除该元素而失效,即使对应迭代器失效也是如此。
 
模板形参
| 本节未完成 原因:添加模板形参的说明。  | 
成员类型
| 成员类型 | 定义 | 
key_type | 
Key | 
mapped_type | 
T | 
value_type | 
std::pair<const Key, T> | 
size_type | 
无符号整数类型(通常是 std::size_t) | 
difference_type | 
有符号整数类型(通常是 std::ptrdiff_t) | 
hasher | 
Hash | 
key_equal | 
KeyEqual | 
allocator_type | 
Allocator | 
reference | 
value_type& | 
const_reference | 
const value_type& | 
pointer | 
std::allocator_traits<Allocator>::pointer | 
const_pointer | 
std::allocator_traits<Allocator>::const_pointer | 
iterator | 
指向 value_type 的常老式向前迭代器 (LegacyForwardIterator) | 
const_iterator | 
指向 const value_type 的老式向前迭代器 (LegacyForwardIterator) | 
local_iterator | 
迭代器类型,其类别、值、差、指针和引用类型都与 iterator 相同。能用此迭代器在桶内遍历,但不能跨桶。  | 
const_local_iterator | 
迭代器类型,其类别、值、差、指针和引用类型都与 const_iterator 相同。此迭代器可用于在桶内遍历,但不能跨桶。  | 
node_type(C++17 起) | 
表示容器节点的节点句柄特化 | 
insert_return_type(C++17 起) | 
描述插入 node_type 结果的类型,下列类型的特化template<class Iter, class NodeType>  | 
成员函数
构造 unordered_map(公开成员函数)  | 
|
析构 unordered_map(公开成员函数)  | 
|
| 将值赋给容器 (公开成员函数)  | 
|
| 返回关联的分配器 (公开成员函数)  | 
|
迭代器 | 
|
| 返回指向起始的迭代器 (公开成员函数)  | 
|
| 返回指向末尾的迭代器 (公开成员函数)  | 
|
容量 | 
|
| 检查容器是否为空 (公开成员函数)  | 
|
| 返回元素数 (公开成员函数)  | 
|
| 返回可容纳的最大元素数 (公开成员函数)  | 
|
修改器 | 
|
| 清除内容 (公开成员函数)  | 
|
| 插入元素或节点 (C++17 起) (公开成员函数)  | 
|
| 
 (C++23) 
 | 
插入一个元素范围 (公开成员函数)  | 
| 
 (C++17) 
 | 
插入元素,或若键已存在则赋值给当前元素 (公开成员函数)  | 
| 原位构造元素 (公开成员函数)  | 
|
| 使用提示原位构造元素 (公开成员函数)  | 
|
| 
 (C++17) 
 | 
若键不存在则原位插入,若键存在则不做任何事 (公开成员函数)  | 
| 擦除元素 (公开成员函数)  | 
|
| 交换内容 (公开成员函数)  | 
|
| 
 (C++17) 
 | 
提取容器中的节点 (公开成员函数)  | 
| 
 (C++17) 
 | 
从另一容器合并节点 (公开成员函数)  | 
查找 | 
|
| 带越界检查访问指定的元素 (公开成员函数)  | 
|
| 访问或插入指定的元素 (公开成员函数)  | 
|
| 返回匹配特定键的元素数量 (公开成员函数)  | 
|
| 寻找带有特定键的元素 (公开成员函数)  | 
|
| 
 (C++20) 
 | 
检查容器是否含有带特定键的元素 (公开成员函数)  | 
| 返回匹配特定键的元素范围 (公开成员函数)  | 
|
桶接口 | 
|
| 返回指向指定的桶的开始的迭代器 (公开成员函数)  | 
|
| 返回指向指定的桶的末尾的迭代器 (公开成员函数)  | 
|
| 返回桶数 (公开成员函数)  | 
|
| 返回桶的最大数量 (公开成员函数)  | 
|
| 返回特定的桶中的元素数量 (公开成员函数)  | 
|
| 返回带有特定键的桶 (公开成员函数)  | 
|
散列策略 | 
|
| 返回每个桶的平均元素数量 (公开成员函数)  | 
|
| 管理每个桶的平均元素数量的最大值 (公开成员函数)  | 
|
| 预留至少指定数量的桶并重新生成散列表 (公开成员函数)  | 
|
| 为至少指定数量的元素预留空间并重新生成散列表 (公开成员函数)  | 
|
观察器 | 
|
| 返回用于对键求散列的函数 (公开成员函数)  | 
|
| 返回用于比较键的相等性的函数 (公开成员函数)  | 
|
非成员函数
| 
 (C++11)(C++11)(C++20 中移除) 
 | 
比较 unordered_map 中的值 (函数模板)  | 
| 
 (C++11) 
 | 
特化 std::swap 算法 (函数模板)  | 
| 
 (C++20) 
 | 
擦除所有满足特定判别标准的元素 (函数模板)  | 
推导指引 | 
(C++17 起) | 
注解
| 功能特性测试宏 | 值 | 标准 | 功能特性 | 
|---|---|---|---|
__cpp_lib_containers_ranges | 
202202L | (C++23) | 容器的范围构造和插入 | 
示例
#include <iostream> #include <string> #include <unordered_map> int main() { // 创建包含三个字符串的(映射到字符串的)unordered_map std::unordered_map<std::string, std::string> u = { {"红色", "#FF0000"}, {"绿色", "#00FF00"}, {"蓝色", "#0000FF"} }; // 用于打印键值对的辅助 lambda 函数 auto print_key_value = [](const auto& key, const auto& value) { std::cout << "键:[" << key << "] 值:[" << value << "]\n"; }; std::cout << "遍历并打印 unordered_map 的键值对,显式指定类型:\n"; for (const std::pair<const std::string, std::string>& n : u) print_key_value(n.first, n.second); std::cout << "\n通过 C++17 的结构化绑定来遍历并打印 unordered_map 的键值对:\n"; for (const auto& [key, value] : u) print_key_value(key, value); // 向 unordered_map 中添加两项 u["黑色"] = "#000000"; u["白色"] = "#FFFFFF"; std::cout << "\n通过键输出值:\n" "红色的十六进制表示:[" << u["红色"] << "]\n" "黑色的十六进制表示:[" << u["黑色"] << "]\n\n"; std::cout << "通过以先前不存在的键使用 operator[] 来插入新的键值对:\n"; print_key_value("新键", u["新键"]); std::cout << "\n通过使用 auto 来遍历并打印键值对;\n" "现在`新键`是映射中的一个键:\n"; for (const auto& n : u) print_key_value(n.first, n.second); }
可能的输出:
遍历并打印 unordered_map 的键值对,显式指定类型: 键:[蓝色] 值:[#0000FF] 键:[绿色] 值:[#00FF00] 键:[红色] 值:[#FF0000] 通过 C++17 的结构化绑定来遍历并打印 unordered_map 的键值对: 键:[蓝色] 值:[#0000FF] 键:[绿色] 值:[#00FF00] 键:[红色] 值:[#FF0000] 通过键输出值: 红色的十六进制表示:[#FF0000] 黑色的十六进制表示:[#000000] 通过以先前不存在的键使用 operator[] 来插入新的键值对: 键:[新键] 值:[] 通过使用 auto 来遍历并打印键值对; 现在`新键`是映射中的一个键: 键:[新键] 值:[] 键:[白色] 值:[#FFFFFF] 键:[黑色] 值:[#000000] 键:[蓝色] 值:[#0000FF] 键:[绿色] 值:[#00FF00] 键:[红色] 值:[#FF0000]
缺陷报告
下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。
| 缺陷报告 | 应用于 | 出版时的行为 | 正确行为 | 
|---|---|---|---|
| LWG 2050 | C++11 | reference、const_reference、pointer 和const_pointer 的定义都基于 allocator_type | 
基于 value_type 和std::allocator_traits  | 
参阅
| 
 (C++11 起) 
 | 
键值对的集合,按照键生成散列 (类模板)  | 
| 键值对的集合,按照键排序,键是唯一的 (类模板)  | 
|
| 
 (C++23) 
 | 
适配两个容器以提供按唯一键排序的键值对集合 (类模板)  |