std::unordered_multiset

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

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

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

不要求此容器的迭代顺序稳定（因此 std::equal 不能用于比较两个 std::unordered_multiset），但关键比较等价（以 key_eq() 为比较器比较相等）的每组元素均组成迭代顺序中的连续子范围，也可以用 equal_range() 访问它。

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

模板形参

成员类型

成员类型	定义
`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)
`const_iterator`	指向 const value_type 的老式向前迭代器 (LegacyForwardIterator)
`local_iterator`	迭代器类型，其类别、值、差、指针和引用类型都与 `iterator` 相同。能用此迭代器在桶内遍历，但不能跨桶。
`const_local_iterator`	迭代器类型，其类别、值、差、指针和引用类型都与 `const_iterator` 相同。此迭代器可用于在桶内遍历，但不能跨桶。
`node_type`(C++17 起)	表示容器节点的节点句柄特化

成员函数

(构造函数)	构造 `unordered_multiset` (公开成员函数)
(析构函数)	析构 `unordered_multiset` (公开成员函数)
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_multiset 中的值 (函数模板)
std::swap(std::unordered_multiset) (C++11)	特化 std::swap 算法 (函数模板)
erase_if(std::unordered_multiset) (C++20)	擦除所有满足特定判别标准的元素 (函数模板)

推导指引

(C++17 起)

注解

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

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

示例

运行此代码

#include <iostream>
#include <map>
#include <set>
#include <unordered_set>
 
int main()
{
    auto print = []<class T>(const T &container) {
        if constexpr (requires {
                          typename T::key_type;
                          typename T::mapped_type;
                      })
        {
            for (const auto &[key, value] : container)
            {
                std::cout << key << ": " << value << '\n';
            }
        }
        else
        {
            for (const auto &element : container)
            {
                std::cout << element << " ";
            }
            std::cout << '\n';
        }
        std::cout << '\n';
    };
    std::map<int, std::string> myMap = {{5, "5"}, {2, "2"}, {8, "8"}, {1, "1"}, {9, "9"}};
    std::cout << "std::map: \n";
    print(myMap);
 
    std::set<int> mySet = {5, 2, 8, 1, 9};
    std::cout << "std::set: \n";
    print(mySet);
 
    // std::unordered_set
    std::unordered_set<int> myHashSet = {5, 2, 8, 1, 9};
    myHashSet.insert(3);
    myHashSet.insert(3);
 
    std::cout << "std::unordered_set: \n";
    print(myHashSet);
 
    // std::unordered_multiset
    std::unordered_multiset<int> myMultiHashSet = {5, 2, 8, 1, 9};
    myMultiHashSet.insert(2);
    myMultiHashSet.insert(2);
 
    std::cout << "std::unordered_multiset : \n";
    print(myMultiHashSet);
 
    return 0;
}

输出：

std::map: 
1: 1
2: 2
5: 5
8: 8
9: 9
 
std::set:
1 2 5 8 9
 
std::unordered_set:
3 9 1 8 2 5
 
std::unordered_multiset :
5 2 2 2 8 1 9

缺陷报告

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

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

参阅

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

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

序列
array (C++11)
vector
vector<bool>
inplace_vector (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)
表格
迭代器失效
成员函数表格
非成员函数表格