std::unordered_map

定义于头文件 `<unordered_map>`
template< class Key, class T, class Hash = std::hash<Key>, class KeyEqual = std::equal_to<Key>, class Allocator = std::allocator<std::pair<const Key, T>> > class unordered_map;	(1)	(since C++11)
namespace pmr { template< class Key, class T, class Hash = std::hash<Key>, class KeyEqual = std::equal_to<Key> > using unordered_map = std::unordered_map<Key, T, Hash, KeyEqual, std::pmr::polymorphic_allocator<std::pair<const Key, T>>>; }	(2)	(since C++17)

std::unordered_map 是一个关联容器，包含键值对，其中键是唯一的。元素的搜索、插入和移除操作平均时间复杂度为常数。

在内部，元素不以任何特定顺序排序，而是组织成桶（buckets）。元素被放入哪个桶完全取决于其键的哈希值。具有相同哈希码的键会出现在同一个桶中。这允许快速访问单个元素，因为一旦计算出哈希值，它就指向元素所在的精确桶。

当传递两个键时，如果映射的键相等谓词返回 true，则认为这两个键等价。如果两个键等价，则哈希函数必须为这两个键返回相同的值。

std::unordered_map 满足 Container、 AllocatorAwareContainer、 UnorderedAssociativeContainer 的要求。

std::unordered_map 的所有成员函数都是 constexpr：可以在常量表达式的求值中创建和使用 std::unordered_map 对象。

但是，std::unordered_map 对象通常不能是 constexpr，因为任何动态分配的存储都必须在相同的常量表达式求值中释放。

(since C++26)

类型	定义
`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`	LegacyForwardIterator 和 ConstexprIterator(since C++26) 指向 `value_type`[编辑]
`const_iterator`	LegacyForwardIterator 和 ConstexprIterator(since C++26) 指向 const value_type[编辑]
`local_iterator`	一种迭代器类型，其类别、值、差值、指针和引用类型与 `iterator` 相同。此迭代器可用于迭代单个桶，但不能跨桶迭代[编辑]
`const_local_iterator`	一种迭代器类型，其类别、值、差值、指针和引用类型与 `const_iterator` 相同。此迭代器可用于迭代单个桶，但不能跨桶迭代[编辑]
`node_type` (since C++17)	表示容器节点的 node handle 的特化[编辑]
`insert_return_type` (since C++17)	描述插入 `node_type` 结果的类型，是以下内容的特化： template<class Iter, class NodeType> struct /unspecified/ { Iter position; bool inserted; NodeType node; }; 使用模板参数 `iterator` 和 `node_type` 实例化。[编辑]

[编辑] 成员函数

(constructor)	构造 `unordered_map` (public member function) [编辑]
(destructor)	析构 `unordered_map` (public member function) [编辑]
operator=	为容器赋值 (public member function) [编辑]
get_allocator	返回关联的分配器 (public member function) [编辑]
迭代器
begincbegin	返回指向开始的迭代器 (public member function) [编辑]
endcend	返回指向末尾的迭代器 (public member function) [编辑]
容量
empty	检查容器是否为空 (public member function) [编辑]
size	返回元素数量 (public member function) [编辑]
max_size	返回最大可能元素数量 (public member function) [编辑]
修改器
clear	清除内容 (public member function) [编辑]
insert	插入元素或节点(since C++17) (public member function) [编辑]
insert_range (C++23)	插入元素范围 (public member function) [编辑]
insert_or_assign (C++17)	插入元素，如果键已存在则赋值给当前元素 (public member function) [编辑]
emplace	就地构造元素 (public member function) [编辑]
emplace_hint	使用提示就地构造元素 (public member function) [编辑]
try_emplace (C++17)	如果键不存在则就地插入，如果键存在则不执行任何操作 (public member function) [编辑]
erase	erases elements (public member function) [编辑]
swap	交换内容 (public member function) [编辑]
extract (C++17)	从容器中提取节点 (public member function) [编辑]
merge (C++17)	从另一个容器拼接节点 (public member function) [编辑]
查找
at	访问指定元素，带边界检查 (public member function) [编辑]
operator[]	访问或插入指定元素 (public member function) [编辑]
count	返回匹配特定键的元素数量 (public member function) [编辑]
find	查找具有特定键的元素 (public member function) [编辑]
contains (C++20)	检查容器是否包含具有特定键的元素 (public member function) [编辑]
equal_range	返回匹配特定键的元素范围 (public member function) [编辑]
桶接口
begin(size_type)cbegin(size_type)	返回指向指定桶开始的迭代器 (public member function) [编辑]
end(size_type)cend(size_type)	返回指向指定桶末尾的迭代器 (public member function) [编辑]
bucket_count	返回桶的数量 (public member function) [编辑]
max_bucket_count	返回最大桶数量 (public member function) [编辑]
bucket_size	返回特定桶中的元素数量 (public member function) [编辑]
bucket	返回特定键的桶 (public member function) [编辑]
哈希策略
load_factor	返回每个桶的平均元素数量 (public member function) [编辑]
max_load_factor	管理每个桶的最大平均元素数量 (public member function) [编辑]
rehash	预留至少指定数量的桶并重新生成哈希表 (public member function) [编辑]
reserve	为至少指定数量的元素预留空间并重新生成哈希表 (public member function) [编辑]
观察器
hash_function	返回用于哈希键的函数 (public member function) [编辑]
key_eq	返回用于比较键是否相等的函数 (public member function) [编辑]

[编辑] 非成员函数

operator==operator!= (C++11)(C++11)(removed in C++20)	比较 unordered_map 中的值 (function template) [编辑]
std::swap(std::unordered_map) (C++11)	特化 std::swap 算法 (function template) [编辑]
erase_if(std::unordered_map) (C++20)	擦除所有满足特定条件的元素 (function template) [编辑]

推导指引	(since C++17)

[编辑] 注释

Feature-test 宏	值	Std	特性
`__cpp_lib_containers_ranges`	`202202L`	(C++23)	容器的范围构造和插入
`__cpp_lib_constexpr_containers`	`202502L`	(C++26)	constexpr `std::unordered_map`

[编辑] 示例

运行此代码

#include <iostream>
#include <string>
#include <unordered_map>
 
int main()
{
    // Create an unordered_map of three strings (that map to strings)
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
 
    // Helper lambda function to print key-value pairs
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Key:[" << key << "] Value:[" << value << "]\n";
    };
 
    std::cout << "Iterate and print key-value pairs of unordered_map, being\n"
                 "explicit with their types:\n";
    for (const std::pair<const std::string, std::string>& n : u)
        print_key_value(n.first, n.second);
 
    std::cout << "\nIterate and print key-value pairs using C++17 structured binding:\n";
    for (const auto& [key, value] : u)
        print_key_value(key, value);
 
    // Add two new entries to the unordered_map
    u["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
 
    std::cout << "\nOutput values by key:\n"
                 "The HEX of color RED is:[" << u["RED"] << "]\n"
                 "The HEX of color BLACK is:[" << u["BLACK"] << "]\n\n";
 
    std::cout << "Use operator[] with non-existent key to insert a new key-value pair:\n";
    print_key_value("new_key", u["new_key"]);
 
    std::cout << "\nIterate and print key-value pairs, using `auto`;\n"
                 "new_key is now one of the keys in the map:\n";
    for (const auto& n : u)
        print_key_value(n.first, n.second);
}

可能的输出

Iterate and print key-value pairs of unordered_map, being
explicit with their types:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
 
Iterate and print key-value pairs using C++17 structured binding:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
 
Output values by key:
The HEX of color RED is:[#FF0000]
The HEX of color BLACK is:[#000000]
 
Use operator[] with non-existent key to insert a new key-value pair:
Key:[new_key] Value:[]
 
Iterate and print key-value pairs, using `auto`;
new_key is now one of the keys in the map:
Key:[new_key] Value:[]
Key:[WHITE] Value:[#FFFFFF]
Key:[BLACK] Value:[#000000]
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]

[编辑] 缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

DR	应用于	已发布行为	正确行为
LWG 2050	C++11	`reference`、 `const_reference`、 `pointer` 的定义和 `const_pointer` 基于 `allocator_type`	基于 `value_type` 和 std::allocator_traits

[编辑] 参见

unordered_multimap (C++11)	键值对的集合，通过键哈希 (class template) [编辑]
map	键值对的集合，按键排序，键是唯一的 (class template) [编辑]
flat_map (C++23)	适配两个容器以提供键值对的集合，按唯一键排序 (类模板) [编辑]

编译器支持
独立和宿主
语言
标准库
标准库头文件
具名要求
Feature test macros (C++20)
语言支持库
Concepts library (C++20)
诊断库
内存管理库
Metaprogramming library (C++11)
通用工具库
容器库
迭代器库
Ranges library (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
技术规范
符号索引
外部库

序列
array (C++11)
vector
vector<bool>
inplace_vector (C++26)
hive (C++26)
deque
forward_list (C++11)
list
关联
set
multiset
map
multimap
无序关联
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
适配器
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
视图
span (C++20)
mdspan (C++23)
表格
迭代器失效
成员函数表
非成员函数表

操作	失效情况
所有只读操作、 swap、 std::swap	从不
clear、 rehash、 reserve、 operator=	总是
insert、 emplace、 emplace_hint、 operator[]	仅当引起重哈希时
erase	仅对被擦除的元素失效

cppreference.cn

命名空间

变体

视图

操作

std::unordered_map

目录

[编辑] 迭代器失效

[编辑] 注释

[编辑] 模板参数

[编辑] 成员类型

[编辑] 成员函数

迭代器

容量

修改器

查找

桶接口

哈希策略

观察器

[编辑] 非成员函数

推导指引

[编辑] 注释

[编辑] 示例

[编辑] 缺陷报告

[编辑] 参见

导航

工具箱