std::unordered_set

在标头 `<unordered_set>` 定义
template< class Key, class Hash = std::hash<Key>, class KeyEqual = std::equal_to<Key>, class Allocator = std::allocator<Key> > class unordered_set;	(1)	(C++11 起)
namespace pmr { template< class Key, class Hash = std::hash<Key>, class Pred = std::equal_to<Key> > using unordered_set = std::unordered_set<Key, Hash, Pred, std::pmr::polymorphic_allocator<Key>>; }	(2)	(C++17 起)

unordered_set 是一种关联容器，含有 Key 类型的唯一对象集合。搜索、插入和移除拥有平均常数时间复杂度。

在内部，元素并不以任何特别顺序排序，而是组织进桶中。元素被放进哪个桶完全依赖其值的散列。这允许对单独元素的快速访问，因为一旦计算了散列值，它就指代元素被放入的确切的桶。

不可修改容器元素（即使通过非 const 迭代器），因为修改可能更改元素的散列，并破坏容器。

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

std::unordered_set 的全部成员函数均为 constexpr：在常量表达式求值中创建并使用 std::unordered_set 对象是可能的。

然而，std::unordered_set 对象通常不能为 constexpr，因为任何动态分配的存储都必须在相同的常量表达式求值中释放。

(C++26 起)

迭代器失效

操作	失效
所有只读操作、swap、std::swap	决不
clear、rehash、reserve、operator=	始终
insert、emplace、emplace_hint	仅限重散列的情况
erase	仅限指向被擦除元素的迭代器

注解

swap 函数不会使容器内的任何迭代器失效，但它们会使标记交换区域结尾的迭代器失效。

指向在容器中存储的键或元素的引用和指针只会因为擦除该元素而失效，即使对应迭代器失效也是如此。

在移动赋值容器后，除非由不兼容的分配器强制进行了逐元素移动赋值，否则到被移动的容器中的引用，指针和迭代器（除了尾后迭代器）都保持有效，但它们现在会指代 *this 中的元素。

模板形参

成员类型

类型	定义
`key_type`	`Key`
`value_type`	`Key`
`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_set` (公开成员函数)
(析构函数)	析构 `unordered_set` (公开成员函数)
operator=	将值赋给容器 (公开成员函数)
get_allocator	返回关联的分配器 (公开成员函数)
迭代器
begincbegin	返回指向起始的迭代器 (公开成员函数)
endcend	返回指向末尾的迭代器 (公开成员函数)
容量
empty	检查容器是否为空 (公开成员函数)
size	返回元素数 (公开成员函数)
max_size	返回可容纳的最大元素数 (公开成员函数)
修改器
clear	清除内容 (公开成员函数)
insert	插入元素或节点(C++17 起) (公开成员函数)
insert_range (C++23)	插入元素范围 (公开成员函数)
emplace	原位构造元素 (公开成员函数)
emplace_hint	使用提示原位构造元素 (公开成员函数)
erase	擦除元素 (公开成员函数)
swap	交换内容 (公开成员函数)
extract (C++17)	提取容器中的节点 (公开成员函数)
merge (C++17)	从另一容器合并节点 (公开成员函数)
查找
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_set 中的值 (函数模板)
std::swap(std::unordered_set) (C++11)	特化 std::swap 算法 (函数模板)
erase_if(std::unordered_set) (C++20)	擦除所有满足特定判别标准的元素 (函数模板)

推导指引

(C++17 起)

注解

成员类型 iterator 与 const_iterator 可能是同一类型的别名。这表明以这两个类型为形参类型的一对函数重载可能违背单一定义规则。因为 iterator 可转换到 const_iterator，所以可以改成只提供一个以 const_iterator 为形参类型的函数。

功能特性测试宏	值	标准	功能特性
`__cpp_lib_containers_ranges`	`202202L`	(C++23)	容器的范围构造和插入
`__cpp_lib_constexpr_containers`	`202502L`	(C++26)	constexpr `std::unordered_set`

示例

运行此代码

#include <iostream>
#include <unordered_set>
 
void print(const auto& set)
{
    for (const auto& elem : set)
        std::cout << elem << ' ';
    std::cout << '\n';
}
 
int main()
{
    std::unordered_set<int> mySet{2, 7, 1, 8, 2, 8}; // 创建 int 的集合
    print(mySet);
 
    mySet.insert(5); // 将元素 5 加入集合
    print(mySet);
 
    if (auto iter = mySet.find(5); iter != mySet.end())
        mySet.erase(iter); // 移除 iter 指向的元素
    print(mySet);
 
    mySet.erase(7); // 移除元素 7
    print(mySet);
}

可能的输出：

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告	应用于	出版时的行为	正确行为
LWG 2050	C++11	`reference`、`const_reference`、`pointer` 和 `const_pointer` 的定义都基于 `allocator_type`	基于 `value_type` 和 std::allocator_traits

参阅

unordered_multiset (C++11 起)	键的集合，按照键生成散列 (类模板)
set	唯一键的集合，按照键排序 (类模板)
flat_set (C++23)	调整容器以提供按键排序的唯一键集合 (类模板)

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
诊断库
内存管理库
元编程库 (C++11)
通用工具库
容器库
迭代器库
范围库 (C++20)
算法库
字符串库
文本处理库
数值库
日期和时间库
输入/输出库
文件系统库 (C++17)
并发支持库 (C++11)
执行控制库 (C++26)
技术规范
符号索引
外部库

序列
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)
表格
迭代器失效
成员函数表格
非成员函数表格