Spec-Zone.ru › C++

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. Операции поиска, удаления и вставки имеют логарифмическую сложность. Обычно карты реализуются как красно-чёрные деревья.

Итераторы 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 обычно является ошибкой, поскольку для вычисления константного выражения требуется освободить всё динамически выделенное хранилище в ходе того же вычисления, что обычно не происходит при инициализации std::map.

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

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

Типы-члены

Тип Определение
key_type Key
mapped_type T
value_type std::pair<constKey,T>
size_type беззнаковый целочисленный тип (обычно std::size_t)
difference_type знаковый целочисленный тип (обычно std::ptrdiff_t)
key_compare Compare
allocator_type Allocator
reference value_type&
const_reference constvalue_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 и ConstexprIterator(начиная с C++26) к value_type
const_iterator LegacyBidirectionalIterator и ConstexprIterator(начиная с C++26) к constvalue_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 /* 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
вставляет элементы или узлы(начиная с 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)
удаляет все элементы, соответствующие заданному условию
(шаблон функции)

Руководства по выводу типов

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

Примечания

Макрос проверки поддержки возможностей Значение Стандарт Возможность
__cpp_lib_containers_ranges 202202L (C++23) Создание и вставка элементов контейнеров с использованием диапазонов
__cpp_lib_constexpr_map 202502L (C++26) Константное выражение 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++.

Отчёт об ошибке Применён к Опубликованное поведение Корректное поведение
LWG 230 C++98 Для Key не требовалось удовлетворять требованиям CopyConstructible
(ключ типа Key мог быть невозможно сконструировать)
Для Key также требуется
удовлетворять требованиям CopyConstructible
LWG 464 C++98 доступ к константному map по ключу был неудобен Предоставлена функция at

См. также

multimap
коллекция пар ключ-значение, отсортированных по ключам
(шаблон класса)
unordered_map
(C++11)
коллекция пар ключ-значение, хешируемых по ключам; ключи уникальны
(шаблон класса)
flat_map
(C++23)
адаптирует два контейнера для предоставления коллекции пар ключ-значение, отсортированных по уникальным ключам
(шаблон класса)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/container/map

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API