注意

请注意，本文尚未完成！您可以通过编辑此文档页面来提供帮助。

概述

简化版 (C++98 起)

template< class Key, class Value, /* ... */ >
class multimap;

详细

常规版 (C++98 起)

template<
    class Key,
    class Value,
    class Compare = std::less<Key>,
    class Allocator = std::allocator<std::pair<const Key, Value>>
>
class multimap;

多态版 (C++17 起)

namespace pmr {
    template< class Key, class Value, class Compare = std::less<Key> >
    using multimap = std::multimap<Key, Value, Compare,
                                  std::pmr::polymorphic_allocator<std::pair<const Key, Value>>>;
}

std::multimap 是一种按指定顺序存储键值对的容器。它与 std::map 几乎相同，唯一的区别是键可以重复。如果两个元素的键相同，则它们按其值排序。

技术细节

multimap 的技术定义

Multimap 是一个关联容器，它包含一个排序的键值对列表，同时允许具有相同键的多个条目。

排序根据应用于键的比较函数 Compare 完成。搜索、插入和删除操作具有对数复杂度。

键值对的顺序（如果键比较相等）是插入顺序，并且不会改变。(C++11 起)

标准库在任何地方使用 Compare 要求时，等价性均通过使用 Compare 中所述的等价关系确定。

不精确地说，如果两个对象 a 和 b 都没有比另一个小，则它们被认为是等价的：!comp(a, b) && !comp(b, a)。

std::multimap

定义于

map

模板参数

pub	Key	存储的键的类型。
pub	Value	存储的值的类型。
pub	Compare	一个满足 Compare 的比较器类型。
pub	Allocator	负责分配和释放内存的分配器类型。必须满足 Allocator。

类型名称

pub	key_type	Key
pub	mapped_type	Value
pub	value_type	std::pair<const Key, Value>
pub	size_type	无符号整型（通常为 std::size_t ).
pub	difference_type	有符号整型（通常为 std::ptrdiff_t ).
pub	key_compare	Compare
pub	allocator_type	Allocator
pub	reference	value_type&
pub	const_reference	const value_type&
pub	pointer	Allocator::pointer(C++11 以前) std::allocator_traits<Allocator>::pointer(C++11 起)
pub	const_pointer	Allocator::const_pointer(C++11 以前) std::allocator_traits<Allocator>::const_pointer(C++11 起)
pub	iterator	LegacyBidirectionalIterator 到 value_type
pub	const_iterator	LegacyBidirectionalIterator 到 const value_type
pub	reverse_iterator	std::reverse_iterator<iterator>
pub	const_reverse_iterator	std::reverse_iterator<const_iterator>
pub	node_type (C++17 起)	节点句柄的一个特化，表示一个容器节点。

成员类

pub

value_compare

比较两个 value_type 类型对象的函数对象。

成员函数

pub	（构造函数）	构造一个新的 multimap。
pub	（析构函数）	销毁一个 multimap。
pub	operator=	将一个 multimap 赋值给另一个。
pub	get_allocator	返回关联的分配器。

迭代器

pub	begin cbegin (C++11 起)	返回指向开头的迭代器。
pub	end cend (C++11 起)	返回指向末尾的迭代器。
pub	rbegin crbegin (C++11 起)	返回指向开头的反向迭代器。
pub	rend crend (C++11 起)	返回指向末尾的反向迭代器。

容量

pub	empty	如果 multimap 为空则返回 true，否则返回 false。
pub	size	返回 multimap 中元素的数量。
pub	max_size	返回最大可能的元素数量。

修饰符

pub	clear	清除 multimap 的内容。
pub	insert	插入元素或节点（使用 .extract() 提取的）(C++17 起)。
pub	emplace (C++11 起)	就地构造新元素。
pub	emplace_hint (C++11 起)	使用提示（迭代器）就地构造元素。
pub	erase	擦除元素。
pub	swap	交换两个 multimap。
pub	extract (C++17 起)	从 multimap 中提取节点（稍后可以插入到其他地方）。
pub	merge (C++17 起)	合并两个 multimap。

查找

pub	count	返回与特定键匹配的元素数量。
pub	find	搜索元素并返回指向它的迭代器，如果未找到则返回 end 迭代器。
pub	contains (C++20 起)	如果 multimap 中包含元素则返回 true，否则返回 false。
pub	equal_range	返回与特定键匹配的元素范围。
pub	lower_bound	返回指向第一个不小于给定键的元素的迭代器。
pub	upper_bound	返回指向第一个大于给定键的元素的迭代器。

观察器

pub	key_comp	返回一个比较键的内部函数对象。
pub	value_comp	返回一个内部函数对象，它比较 value_type 类型（std::pair<const Key, Value>）对象中的键。

非成员函数

pub	operator== operator!= (C++20 中移除) operator< (C++20 中移除) operator> (C++20 中移除) operator<= (C++20 中移除) operator>= (C++20 中移除) operator<=> (C++20 起)	按字典顺序比较 multimap 中的值。
pub	std::swap (std::multimap)	std::swap 算法的重载。
pub	std::erase_if (std::multimap) (C++20 起)	std::erase_if 算法的重载。

推导指南 (C++17 起)

点击展开

推导指南

// (1)
template< class InputIt, class Alloc >
multimap( InputIt, InputIt, Alloc )
  -> multimap<iter_key_t<InputIt>, iter_val_t<InputIt>,
              std::less<iter_key_t<InputIt>>, Alloc>;

// (2)
template< class InputIt,
          class Comp = std::less<iter_key_t<InputIt>>,
          class Alloc = std::allocator<iter_to_alloc_t<InputIt>> >
multimap( InputIt, InputIt, Comp = Comp(), Alloc = Alloc() )
  -> multimap<iter_key_t<InputIt>, iter_val_t<InputIt>, Comp, Alloc>;

(1) 和 (2) 允许从迭代器范围进行推导

// (3)
template< class Key, class T, class Allocator >
multimap( std::initializer_list<std::pair<Key, T>>, Allocator )
  -> multimap<Key, T, std::less<Key>, Allocator>;

// (4)
template< class Key,
          class T,
          class Comp = std::less<Key>,
          class Alloc = std::allocator<std::pair<const Key, T>> >
multimap( std::initializer_list<std::pair<Key, T>>, Comp = Comp(), Alloc = Alloc() )
  -> multimap<Key, T, Comp, Alloc>;

(3) 和 (4) 允许从 std::initializer_list 进行推导

别名 iter_key_t、iter_val_t 和 iter_to_alloc_t 定义如下

template< class InputIt >
using iter_key_t = std::remove_const_t<
                     typename std::iterator_traits<InputIt>::value_type::first_type>;

template< class InputIt >
using iter_val_t = typename std::iterator_traits<InputIt>::value_type::second_type;

template< class InputIt >
using iter_to_alloc_t = std::pair<
  std::add_const_t<typename std::iterator_traits<InputIt>::value_type::first_type>,
  typename std::iterator_traits<InputIt>::value_type::second_type
>

注意

请注意，这些别名不保证在标准库的任何地方都能找到。它们仅为这些推导指南的展示目的而定义，并且在本文档撰写时尚未出现在标准库中。

重载决议

为了使任何推导指南参与重载决议，必须满足以下要求

• InputIt 满足 LegacyInputIterator
• Alloc 满足 Allocator
• Comp 不满足 Allocator

注意

库确定类型不满足 LegacyInputIterator 的程度是未指定的，但至少

• 整型不符合输入迭代器的条件。

同样，它确定类型不满足 Allocator 的程度是未指定的，但至少

• 成员类型 Alloc::value_type 必须存在。
• 当作为未求值操作数处理时，表达式 std::declval<Alloc&>().allocate(std::size_t{}) 必须是格式良好的。

更多示例

基本操作

创建 map，插入对，打印出来

#include <iostream>
#include <utility>
#include <string>
#include <map>

int main(){
  std::multimap<std::string, int> potions { {"health", 30}, {"mana", 25}, {"mana", 50} };

  potions.emplace("health", 200);
  potions.insert(std::make_pair("speed", 10));

  for (const auto& [key, value] : potions)
    std::cout << key << " " << value << std::endl;

  return 0;
}

结果

health 30
health 200
mana 25
mana 50
speed 10