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.
| Все функции-члены Однако определение переменной | (начиная с 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;
};
с аргументами шаблона |
Функции-члены
создаёт unordered_map (открытая функция-член) |
|
уничтожает unordered_map (открытая функция-член) |
|
| присваивает значения контейнеру (открытая функция-член) |
|
| возвращает связанный аллокатор (открытая функция-член) |
|
Итераторы |
|
| возвращает итератор на начало (открытая функция-член) |
|
| возвращает итератор на конец (открытая функция-член) |
|
Ёмкость |
|
| проверяет, пуст ли контейнер (открытая функция-член) |
|
| возвращает количество элементов (открытая функция-член) |
|
| возвращает максимально возможное количество элементов (открытая функция-член) |
|
Модификаторы |
|
| очищает содержимое (открытая функция-член) |
|
| вставляет элементы или узлы(начиная с C++17) (открытая функция-член) |
|
|
(C++23) | вставляет диапазон элементов (открытая функция-член) |
|
(C++17) | вставляет элемент или присваивает значение существующему элементу, если ключ уже существует (открытая функция-член) |
| создаёт элемент на месте (открытая функция-член) |
|
| создаёт элементы на месте, используя подсказку (открытая функция-член) |
|
|
(C++17) | вставляет элемент на месте, если ключ не существует; если ключ существует, ничего не делает (открытая функция-член) |
| удаляет элементы (открытая функция-член) |
|
| обменивает содержимое (открытая функция-член) |
|
|
(C++17) | извлекает узлы из контейнера (открытая функция-член) |
|
(C++17) | перемещает узлы из другого контейнера (открытая функция-член) |
Поиск |
|
| обращается к заданному элементу с проверкой границ (открытая функция-член) |
|
| обращается к заданному элементу или вставляет его (открытая функция-член) |
|
| возвращает количество элементов с заданным ключом (открытая функция-член) |
|
| находит элемент с заданным ключом (открытая функция-член) |
|
|
(C++20) | проверяет, содержит ли контейнер элемент с заданным ключом (открытая функция-член) |
| возвращает диапазон элементов с заданным ключом (открытая функция-член) |
|
Интерфейс корзин |
|
| возвращает итератор на начало указанной корзины (открытая функция-член) |
|
| возвращает итератор на конец указанной корзины (открытая функция-член) |
|
| возвращает количество корзин (открытая функция-член) |
|
| возвращает максимальное количество корзин (открытая функция-член) |
|
| возвращает количество элементов в указанной корзине (открытая функция-член) |
|
| возвращает корзину для заданного ключа (открытая функция-член) |
|
Политика хеширования |
|
| возвращает среднее количество элементов на корзину (открытая функция-член) |
|
| управляет максимальным средним количеством элементов на корзину (открытая функция-член) |
|
| резервирует не менее указанного количества корзин и перестраивает хеш-таблицу (открытая функция-член) |
|
| резервирует место как минимум для указанного количества элементов и перестраивает хеш-таблицу (открытая функция-член) |
|
Наблюдатели |
|
| возвращает функцию, используемую для хеширования ключей (открытая функция-член) |
|
| возвращает функцию, используемую для сравнения ключей на равенство (открытая функция-член) |
|
Функции, не являющиеся членами
|
(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) | Константное выражение 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 |
См. также
|
(C++11) | коллекция пар «ключ-значение», хешированных по ключам (шаблон класса) |
| коллекция пар «ключ-значение», отсортированных по ключам; ключи уникальны (шаблон класса) |
|
|
(C++23) | адаптирует два контейнера для предоставления коллекции пар «ключ-значение», отсортированных по уникальным ключам (шаблон класса) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/container/unordered_map