std::unordered_map

来自cppreference.com
< cpp‎ | container
 
C++
 
容器库
 
std::unordered_map
成员函数
迭代器
容量
修改器
(C++17)
(C++17)
(C++17)
(C++17)
查找
(C++20)
桶接口
哈希策略
观察器
非成员函数
(C++20 前)
(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 是关联容器，含有带唯一键的键-值对。搜索、插入和元素移除拥有平均常数时间复杂度。

元素在内部不以任何特定顺序排序，而是组织进桶中。元素放进哪个桶完全依赖于对应键的哈希。这允许对单独元素的快速访问，因为计算哈希就可以准确指代元素所放进的桶。

std::unordered_map 满足容器 (Container) 、知分配器容器 (AllocatorAwareContainer) 和无序关联容器 (UnorderedAssociativeContainer) 的要求。

迭代器失效

操作 失效
所有只读操作、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)
const_iterator 指向 const value_type 的老式向前迭代器 (LegacyForwardIterator)
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 实例化。

成员函数

(C++11)
 构造 unordered_map
(公开成员函数)
(C++11)
 析构 unordered_map
(公开成员函数)
(C++11)
 赋值给容器
(公开成员函数)
(C++11)
 返回相关的分配器
(公开成员函数)
迭代器
(C++11)
 返回指向起始的迭代器
(公开成员函数)
(C++11)
 返回指向末尾的迭代器
(公开成员函数)
容量
(C++11)
 检查容器是否为空
(公开成员函数)
(C++11)
 返回容纳的元素数
(公开成员函数)
(C++11)
 返回可容纳的最大元素数
(公开成员函数)
修改器
(C++11)
 清除内容
(公开成员函数)
(C++11)
 插入元素或结点 (C++17 起)
(公开成员函数)
(C++23)
 插入元素的范围
(公开成员函数)
(C++17)
 插入元素，或若键已存在则赋值给当前元素
(公开成员函数)
(C++11)
 原位构造元素
(公开成员函数)
(C++11)
 使用提示原位构造元素
(公开成员函数)
(C++17)
 若键不存在则原位插入，若键存在则不做任何事
(公开成员函数)
(C++11)
 擦除元素
(公开成员函数)
(C++11)
 交换内容
(公开成员函数)
(C++17)
 从另一容器提取节点
(公开成员函数)
(C++17)
 从另一容器合并节点
(公开成员函数)
查找
(C++11)
 访问指定的元素，同时进行越界检查
(公开成员函数)
(C++11)
 访问或插入指定的元素
(公开成员函数)
(C++11)
 返回匹配特定键的元素数量
(公开成员函数)
(C++11)
 寻找带有特定键的元素
(公开成员函数)
(C++20)
 检查容器是否含有带特定键的元素
(公开成员函数)
(C++11)
 返回匹配特定键的元素范围
(公开成员函数)
桶接口
(C++11)
 返回一个迭代器，指向指定的桶的开始
(公开成员函数)
(C++11)
 返回一个迭代器，指向指定的桶的末尾
(公开成员函数)
(C++11)
 返回桶数
(公开成员函数)
(C++11)
 返回桶的最大数量
(公开成员函数)
(C++11)
 返回在特定的桶中的元素数量
(公开成员函数)
(C++11)
 返回带有特定键的桶
(公开成员函数)
哈希策略
(C++11)
 返回每个桶的平均元素数量
(公开成员函数)
(C++11)
 管理每个桶的平均元素数量的最大值
(公开成员函数)
(C++11)
 为至少为指定数量的桶预留存储空间并重新生成散列表
(公开成员函数)
(C++11)
 为至少为指定数量的元素预留存储空间并重新生成哈希表。
(公开成员函数)
观察器
(C++11)
 返回用于对键散列的函数
(公开成员函数)
(C++11)
 返回用于比较键的相等性的函数
(公开成员函数)

非成员函数

(C++20 中移除)
 比较 unordered_map 中的值
(函数模板)
(C++11)
 特化 std::swap 算法
(函数模板)
(C++20)
 擦除所有满足特定判别标准的元素
(函数模板)

推导指引

 (C++17 起)

注解

功能特性测试宏 值 标准 注释
__cpp_lib_containers_ranges 202202L (C++23) 容器的范围构造和插入

示例

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

参阅

 键值对的集合，按照键排序，键是唯一的
(类模板)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/container/unordered_map&oldid=78803”