std::unordered_map

 

C++

Поддержка компилятором

Автономные и размещённые реализации

Язык

Стандартная библиотека

Заголовки стандартной библиотеки

Требования к именованию

Макросы тестирования функциональности (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)

Недействительные итераторы

Таблица функций-элементов

Таблица функций, не являющихся элементами

 

std::unordered_map

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

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

unordered_map::unordered_map

unordered_map::~unordered_map

unordered_map::operator=

unordered_map::get_allocator

Итераторы

unordered_map::beginunordered_map::cbegin

unordered_map::endunordered_map::cend

Ёмкость

unordered_map::empty

unordered_map::size

unordered_map::max_size

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

unordered_map::clear

unordered_map::insert

unordered_map::insert_range (C++23)

unordered_map::insert_or_assign (C++17)

unordered_map::emplace

unordered_map::emplace_hint

unordered_map::try_emplace (C++17)

unordered_map::erase

unordered_map::swap

unordered_map::extract (C++17)

unordered_map::merge (C++17)

Просмотр

unordered_map::at

unordered_map::operator[]

unordered_map::count

unordered_map::find

unordered_map::contains (C++20)

unordered_map::equal_range

Интерфейс сегментов

unordered_map::begin(size_type)unordered_map::cbegin(size_type)

unordered_map::end(size_type)unordered_map::cend(size_type)

unordered_map::bucket_count

unordered_map::max_bucket_count

unordered_map::bucket_size

unordered_map::bucket

Политика хэширования

unordered_map::load_factor

unordered_map::max_load_factor

unordered_map::rehash

unordered_map::reserve

Наблюдатели

unordered_map::hash_function

unordered_map::key_eq

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

operator==operator!= (до C++20)

std::swap

erase_if (C++20)

Принципы вывода (C++17)

 

Определено в заголовочном файле <unordered_map>
template<     class Key,     class T,     class Hash = std::hash<Key>,     class KeyEqual = std::equal_to<Key>,     class Allocator = std::allocator< std::pair<const Key, T> > > class unordered_map;	(1)	(начиная с C++11)
namespace pmr { template <class Key,     class T,     class Hash = std::hash<Key>,     class Pred = std::equal_to<Key> > using unordered_map = std::unordered_map<Key, T, Hash, Pred,                             std::pmr::polymorphic_allocator<std::pair<const Key,T>>>; }	(2)	(начиная с C++17)

std::unordered_map это ассоциативный контейнер, содержащий пары ключ-значение с уникальными ключами. Поиск, вставка и удаление элементов имеют среднюю постоянную сложность.

Внутри элементы не сортируются в каком-либо определённом порядке, а организованы в сегменты. В какой сегмент помещается элемент, полностью зависит от хеша его ключа. Ключи с одинаковым хэш-кодом находятся в одном сегменте. Это обеспечивает быстрый доступ к отдельным элементам, поскольку после вычисления хэша он обращается к точному сегменту, в котором размещён элемент.

Два ключа считаются эквивалентными, если предикат равенства ключей карты возвращает true при передаче этих ключей. Если два ключа эквивалентны, хэш-функция должна возвращать одно и то же значение для обоих ключей.

std::unordered_map соответствует требованиям Container, AllocatorAwareContainer, UnorderedAssociativeContainer.

Аннулирование итератора

Операции	Недействителен
Все операции только для чтения, swap, std::swap	Ни один
clear, rehash, reserve, operator=	Все
insert, emplace, emplace_hint, operator[]	Только если вызывает перехэширование
erase	Только на стёртый элемент

Примечание

• Функции обмена не делают недействительными ни один из итераторов внутри контейнера, но они делают недействительным итератор, отмечающий конец области обмена.

• Ссылки и указатели на любой ключ или данные, хранящиеся в контейнере, становятся недействительными только при удалении этого элемента, даже если соответствующий итератор становится недействительным.

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

Тип элемент	Определение
key_type	Key
mapped_type	T
value_type	std::pair<const Key, T>
size_type	Беззнаковый целочисленный тип (обычно std::size_t)
difference_type	Знаковый целочисленный тип (обычно std::ptrdiff_t)
hasher	Hash
key_equal	KeyEqual
allocator_type	Allocator
reference	value_type&
const_reference	const value_type&
pointer	std::allocator_traits<Allocator>::pointer
const_pointer	std::allocator_traits<Allocator>::const_pointer
iterator	LegacyForwardIterator в value_type
const_iterator	LegacyForwardIterator в const value_type
local_iterator	Тип итератора, category, value, difference, pointer и ссылочные типы которого совпадают с типами iterator. Этот итератор можно использовать для итерации по одному сегменту, но не по сегментам.
const_local_iterator	Тип итератора, category, value, difference, pointer и ссылочные типы которого совпадают с типами 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.

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

(конструктор) (C++11)	создаёт unordered_map (public функция-элемент)
(деструктор) (C++11)	уничтожает unordered_map (public функция-элемент)
operator= (C++11)	присваивает значения контейнеру (public функция-элемент)
get_allocator (C++11)	возвращает связанный аллокатор (public функция-элемент)
Итераторы
begin cbegin (C++11)	возвращает итератор на начало (public функция-элемент)
end cend (C++11)	возвращает итератор на конец (public функция-элемент)
Ёмкость
empty (C++11)	проверяет, пуст ли контейнер (public функция-элемент)
size (C++11)	возвращает количество элементов (public функция-элемент)
max_size (C++11)	возвращает максимально возможное количество элементов (public функция-элемент)
Модификаторы
clear (C++11)	очищает содержимое (public функция-элемент)
insert (C++11)	вставляет элементы или узлы (начиная с 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 (C++11)	удаляет элементы (public функция-элемент)
swap (C++11)	обменивает содержимое (public функция-элемент)
extract (C++17)	извлекает узлы из контейнера (public функция-элемент)
merge (C++17)	сливает с узлами из другого контейнера (public функция-элемент)
Просмотр
at (C++11)	предоставляет доступ к указанному элементу с проверкой границ (public функция-элемент)
operator[] (C++11)	предоставляет доступ к или вставляет указанному элементу (public функция-элемент)
count (C++11)	возвращает количество элементов, соответствующих определённому ключу (public функция-элемент)
find (C++11)	ищет элемент с определённым ключом (public функция-элемент)
contains (C++20)	проверяет, содержит ли контейнер элемент с определённым ключом (public функция-элемент)
equal_range (C++11)	возвращает диапазон элементов, соответствующих определённому ключу (public функция-элемент)
Интерфейс сегментов
begin(size_type) cbegin(size_type) (C++11)	возвращает итератор на начало указанного сегмента (public функция-элемент)
end(size_type) cend(size_type) (C++11)	возвращает итератор на конец указанного сегмента (public функция-элемент)
bucket_count (C++11)	возвращает количество сегментов (public функция-элемент)
max_bucket_count (C++11)	возвращает максимальное количество сегментов (public функция-элемент)
bucket_size (C++11)	возвращает количество элементов в конкретном сегменте (public функция-элемент)
bucket (C++11)	возвращает сегмент для конкретного ключа (public функция-элемент)
Политика хеширования
load_factor (C++11)	возвращает среднее количество элементов на сегмент (public функция-элемент)
max_load_factor (C++11)	управляет максимальным средним количеством элементов на сегмент (public функция-элемент)
rehash (C++11)	резервирует как минимум указанное количество сегментов и регенерирует хеш-таблицу (public функция-элемент)
reserve (C++11)	резервирует место по крайней мере для указанного количества элементов и регенерирует хеш-таблицу (public функция-элемент)
Наблюдатели
hash_function (C++11)	возвращает функцию, используемую для хэширования ключей (public функция-элемент)
key_eq (C++11)	возвращает функцию, используемую для сравнения ключей на равенство (public функция-элемент)

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

operator==operator!= (удалено в C++20)	сравнивает значения в unordered_map (шаблон функции)
std::swap(std::unordered_map) (C++11)	специализация алгоритма std::swap (шаблон функции)
erase_if(std::unordered_map) (C++20)	стирает все элементы, соответствующие определённым критериям (шаблон функции)

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

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

Примечание

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

Пример

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

#include <iostream>
#include <string>
#include <unordered_map>
 
int main()
{
    // Создание unordered_map из трёх строк (которые сопоставляются со строками)
    std::unordered_map<std::string, std::string> u = {
        {"КРАСНЫЙ","#FF0000"},
        {"ЗЕЛЁНЫЙ","#00FF00"},
        {"СИНИЙ","#0000FF"}
    };
 
    // Вспомогательная лямбда-функция для печати пар ключ-значение
    auto print_key_value = [](const auto& key, const auto& value) {
        std::cout << "Ключ:[" << key << "] Значение:[" << value << "]\n";
    };
 
    std::cout << "Итерация и печать пар ключ-значение unordered_map,\n"
                 "с явным указанием их типов:\n";
    for( const std::pair<const std::string, std::string>& n : u ) {
        print_key_value(n.first, n.second);
    }
 
    std::cout << "\nИтерация и печать пар ключ-значение, "
                 "используя структурную привязку C++17:\n";
    for( const auto& [key, value] : u ) {
        print_key_value(key, value);
    }
 
    // Добавление двух новых записей в unordered_map
    u["ЧЁРНЫЙ"] = "#000000";
    u["БЕЛЫЙ"] = "#FFFFFF";
 
    std::cout << "\nВывод значений по ключу:\n"
                 "Шестнадцатиричное значение цвета КРАСНЫЙ:[" << u["КРАСНЫЙ"] << "]\n"
                 "Шестнадцатиричное значение цвета ЧЁРНЫЙ:[" << u["ЧЁРНЫЙ"] << "]\n\n";
 
    std::cout << "Используйте operator[] с несуществующим ключом, "
                 "чтобы вставить новую пару ключ-значение:\n";
    print_key_value("новый_ключ", u["новый_ключ"]);
 
    std::cout << "\nИтерация и печать пар ключ-значение, используя `auto`;\n"
                 "новый_ключ теперь является одним из ключей в карте:\n";
    for( const auto& n : u ) {
        print_key_value(n.first, n.second);
    }
}

Возможный вывод:

Итерация и печать пар ключ-значение unordered_map,
с явным указанием их типов:
Key:[СИНИЙ] Value:[#0000FF]
Key:[ЗЕЛЁНЫЙ] Value:[#00FF00]
Key:[КРАСНЫЙ] Value:[#FF0000]
 
Итерация и печать пар ключ-значение, используя структурную привязку C++17:
Key:[СИНИЙ] Value:[#0000FF]
Key:[ЗЕЛЁНЫЙ] Value:[#00FF00]
Key:[КРАСНЫЙ] Value:[#FF0000]
 
Вывод значений по ключу:
Шестнадцатиричное значение цвета КРАСНЫЙ:[#FF0000]
Шестнадцатиричное значение цвета ЧЁРНЫЙ:[#000000]
 
Используйте operator[] с несуществующим ключом, чтобы вставить новую пару ключ-значение:
Key:[новый_ключ] Value:[]
 
Итерация и печать пар ключ-значение, используя `auto`;
новый_ключ теперь является одним из ключей в карте:
Key:[новый_ключ] Value:[]
Key:[БЕЛЫЙ] Value:[#FFFFFF]
Key:[ЧЁРНЫЙ] Value:[#000000]
Key:[СИНИЙ] Value:[#0000FF]
Key:[ЗЕЛЁНЫЙ] Value:[#00FF00]
Key:[КРАСНЫЙ] Value:[#FF0000]

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

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

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 2050	C++11	определения reference, const_reference, pointer и const_pointer были основаны на allocator_type	на основе value_type и std::allocator_traits

Смотрите также

map	коллекция пар ключ-значение, отсортированных по ключам, ключи уникальны (шаблон класса)