注意

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

概述

简化版 (C++98 起)

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

详细

常规版 (C++98 起)

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

多态版 (C++17 起)

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

std::map 是一个按指定顺序存储具有唯一键的键值对的容器。

技术细节

map 的技术定义

std::map 是一个有序的关联容器，包含具有唯一键的键值对。键通过比较函数 Compare 进行排序。搜索、删除和插入操作具有对数复杂度。Map 通常实现为红黑树。

在标准库中使用 Compare 要求的所有地方，唯一性都通过等价关系来确定。不精确地说，如果两个对象 a 和 b 都不比对方小：!comp(a, b) && !comp(b, a)，则认为它们是等价的（不唯一）。

std::map

定义于

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	insert_return_type (C++17起)	描述插入 node_type 结果的类型，它是 template < class Iter, class NodeType > struct /* unspecified */ { Iter position; bool inserted; NodeType node; }; 使用模板参数 iterator 和 node_type 实例化的特化。

成员类

pub

value_compare

比较两个 value_type 类型的对象。

成员函数

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

元素访问

pub	at	访问指定元素并进行边界检查。
pub	operator[]	访问或插入指定元素。

迭代器

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

容量

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

修饰符

pub	clear	清空 map 的内容。
pub	insert	插入元素或节点（使用 .extract() 提取的）(C++17 起)。
pub	insert_or_assign (自 C++17 起)	插入新元素，如果已存在则赋值给现有元素。
pub	emplace (C++11 起)	就地构造新元素。
pub	emplace_hint (C++11 起)	使用提示（迭代器）就地构造元素。
pub	try_emplace	如果键不存在，则就地插入新元素；如果键存在，则不执行任何操作。
pub	erase	擦除元素。
pub	swap	交换两个 map。
pub	extract (C++17 起)	从 map 中提取节点（可以稍后插入到其他地方）。
pub	merge (C++17 起)	将两个 map 合并在一起。

查找

pub	count	返回匹配特定键的元素数量（对于 map 总是 0/1）。
pub	find	搜索元素并返回指向它的迭代器，如果未找到则返回 end 迭代器。
pub	contains (C++20 起)	如果元素在 map 中，则返回 true，否则返回 false。
pub	equal_range	返回匹配特定键的元素范围。（对于 map，该范围将始终包含一个元素）。
pub	lower_bound	返回指向第一个不小于给定键的元素的迭代器。
pub	upper_bound	返回指向第一个大于给定键的元素的迭代器。

观察器

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

非成员函数

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

推导指南 (C++17 起)

点击展开

推导指南

// (1)
template< class InputIt, class Alloc >
map( InputIt, InputIt, Alloc )
  -> map<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>> >
map( InputIt, InputIt, Comp = Comp(), Alloc = Alloc() )
  -> map<iter_key_t<InputIt>, iter_val_t<InputIt>, Comp, Alloc>;

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

// (3)
template< class Key, class T, class Allocator >
map( std::initializer_list<std::pair<Key, T>>, Allocator )
  -> map<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>> >
map( std::initializer_list<std::pair<Key, T>>, Comp = Comp(), Alloc = Alloc() )
  -> map<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 <string>
#include <map>

int main(){
  std::map<std::string, int> player_stats { {"C1", -10}, {"B2", 25} };

  player_stats.insert(std::make_pair("A3", 200));
  player_stats.emplace("D4", 500);
  player_stats["A3"] = 90;

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

  return 0;
}

结果

A3 90
B2 25
C1 -10
D4 500