std::map

定义于头文件 `<map>`
template< class Key, class T, class Compare = std::less<Key>, class Allocator = std::allocator<std::pair<const Key, T>> > class map;	(1)
namespace pmr { template< class Key, class T, class Compare = std::less<Key> > using map = std::map<Key, T, Compare, std::pmr::polymorphic_allocator<std::pair<const Key, T>>>; }	(2)	(since C++17)

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

std::map 的迭代器以键的升序迭代，其中升序是由构造时使用的比较定义的。也就是说，给定

m，一个 std::map
it_l 和 it_r，可解引用的迭代器指向 m，其中 it_l < it_r。

m.value_comp()(*it_l, *it_r) == true (如果使用默认比较，则为从最小到最大)。

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

std::map 满足 Container、AllocatorAwareContainer、AssociativeContainer 和 ReversibleContainer 的要求。

std::map 的所有成员函数都是 constexpr：可以在常量表达式的求值中创建和使用 std::map 对象。

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

(since C++26)

[编辑] 模板形参

[编辑] 成员类型

类型定义

key_type Key[编辑]

mapped_type T[编辑]

value_type std::pair<const Key, T>[编辑]

size_type 无符号整数类型（通常为 std::size_t）[编辑]

difference_type 有符号整数类型（通常为 std::ptrdiff_t）[编辑]

key_compare Compare[编辑]

allocator_type Allocator[编辑]

reference value_type&[编辑]

const_reference const value_type&[编辑]

pointer

`Allocator::pointer`	(until C++11)
std::allocator_traits<Allocator>::pointer	(since C++11)

[编辑]

const_pointer

`Allocator::const_pointer`	(until C++11)
std::allocator_traits<Allocator>::const_pointer	(since C++11)

[编辑]

iterator LegacyBidirectionalIterator 和 ConstexprIterator(since C++26) to value_type[编辑]

const_iterator LegacyBidirectionalIterator 和 ConstexprIterator(since C++26) to const value_type[编辑]

reverse_iterator std::reverse_iterator<iterator>[编辑]

const_reverse_iterator std::reverse_iterator<const_iterator>[编辑]

node_type (since C++17) 一种节点句柄的特化，表示容器节点[编辑]

insert_return_type (since C++17)

描述插入 node_type 结果的类型，是以下内容的特化

template<class Iter, class NodeType>
struct /*unspecified*/
{
Iter position;
bool inserted;
NodeType node;
};
用模板实参 iterator 和 node_type 实例化。[编辑]

[编辑] 成员类

value_compare

比较 value_type 类型的对象
(类) [编辑]

[编辑] 成员函数

(构造器)	构造 `map` (公有成员函数) [编辑]
(析构器)	析构 `map` (公有成员函数) [编辑]
operator=	为容器赋值 (公有成员函数) [编辑]
get_allocator	返回关联的分配器 (公有成员函数) [编辑]
元素访问
at	访问指定的元素，带边界检查 (公有成员函数) [编辑]
operator[]	访问或插入指定的元素 (公有成员函数) [编辑]
迭代器
begincbegin (C++11)	返回指向开头的迭代器 (公有成员函数) [编辑]
endcend (C++11)	返回指向末尾的迭代器 (公有成员函数) [编辑]
rbegincrbegin (C++11)	返回指向开头的逆向迭代器 (公有成员函数) [编辑]
rendcrend (C++11)	返回指向末尾的逆向迭代器 (公有成员函数) [编辑]
容量
empty	检查容器是否为空 (公有成员函数) [编辑]
size	返回元素数量 (公有成员函数) [编辑]
max_size	返回元素的最大可能数量 (公有成员函数) [编辑]
修改器
clear	清除内容 (公有成员函数) [编辑]
insert	插入元素或节点(since C++17) (公有成员函数) [编辑]
insert_range (C++23)	插入一个元素范围 (公有成员函数) [编辑]
insert_or_assign (C++17)	插入一个元素，或者如果键已存在则赋值给当前元素 (公有成员函数) [编辑]
emplace (C++11)	就地构造元素 (公有成员函数) [编辑]
emplace_hint (C++11)	使用提示就地构造元素 (公有成员函数) [编辑]
try_emplace (C++17)	如果键不存在则就地插入，如果键存在则不执行任何操作 (公有成员函数) [编辑]
erase	移除元素 (公有成员函数) [编辑]
swap	交换内容 (公有成员函数) [编辑]
extract (C++17)	从容器提取节点 (公有成员函数) [编辑]
merge (C++17)	从另一个容器拼接节点 (公有成员函数) [编辑]
查找
count	返回匹配特定键的元素数量 (公有成员函数) [编辑]
find	查找具有特定键的元素 (公有成员函数) [编辑]
contains (C++20)	检查容器是否含有具有特定键的元素 (公有成员函数) [编辑]
equal_range	返回匹配特定键的元素范围 (公有成员函数) [编辑]
lower_bound	返回指向首个不小于给定键的元素的迭代器 (公有成员函数) [编辑]
upper_bound	返回指向首个大于给定键的元素的迭代器 (公有成员函数) [编辑]
观察器
key_comp	返回比较键的函数 (公有成员函数) [编辑]
value_comp	返回比较 `value_type` 类型的对象中键的函数 (公有成员函数) [编辑]

[编辑] 非成员函数

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20)	按字典序比较两个 `map` 的值 (函数模板) [编辑]
std::swap(std::map)	特化 std::swap 算法 (函数模板) [编辑]
erase_if(std::map) (C++20)	移除所有满足特定标准的元素 (函数模板) [编辑]

推导指引	(since C++17)

[编辑] 注解

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

[编辑] 示例

运行此代码

#include <iostream>
#include <map>
#include <string>
#include <string_view>
 
void print_map(std::string_view comment, const std::map<std::string, int>& m)
{
    std::cout << comment;
    // Iterate using C++17 facilities
    for (const auto& [key, value] : m)
        std::cout << '[' << key << "] = " << value << "; ";
 
// C++11 alternative:
//  for (const auto& n : m)
//      std::cout << n.first << " = " << n.second << "; ";
//
// C++98 alternative:
//  for (std::map<std::string, int>::const_iterator it = m.begin(); it != m.end(); ++it)
//      std::cout << it->first << " = " << it->second << "; ";
 
    std::cout << '\n';
}
 
int main()
{
    // Create a map of three (string, int) pairs
    std::map<std::string, int> m{{"CPU", 10}, {"GPU", 15}, {"RAM", 20}};
 
    print_map("1) Initial map: ", m);
 
    m["CPU"] = 25; // update an existing value
    m["SSD"] = 30; // insert a new value
    print_map("2) Updated map: ", m);
 
    // Using operator[] with non-existent key always performs an insert
    std::cout << "3) m[UPS] = " << m["UPS"] << '\n';
    print_map("4) Updated map: ", m);
 
    m.erase("GPU");
    print_map("5) After erase: ", m);
 
    std::erase_if(m, [](const auto& pair){ return pair.second > 25; });
    print_map("6) After erase: ", m);
    std::cout << "7) m.size() = " << m.size() << '\n';
 
    m.clear();
    std::cout << std::boolalpha << "8) Map is empty: " << m.empty() << '\n';
}

输出

1) Initial map: [CPU] = 10; [GPU] = 15; [RAM] = 20;
2) Updated map: [CPU] = 25; [GPU] = 15; [RAM] = 20; [SSD] = 30;
3) m[UPS] = 0
4) Updated map: [CPU] = 25; [GPU] = 15; [RAM] = 20; [SSD] = 30; [UPS] = 0;
5) After erase: [CPU] = 25; [RAM] = 20; [SSD] = 30; [UPS] = 0;
6) After erase: [CPU] = 25; [RAM] = 20; [UPS] = 0;
7) m.size() = 3
8) Map is empty: true

[编辑] 缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

DR	应用于	已发布行为	正确行为
LWG 230	C++98	`Key` 未被要求为 CopyConstructible （可能无法构造 `Key` 类型的键）	`Key` 也被要求为 CopyConstructible
LWG 464	C++98	通过键访问 const `map` 不方便	提供了 `at` 函数

[编辑] 参见

multimap	键值对的集合，按键排序 (类模板) [编辑]
unordered_map (C++11)	键值对的集合，通过键哈希，键是唯一的 (类模板) [编辑]
flat_map (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)
表格
迭代器失效
成员函数表
非成员函数表

cppreference.cn

命名空间

变体

视图

操作