std::unordered_map

 

C++

编译器支持

自立实现与有宿主实现

语言

标准库

标准库标头

具名要求

功能特性测试宏(C++20)

语言支持库

概念库(C++20)

诊断库

内存管理库

元编程库(C++11)

通用工具库

容器库

迭代器库

范围库(C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库(C++17)

并发支持库(C++11)

执行控制库(C++26)

技术规范

符号索引

外部库

 

容器库

node-handle (C++17)

序列容器

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)

表格

迭代器失效

成员函数表格

非成员函数表格

 

std::unordered_map

成员类型
成员函数
unordered_map::unordered_map unordered_map::~unordered_map unordered_map::operator= unordered_map::get_allocator 迭代器 unordered_map::beginunordered_map::cbegin unordered_map::endunordered_map::cend 容量 unordered_map::size unordered_map::max_size unordered_map::empty 修改器 unordered_map::clear unordered_map::erase unordered_map::swap unordered_map::extract (C++17) unordered_map::merge (C++17) unordered_map::insert unordered_map::insert_range (C++23) unordered_map::insert_or_assign (C++17)   unordered_map::emplace unordered_map::emplace_hint unordered_map::try_emplace (C++17)	查找 unordered_map::at unordered_map::operator[] unordered_map::count unordered_map::find unordered_map::contains (C++20) unordered_map::equal_range 桶接口 unordered_map::begin(size_type)unordered_map::cbegin(size_type) unordered_map::end(size_type)unordered_map::cend(size_type) unordered_map::bucket_count unordered_map::max_bucket_count unordered_map::bucket_size unordered_map::bucket 散列策略 unordered_map::load_factor unordered_map::max_load_factor unordered_map::rehash unordered_map::reserve 观察器 unordered_map::hash_function unordered_map::key_eq
非成员函数
operator==operator!= (C++20 前)	std::swap(std::unordered_map) erase_if(std::unordered_map) (C++20)
推导指引(C++17)

 

在标头 <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 起)

迭代器失效

操作	失效
所有只读操作、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) 和常量表达式迭代器(ConstexprIterator) (C++26 起)
const_iterator	指向 const value_type 的老式向前迭代器(LegacyForwardIterator) 和常量表达式迭代器(ConstexprIterator) (C++26 起)
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)	constexprstd::unordered_map

示例

运行此代码

#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 =[](constauto& key, constauto& value){std::cout<<"键：["<< key <<"] 值：["<< value <<"]\n";};   std::cout<<"遍历并打印 unordered_map 的键值对，显式指定类型：\n";for(conststd::pair<conststd::string, std::string>& n : u) print_key_value(n.first, n.second);   std::cout<<"\n通过 C++17 的结构化绑定来遍历并打印 unordered_map 的键值对：\n";for(constauto&[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(constauto& 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

参阅

unordered_multimap (C++11 起)	键值对的集合，按照键生成散列 (类模板)
map	键值对的集合，按照键排序，键是唯一的 (类模板)
flat_map (C++23)	适配两个容器以提供按唯一键排序的键值对集合 (类模板)