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)	(начиная с C++17)

std::map это сортируемый ассоциативный контейнер, который содержит пары ключ-значение с уникальными ключами. Ключи сортируются с помощью функции сравнения Compare. Операции поиска, удаления и вставки имеют логарифмическую сложность. Карты обычно реализуются как красно-чёрные деревья.

Везде, где стандартная библиотека использует требования Compare, уникальность определяется с помощью отношения эквивалентности. Грубо говоря, два объекта a и b считаются эквивалентными (не уникальными), если ни один из них при сравнении не меньше, чем другой: !comp(a, b) && !comp(b, a).

std::map соответствует требованиям Container, AllocatorAwareContainer, AssociativeContainer и ReversibleContainer.

Параметры шаблона

Типы элементы

Тип элемент Определение

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`	(до C++11)
`std::allocator_traits<Allocator>::pointer`	(начиная с C++11)

[править]

const_pointer

`Allocator::const_pointer`	(до C++11)
`std::allocator_traits<Allocator>::const_pointer`	(начиная с C++11)

[править]

iterator LegacyBidirectionalIterator в value_type [править]

const_iterator LegacyBidirectionalIterator в const value_type [править]

reverse_iterator std::reverse_iterator<iterator>[править]

const_reverse_iterator std::reverse_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. [править]

Классы элементы

value_compare

сравнивает объекты типа value_type
(класс) [править]

Функции элементы

(конструктор)	создаёт `map` (public функция-элемент) [править]
(деструктор)	уничтожает `map` (public функция-элемент) [править]
operator=	присваивает значения контейнеру (public функция-элемент) [править]
get_allocator	возвращает связанный аллокатор (public функция-элемент) [править]
Доступ к элементам
at	предоставляет доступ к указанному элементу с проверкой границ (public функция-элемент) [править]
operator[]	предоставляет доступ к или вставляет указанному элементу (public функция-элемент) [править]
Итераторы
begin cbegin (C++11)	возвращает итератор на начало (public функция-элемент) [править]
end cend (C++11)	возвращает итератор на конец (public функция-элемент) [править]
rbegin crbegin (C++11)	возвращает обратный итератор на начало (public функция-элемент) [править]
rend crend (C++11)	возвращает обратный итератор на конец (public функция-элемент) [править]
Ёмкость
empty	проверяет, пуст ли контейнер (public функция-элемент) [править]
size	возвращает количество элементов (public функция-элемент) [править]
max_size	возвращает максимально возможное количество элементов (public функция-элемент) [править]
Модификаторы
clear	очищает содержимое (public функция-элемент) [править]
insert	вставляет элементы или узлы (начиная с C++17) (public функция-элемент) [править]
insert_range (C++23)	вставляет ряд элементов (public функция-элемент) [править]
insert_or_assign (C++17)	вставляет элемент или присваивает текущему элементу, если ключ уже существует (public функция-элемент) [править]
emplace (C++11)	создаёт элемент на месте (public функция-элемент) [править]
emplace_hint (C++11)	создаёт элементы на месте, используя подсказку (public функция-элемент) [править]
try_emplace (C++17)	вставляет "на месте", если ключ не существует, ничего не делает, если ключ существует (public функция-элемент) [править]
erase	удаляет элементы (public функция-элемент) [править]
swap	обменивает содержимое (public функция-элемент) [править]
extract (C++17)	извлекает узлы из контейнера (public функция-элемент) [править]
merge (C++17)	сливает с узлами из другого контейнера (public функция-элемент) [править]
Просмотр
count	возвращает количество элементов, соответствующих определённому ключу (public функция-элемент) [править]
find	ищет элемент с определённым ключом (public функция-элемент) [править]
contains (C++20)	проверяет, содержит ли контейнер элемент с определённым ключом (public функция-элемент) [править]
equal_range	возвращает диапазон элементов, соответствующих определённому ключу (public функция-элемент) [править]
lower_bound	возвращает итератор на первый элемент не меньший, чем заданный ключ (public функция-элемент) [править]
upper_bound	возвращает итератор на первый элемент больший, чем заданный ключ (public функция-элемент) [править]
Наблюдатели
key_comp	возвращает функцию, сравнивающую ключи (public функция-элемент) [править]
value_comp	возвращает функцию, которая сравнивает ключи в объектах типа value_type (public функция-элемент) [править]

Функции, не являющиеся элементами

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)	стирает все элементы, соответствующие определённым критериям (шаблон функции) [править]

Принципы вывода

(начиная с C++17)

Примечание

Макрос тест функциональности	Значение	Стандарт	Комментарий
`__cpp_lib_containers_ranges`	`202202L`	(C++23)	Создание и вставка диапазонов для контейнеров

Пример

Запустить этот код

#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;
    // итерация с использованием средств C++17
    for (const auto& [key, value] : m) {
        std::cout << '[' << key << "] = " << value << "; ";
    }
// альтернатива C++11:
//  for (const auto& n : m) {
//      std::cout << '[' << n.first << "] = " << n.second << "; ";
//  }
// альтернатива C++98:
//  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()
{
    // Создаём карту из трёх строк (которые отображаются на целые числа)
    std::map<std::string, int> m { {"CPU", 10}, {"GPU", 15}, {"RAM", 20}, };

    print_map("1) Начальная карта: ", m);

    m["CPU"] = 25;  // модифицируем существующее значение
    m["SSD"] = 30;  // вставляем новое значение

    print_map("2) Модифицированная карта: ", m);

    // использование operator[] с несуществующим ключом всегда выполняет вставку
    std::cout << "3) m[UPS] = " << m["UPS"] << '\n';
    print_map("4) Модифицированная карта: ", m);

    m.erase("GPU");
    print_map("5) После стирания: ", m);

    std::erase_if(m, [](const auto& pair){ return pair.second > 25; });
    print_map("6) После стирания: ", m);
    std::cout << "7) m.size() = " << m.size() << '\n';

    m.clear();
    std::cout << std::boolalpha << "8) Карта пуста: " << m.empty() << '\n';
}

Вывод:

1) Начальная карта: [CPU] = 10; [GPU] = 15; [RAM] = 20; 
2) Модифицированная карта: [CPU] = 25; [GPU] = 15; [RAM] = 20; [SSD] = 30;
3) m[UPS] = 0
4) Модифицированная карта: [CPU] = 25; [GPU] = 15; [RAM] = 20; [SSD] = 30; [UPS] = 0; 
5) После стирания: [CPU] = 25; [RAM] = 20; [SSD] = 30; [UPS] = 0; 
6) После стирания: [CPU] = 25; [RAM] = 20; [UPS] = 0; 
7) m.size() = 3
8) Карта пуста: true

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 464	C++98	доступ к const `map` по ключу был неудобным	предоставлена функция `at`

Поддержка компилятором
Автономные и размещённые реализации
Язык
Стандартная библиотека
Заголовки стандартной библиотеки
Требования к именованию
Макросы тестирования функциональности (C++20)
Поддержка языка
Библиотека концептов (C++20)
Библиотека метапрограммирования (C++11)
Библиотека диагностики
Библиотека общих утилит
Библиотека строк
Библиотека контейнеров
Библиотека итераторов
Библиотека диапазонов (C++20)
Библиотека алгоритмов
Библиотека численных данных
Библиотека ввода/вывода
Библиотека локализаций
Регулярные выражения (C++11)
Атомарные операции (C++11)
Библиотека поддержки конкуренции (C++11)
Библиотека файловой системы (C++17)
Технические спецификации
Указатель символов
Внешние библиотеки

Последовательные
array (C++11)
vector
vector<bool>
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)
Недействительные итераторы
Таблица функций-элементов
Таблица функций, не являющихся элементами

Функции элементы
map::map
map::~map
map::operator=
map::get_allocator
Доступ к элементам
map::at
map::operator[]
Итераторы
map::beginmap::cbegin (C++11)
map::endmap::cend (C++11)
map::rbeginmap::crbegin (C++11)
map::rendmap::crend (C++11)
Ёмкость
map::empty
map::size
map::max_size
Модификаторы
map::clear
map::insert
map::insert_range (C++23)
map::insert_or_assign (C++17)
map::emplace (C++11)
map::emplace_hint (C++11)
map::try_emplace (C++17)
map::erase
map::swap
map::extract (C++17)
map::merge (C++17)
Просмотр
map::count
map::find
map::contains (C++20)
map::equal_range
map::lower_bound
map::upper_bound
Наблюдатели
map::key_comp
map::value_comp
Функции, не являющиеся элементами
std::swap
erase_if (C++20)
operator==operator!=operator<operator>operator<=operator>=operator<=> (до C++20)(до C++20)(до C++20)(до C++20)(до C++20)(C++20)
Принципы вывода (C++17)

cppreference.com

Поиск

Пространства имён

Варианты

Просмотры

Действия

std::map

Содержание

Параметры шаблона

Типы элементы

Классы элементы

Функции элементы

Доступ к элементам

Итераторы

Ёмкость

Модификаторы

Просмотр

Наблюдатели

Функции, не являющиеся элементами

Принципы вывода

Примечание

Пример

Отчёты о дефектах

Навигация

Инструменты