Namespaces
Variants

std:: unordered_map

From cppreference.net
C++
Containers library
std::unordered_map
Member types
Member functions
Non-member functions
Deduction guides (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 KeyEqual = std:: equal_to < Key >
> using unordered_map =
std :: unordered_map < Key, T, Hash, KeyEqual,
std:: pmr :: polymorphic_allocator < std:: pair < const Key, T >>> ;

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

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

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

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

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

Все функции-члены std::unordered_map являются constexpr : возможно создавать и использовать объекты std::unordered_map при вычислении константного выражения.

Однако, объекты std::unordered_map обычно не могут быть constexpr , поскольку любая динамически выделенная память должна быть освобождена в том же вычислении константного выражения.

(since C++26)

Содержание

Инвалидация итераторов

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

Примечания

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

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

Этот раздел не завершён
Причина: Добавьте описания параметров шаблона.

Типы членов

Тип Определение
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 и ConstexprIterator (начиная с C++26) для value_type
const_iterator LegacyForwardIterator и ConstexprIterator (начиная с C++26) для const value_type
local_iterator Тип итератора, категория, тип значения, разности, указателя и
ссылки которого совпадают с iterator . Этот итератор
может использоваться для обхода одной корзины, но не между корзинами
const_local_iterator Тип итератора, категория, тип значения, разности, указателя и
ссылки которого совпадают с const_iterator . Этот итератор
может использоваться для обхода одной корзины, но не между корзинами
node_type (начиная с C++17) специализация node handle представляющая узел контейнера
insert_return_type (начиная с C++17) тип, описывающий результат вставки node_type , специализация

template < class Iter, class NodeType >
struct /*unspecified*/
{
Iter     position ;
bool inserted ;
NodeType node ;
} ;
инстанцированная с шаблонными аргументами iterator и node_type .

Функции-члены

конструирует unordered_map
(публичная функция-член)
уничтожает unordered_map
(публичная функция-член)
присваивает значения контейнеру
(public member function)
возвращает связанный аллокатор
(публичная функция-член)
Итераторы
возвращает итератор на начало
(public member function)
возвращает итератор на конец
(public member function)
Ёмкость
проверяет, является ли контейнер пустым
(публичная функция-член)
возвращает количество элементов
(публичная функция-член)
возвращает максимально возможное количество элементов
(public member function)
Модификаторы
очищает содержимое
(публичная функция-член)
вставляет элементы или узлы (since C++17)
(публичная функция-член)
(C++23)
вставляет диапазон элементов
(публичная функция-член)
(C++17)
вставляет элемент или присваивает значение существующему элементу, если ключ уже существует
(публичная функция-член)
создаёт элемент на месте
(публичная функция-член)
конструирует элементы на месте с использованием подсказки
(публичная функция-член)
(C++17)
вставляет на месте, если ключ не существует, не делает ничего, если ключ существует
(публичная функция-член)
удаляет элементы
(публичная функция-член)
обменивает содержимое
(публичная функция-член)
(C++17)
извлекает узлы из контейнера
(публичная функция-член)
(C++17)
объединяет узлы из другого контейнера
(публичная функция-член)
Поиск
доступ к указанному элементу с проверкой границ
(публичная функция-член)
доступ или вставка указанного элемента
(public member function)
возвращает количество элементов, соответствующих определённому ключу
(public member function)
находит элемент с заданным ключом
(public member function)
(C++20)
проверяет, содержит ли контейнер элемент с указанным ключом
(публичная функция-член)
возвращает диапазон элементов, соответствующих определённому ключу
(публичная функция-член)
Интерфейс Bucket
возвращает итератор на начало указанной корзины
(public member function)
возвращает итератор на конец указанной корзины
(public member function)
возвращает количество сегментов
(публичная функция-член)
возвращает максимальное количество сегментов
(публичная функция-член)
возвращает количество элементов в определённой корзине
(публичная функция-член)
возвращает сегмент для указанного ключа
(публичная функция-член)
Политика хеширования
возвращает среднее количество элементов на сегмент
(публичная функция-член)
управляет максимальным средним количеством элементов на сегмент
(публичная функция-член)
резервирует как минимум указанное количество сегментов и перестраивает хеш-таблицу
(публичная функция-член)
резервирует место как минимум для указанного количества элементов и перестраивает хеш-таблицу
(публичная функция-член)
Наблюдатели
возвращает функцию, используемую для хеширования ключей
(public member function)
возвращает функцию, используемую для сравнения ключей на равенство
(публичная функция-член)

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

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

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

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

Примечания

Макрос тестирования возможностей Значение Стандарт Функция
__cpp_lib_containers_ranges 202202L (C++23) Конструирование и вставка диапазонов для контейнеров
__cpp_lib_constexpr_unordered_map 202502L (C++26) constexpr std::unordered_map

Пример

Запустить этот код 
#include <iostream>
#include <string>
#include <unordered_map>
int main()
{
    // Создать unordered_map из трех строк (которые отображаются в строки)
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
    // Вспомогательная лямбда-функция для вывода пар ключ-значение
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Key:[" << key << "] Value:[" << 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["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
    std::cout << "\nВывод значений по ключу:\n"
                 "HEX цвета RED:[" << u["RED"] << "]\n"
                 "HEX цвета BLACK:[" << u["BLACK"] << "]\n\n";
    std::cout << "Использование operator[] с несуществующим ключом для вставки новой пары ключ-значение:\n";
    print_key_value("new_key", u["new_key"]);
    std::cout << "\nИтерация и вывод пар ключ-значение с использованием `auto`;\n"
                 "new_key теперь один из ключей в map:\n";
    for (const auto& n : u)
        print_key_value(n.first, n.second);
}

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

Итерация и вывод пар ключ-значение unordered_map, явно
указывая их типы:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
Итерация и вывод пар ключ-значение с использованием структурированных привязок C++17:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]
Вывод значений по ключу:
HEX цвета RED:[#FF0000]
HEX цвета BLACK:[#000000]
Использование operator[] с несуществующим ключом для вставки новой пары ключ-значение:
Key:[new_key] Value:[]
Итерация и вывод пар ключ-значение с использованием `auto`;
new_key теперь один из ключей в map:
Key:[new_key] Value:[]
Key:[WHITE] Value:[#FFFFFF]
Key:[BLACK] Value:[#000000]
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]

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

Следующие отчеты об изменениях поведения, влияющие на дефекты, были применены ретроактивно к ранее опубликованным стандартам C++.

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

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

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