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)	(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)	(C++17 起)

std::unordered_map 是一个关联容器，包含键值对，且键是唯一的。元素的查找、插入和删除具有平均常数时间复杂度。

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

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

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

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

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

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

[编辑] 成员函数

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

[编辑] 非成员函数

operator==operator!= (C++11起)(C++11起)(C++20中移除)	比较 unordered_map 中的值 (函数模板) [编辑]
std::swap(std::unordered_map) (C++11)	特化 std::swap 算法 (函数模板) [编辑]
erase_if(std::unordered_map) (C++20)	擦除所有满足特定标准的元素 (函数模板) [编辑]

推导指引

(C++17 起)

[编辑] 注

特性测试宏	值	标准	特性
`__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++ 标准。

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

[编辑] 参阅

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

编译器支持
自由（freestanding）与宿主（hosted）
语言
标准库
标准库头文件
具名要求
特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (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

目录

[编辑] 迭代器失效

[编辑] 注

[编辑] 模板参数

[编辑] 成员类型

[编辑] 成员函数

迭代器

容量

修改器

查找

桶接口

哈希策略

观察器

[编辑] 非成员函数

推导指引

[编辑] 注

[编辑] 示例

[编辑] 缺陷报告

[编辑] 参阅

导航

工具箱