命名空间
变体
操作

std::unordered_map

来自 cppreference.com
< cpp‎ | 容器
 
 
 
 
定义在头文件 <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 满足 ContainerAllocatorAwareContainerUnorderedAssociativeContainer 的要求。

内容

[编辑] 迭代器失效

操作 失效
所有只读操作,交换std::swap 从不
清除重新哈希保留运算符= 总是
插入放置放置提示运算符[] 只有在导致重新哈希时
擦除 仅擦除元素

[编辑] 注意

  • 交换函数不会使容器内的任何迭代器失效,但它们会使标记交换区域末尾的迭代器失效。
  • 即使对应的迭代器失效,对存储在容器中的键或数据的引用和指针也只会被擦除该元素所使失效。

[编辑] 模板参数

[编辑] 成员类型

成员类型 定义
key_type Key[编辑]
mapped_type T[编辑]
value_type std::pair<const Key, T>[编辑]
size_type 无符号整数类型(通常为 std::size_t)[编辑]
difference_type 带符号整数类型(通常为 std::ptrdiff_t[edit]
哈希函数 Hash[edit]
键比较函数 KeyEqual[edit]
分配器类型 Allocator[edit]
引用 value_type&[edit]
常量引用 const value_type&[edit]
指针 std::allocator_traits<Allocator>::pointer[edit]
常量指针 std::allocator_traits<Allocator>::const_pointer[edit]
迭代器 LegacyForwardIteratorvalue_type[edit]
常量迭代器 LegacyForwardIteratorconst value_type[edit]
本地迭代器 一种迭代器类型,其类别、值、差值、指针和
引用类型与 iterator 相同。此迭代器
可用于遍历单个桶,但不能跨桶遍历[edit]
常量本地迭代器 一种迭代器类型,其类别、值、差值、指针和
引用类型与 const_iterator 相同。此迭代器
可用于遍历单个桶,但不能跨桶遍历[edit]
node_type (自 C++17 起) 一个 节点句柄 的特化,表示一个容器节点[edit]
insert_return_type (自 C++17 起) 描述插入 node_type 结果的类型,一个

template<class Iter, class NodeType>
struct /*未指定*/
{
    Iter     position;
    bool     inserted;
    NodeType node;
};

用模板参数 iteratornode_type 实例化。[edit]

[edit] 成员函数

构造 unordered_map
(公有成员函数) [edit]
析构 unordered_map
(公有成员函数) [edit]
将值分配给容器
(公有成员函数) [edit]
返回关联的分配器
(公有成员函数) [edit]
迭代器
返回指向开头的迭代器
(公有成员函数) [edit]
返回指向结尾的迭代器
(公有成员函数) [edit]
容量
检查容器是否为空
(公有成员函数) [edit]
返回元素数量
(公有成员函数) [edit]
返回最大可能的元素数量
(公有成员函数) [edit]
修饰符
清除内容
(公有成员函数) [edit]
插入元素 或节点(自 C++17 起)
(公有成员函数) [edit]
插入一系列元素
(公有成员函数) [edit]
插入元素,如果键已存在,则分配给当前元素
(公有成员函数) [edit]
在容器中就地构造元素
(公有成员函数) [edit]
使用提示在容器中就地构造元素
(公有成员函数) [edit]
如果键不存在,则在容器中就地构造元素,如果键存在,则不执行任何操作
(公有成员函数) [edit]
擦除元素
(公有成员函数) [edit]
交换容器的内容
(公有成员函数) [edit]
(C++17)
从容器中提取节点
(公有成员函数) [edit]
(C++17)
从另一个容器中拼接节点
(公有成员函数) [edit]
查找
访问指定元素,并进行边界检查
(公有成员函数) [edit]
访问或插入指定元素
(公有成员函数) [edit]
返回与特定键匹配的元素数量
(公有成员函数) [edit]
查找具有特定键的元素
(公有成员函数) [edit]
(C++20)
检查容器是否包含具有特定键的元素
(公有成员函数) [edit]
返回与特定键匹配的元素范围
(公有成员函数) [edit]
桶接口
返回指向指定桶开头的迭代器
(公有成员函数) [edit]
返回指向指定桶结尾的迭代器
(公有成员函数) [edit]
返回桶的数量
(公共成员函数) [编辑]
返回最大桶数
(公共成员函数) [编辑]
返回特定桶中的元素数量
(公共成员函数) [编辑]
返回特定键的桶
(公共成员函数) [编辑]
哈希策略
返回每个桶的平均元素数
(公共成员函数) [编辑]
管理每个桶的最大平均元素数
(公共成员函数) [编辑]
保留至少指定的桶数,并重新生成哈希表
(公共成员函数) [编辑]
为至少指定的元素数量保留空间,并重新生成哈希表
(公共成员函数) [编辑]
观察者
返回用于对键进行哈希处理的函数
(公共成员函数) [编辑]
返回用于比较键是否相等的函数
(公共成员函数) [编辑]

[编辑] 非成员函数

(C++11)(C++11)(C++20 中已移除)
比较无序映射中的值
(函数模板) [编辑]
专门化 std::swap 算法
(函数模板) [编辑]
擦除满足特定条件的所有元素
(函数模板) [编辑]

推断指南

(自 C++17 起)

[编辑] 备注

特性测试 Std 特性
__cpp_lib_containers_ranges 202202L (C++23) 容器的范围构造和插入

[编辑] 示例

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

DR 应用于 已发布的行为 正确的行为
LWG 2050 C++11 referenceconst_referencepointer
const_pointer 的定义基于 allocator_type
基于 value_type
std::allocator_traits

[编辑] 另请参见

键值对集合,按键进行哈希处理
(类模板) [编辑]
键值对集合,按键排序,键是唯一的
(类模板) [编辑]
适配两个容器以提供键值对集合,按唯一键排序
(类模板) [编辑]