Namespaces
Variants

std:: unordered_map

From cppreference.net
C++
Containers library
std::unordered_map
Member types
Member functions
Non-member functions
Deduction guides (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 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 /*unspecified*/
{
Iter     position ;
bool inserted ;
NodeType node ;
} ;
使用模板参数 iterator 和 node_type 实例化的特化。

成员函数

构造 unordered_map
(公开成员函数)
析构 unordered_map
(公开成员函数)
为容器赋值
(公开成员函数)
返回关联的分配器
（公开成员函数）
迭代器
返回指向起始位置的迭代器
（公开成员函数）
返回指向末尾的迭代器
（公开成员函数）
容量
检查容器是否为空
(公开成员函数)
返回元素数量
(公开成员函数)
返回可能的最大元素数量
（公开成员函数）
修饰符
清空内容
（公开成员函数）
插入元素 或节点 (C++17 起)
(公开成员函数)
(C++23)
插入一个元素范围
(公开成员函数)
(C++17)
插入元素，若键已存在则赋值给当前元素
(公开成员函数)
原地构造元素
(公开成员函数)
使用提示原位构造元素
(公开成员函数)
(C++17)
若键不存在则就地插入，若键存在则不执行任何操作
(公开成员函数)
删除元素
（公开成员函数）
交换内容
（公开成员函数）
(C++17)
从容器中提取节点
(公开成员函数)
(C++17)
从另一容器接合节点
(公开成员函数)
查找
访问指定元素（带边界检查）
（公开成员函数）
访问或插入指定元素
(公开成员函数)
返回匹配特定键的元素数量
（公开成员函数）
根据特定键查找元素
（公开成员函数）
(C++20)
检查容器是否包含具有特定键的元素
(公开成员函数)
返回匹配特定键的元素范围
（公开成员函数）
桶接口
返回指向指定桶起始位置的迭代器
(公开成员函数)
返回指向指定存储桶末尾的迭代器
（公开成员函数）
返回桶的数量
（公开成员函数）
返回最大桶数量
（公开成员函数）
返回特定桶中的元素数量
(公开成员函数)
返回特定键对应的桶
（公开成员函数）
哈希策略
返回每个桶的平均元素数量
（公开成员函数）
管理每个桶的最大平均元素数量
（公开成员函数）
预留至少指定数量的桶并重新生成哈希表
(公开成员函数)
预留至少指定数量元素的存储空间并重新生成哈希表
(公开成员函数)
观察器
返回用于哈希键的函数
（公开成员函数）
返回用于比较键是否相等的函数
（公开成员函数）

非成员函数

(C++11) (C++11) (removed in C++20)
比较 unordered_map 中的值
(函数模板)
(C++11)
特化 std::swap 算法
(函数模板)
(C++20)
擦除满足特定条件的所有元素
(函数模板)

推导指引

(C++17 起)

注释

功能测试 宏 值 标准 功能
__cpp_lib_containers_ranges 202202L (C++23) 容器的范围构造与插入
__cpp_lib_constexpr_unordered_map 202502L (C++26) constexpr std::unordered_map

示例

运行此代码 
#include <iostream>
#include <string>
#include <unordered_map>
int main()
{
    // 创建一个包含三个字符串（映射到字符串）的 unordered_map
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
    // 用于打印键值对的辅助 lambda 函数
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Key:[" << key << "] Value:[" << value << "]\n";
    };
    std::cout << "遍历并打印 unordered_map 的键值对，\n"
                 "显式指定其类型：\n";
    for (const std::pair<const std::string, std::string>& n : u)
        print_key_value(n.first, n.second);
    std::cout << "\n使用 C++17 结构化绑定遍历并打印键值对：\n";
    for (const auto& [key, value] : u)
        print_key_value(key, value);
    // 向 unordered_map 添加两个新条目
    u["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
    std::cout << "\n通过键输出值：\n"
                 "颜色 RED 的 HEX 值为：[" << u["RED"] << "]\n"
                 "颜色 BLACK 的 HEX 值为：[" << u["BLACK"] << "]\n\n";
    std::cout << "对不存在的键使用 operator[] 插入新的键值对：\n";
    print_key_value("new_key", u["new_key"]);
    std::cout << "\n使用 `auto` 遍历并打印键值对；\n"
                 "new_key 现在已成为映射中的键之一：\n";
    for (const auto& n : u)
        print_key_value(n.first, n.second);
}

可能的输出： 

遍历并打印 unordered_map 的键值对，
显式指定其类型：
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
使用 C++17 结构化绑定遍历并打印键值对：
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
通过键输出值：
颜色 RED 的 HEX 值为：[#FF0000]
颜色 BLACK 的 HEX 值为：[#000000]
对不存在的键使用 operator[] 插入新的键值对：
Key:[new_key] Value:[]
使用 `auto` 遍历并打印键值对；
new_key 现在已成为映射中的键之一：
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

另请参阅

(C++11)
键值对集合，通过键进行哈希存储
(类模板)
键值对集合，按键排序，键具有唯一性
(类模板)
(C++23)
适配两个容器以提供键值对集合，按键排序且键具有唯一性
(类模板)