Spec-Zone.ru › C++

std::unordered_map

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

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

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

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

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

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

(начиная с 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<constKey,T>
size_type беззнаковый целочисленный тип (обычно std::size_t)
difference_type знаковый целочисленный тип (обычно std::ptrdiff_t)
hasher Hash
key_equal KeyEqual
allocator_type Allocator
reference value_type&
const_reference constvalue_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) для constvalue_type
local_iterator тип итератора, категории, типы значения, разности, указателя и
ссылки которого совпадают с iterator. Этот итератор
можно использовать для обхода одной корзины, но не для перехода между корзинами
const_local_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.

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

(constructor)
создаёт unordered_map
(открытая функция-член)
(destructor)
уничтожает unordered_map
(открытая функция-член)
operator=
присваивает значения контейнеру
(открытая функция-член)
get_allocator
возвращает связанный аллокатор
(открытая функция-член)
Итераторы
begincbegin
возвращает итератор на начало
(открытая функция-член)
endcend
возвращает итератор на конец
(открытая функция-член)
Ёмкость
empty
проверяет, пуст ли контейнер
(открытая функция-член)
size
возвращает количество элементов
(открытая функция-член)
max_size
возвращает максимально возможное количество элементов
(открытая функция-член)
Модификаторы
clear
очищает содержимое
(открытая функция-член)
insert
вставляет элементы или узлы(начиная с C++17)
(открытая функция-член)
insert_range
(C++23)
вставляет диапазон элементов
(открытая функция-член)
insert_or_assign
(C++17)
вставляет элемент или присваивает значение существующему элементу, если ключ уже существует
(открытая функция-член)
emplace
создаёт элемент на месте
(открытая функция-член)
emplace_hint
создаёт элементы на месте, используя подсказку
(открытая функция-член)
try_emplace
(C++17)
вставляет элемент на месте, если ключ не существует; если ключ существует, ничего не делает
(открытая функция-член)
erase
удаляет элементы
(открытая функция-член)
swap
обменивает содержимое
(открытая функция-член)
extract
(C++17)
извлекает узлы из контейнера
(открытая функция-член)
merge
(C++17)
перемещает узлы из другого контейнера
(открытая функция-член)
Поиск
at
обращается к заданному элементу с проверкой границ
(открытая функция-член)
operator[]
обращается к заданному элементу или вставляет его
(открытая функция-член)
count
возвращает количество элементов с заданным ключом
(открытая функция-член)
find
находит элемент с заданным ключом
(открытая функция-член)
contains
(C++20)
проверяет, содержит ли контейнер элемент с заданным ключом
(открытая функция-член)
equal_range
возвращает диапазон элементов с заданным ключом
(открытая функция-член)
Интерфейс корзин
begin(size_type)cbegin(size_type)
возвращает итератор на начало указанной корзины
(открытая функция-член)
end(size_type)cend(size_type)
возвращает итератор на конец указанной корзины
(открытая функция-член)
bucket_count
возвращает количество корзин
(открытая функция-член)
max_bucket_count
возвращает максимальное количество корзин
(открытая функция-член)
bucket_size
возвращает количество элементов в указанной корзине
(открытая функция-член)
bucket
возвращает корзину для заданного ключа
(открытая функция-член)
Политика хеширования
load_factor
возвращает среднее количество элементов на корзину
(открытая функция-член)
max_load_factor
управляет максимальным средним количеством элементов на корзину
(открытая функция-член)
rehash
резервирует не менее указанного количества корзин и перестраивает хеш-таблицу
(открытая функция-член)
reserve
резервирует место как минимум для указанного количества элементов и перестраивает хеш-таблицу
(открытая функция-член)
Наблюдатели
hash_function
возвращает функцию, используемую для хеширования ключей
(открытая функция-член)
key_eq
возвращает функцию, используемую для сравнения ключей на равенство
(открытая функция-член)

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

operator==operator!=
(C++11)(C++11)(удалён в 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) Создание контейнеров и вставка в них с использованием диапазонов
__cpp_lib_constexpr_unordered_map 202502L (C++26) Константное выражение std::unordered_map

Пример

#include <iostream>
#include <string>
#include <unordered_map>

int main()
{
    // Create an unordered_map of three strings (that map to strings)
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
    
    // Helper lambda function to print key-value pairs
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Key:[" << key << "] Value:[" << value << "]\n";
    };
    
    std::cout << "Iterate and print key-value pairs of unordered_map, being\n"
                 "explicit with their types:\n";
    for (const std::pair<const std::string, std::string>& n : u)
        print_key_value(n.first, n.second);
    
    std::cout << "\nIterate and print key-value pairs using C++17 structured binding:\n";
    for (const auto& [key, value] : u)
        print_key_value(key, value);
    
    // Add two new entries to the unordered_map
    u["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
    
    std::cout << "\nOutput values by key:\n"
                 "The HEX of color RED is:[" << u["RED"] << "]\n"
                 "The HEX of color BLACK is:[" << u["BLACK"] << "]\n\n";
    
    std::cout << "Use operator[] with non-existent key to insert a new key-value pair:\n";
    print_key_value("new_key", u["new_key"]);
    
    std::cout << "\nIterate and print key-value pairs, using `auto`;\n"
                 "new_key is now one of the keys in the map:\n";
    for (const auto& n : u)
        print_key_value(n.first, n.second);
}

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

Iterate and print key-value pairs of unordered_map, being
explicit with their types:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]

Iterate and print key-value pairs using C++17 structured binding:
Key:[BLUE] Value:[#0000FF]
Key:[GREEN] Value:[#00FF00]
Key:[RED] Value:[#FF0000]

Output values by key:
The HEX of color RED is:[#FF0000]
The HEX of color BLACK is:[#000000]

Use operator[] with non-existent key to insert a new key-value pair:
Key:[new_key] Value:[]

Iterate and print key-value pairs, using `auto`;
new_key is now one of the keys in the 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

См. также

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

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

Spec-Zone.ru

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