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 是一种关联容器，包含具有唯一键的键值对。元素的查找、插入和删除操作具有平均常数时间复杂度。

在内部，元素并非按特定顺序排列，而是被组织到多个桶中。元素被分配到哪个桶完全取决于其键的哈希值。具有相同哈希码的键会出现在同一个桶中。这使得可以快速访问单个元素，因为一旦计算出哈希值，它就直接指向包含该元素的桶。

两个键如果满足映射的键相等谓词条件，则被视为 等价 。若两个键等价，则哈希函数必须为这两个键返回相同的值。

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

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

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

(since C++26)

目录

迭代器失效

操作 失效情况
所有只读操作、 swap 、 std::swap 永不失效
clear 、 rehash 、 reserve 、 operator= 始终失效
insert 、 emplace 、 emplace_hint 、 operator[] 仅当引发重哈希时失效
erase 仅对被删除元素失效

注释

  • 交换函数不会使容器内的任何迭代器失效，但会使标记交换区域末尾的迭代器失效。
  • 容器中存储的键或数据的引用和指针仅在该元素被删除时才会失效，即使对应的迭代器已失效也是如此。

模板参数

本节内容不完整
原因：需补充模板参数的描述说明。

成员类型

类型 定义
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
(公开成员函数)
赋值给容器
(公开成员函数)
返回关联的分配器
(公开成员函数)
迭代器
返回指向起始的迭代器
(公开成员函数)
返回指向末尾的迭代器
(公开成员函数)
容量
检查容器是否为空
(公开成员函数)
返回元素数量
(公开成员函数)
返回可容纳的最大元素数
(公开成员函数)
修改器
清除内容
(公开成员函数)
插入元素 或节点 (C++17 起)
(公开成员函数)
(C++23)
插入元素范围
(公开成员函数)
(C++17)
插入元素，或在键已存在时赋值给当前元素
(公开成员函数)
原位构造元素
(公开成员函数)
使用提示原位构造元素
(公开成员函数)
(C++17)
若键不存在则原位插入，否则无操作
(公开成员函数)
擦除元素
(公开成员函数)
交换内容
(公开成员函数)
(C++17)
从容器提取节点
(公开成员函数)
(C++17)
从另一容器接合节点
(公开成员函数)
查找
访问指定元素，带越界检查
(公开成员函数)
访问或插入指定元素
(公开成员函数)

非成员函数

(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++标准。

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

参见

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