std:: unordered_map

From es.cppreference.net

Definido en el encabezado `<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)	(desde 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)	(desde C++17)

std::unordered_map es un contenedor asociativo que contiene pares clave-valor con claves únicas. La búsqueda, inserción y eliminación de elementos tienen una complejidad temporal promedio constante.

Internamente, los elementos no se ordenan de ninguna manera particular, sino que se organizan en cubos. En qué cubo se coloca un elemento depende completamente del hash de su clave. Las claves con el mismo código hash aparecen en el mismo cubo. Esto permite un acceso rápido a elementos individuales, ya que una vez calculado el hash, este hace referencia al cubo que contiene el elemento.

Dos claves se consideran equivalentes si el predicado de igualdad de claves del mapa devuelve verdadero cuando se le pasan esas claves. Si dos claves son equivalentes, la función hash debe devolver el mismo valor para ambas claves.

std::unordered_map cumple con los requisitos de Container , AllocatorAwareContainer , UnorderedAssociativeContainer .

Todas las funciones miembro de


          std::unordered_map

son constexpr : es posible crear y utilizar objetos


          std::unordered_map

en la evaluación de una expresión constante.

Sin embargo, los objetos std::unordered_map generalmente no pueden ser constexpr , porque cualquier almacenamiento asignado dinámicamente debe liberarse en la misma evaluación de la expresión constante.

(since C++26)

Invalidación de iteradores

Operaciones	Invalidación
Todas las operaciones de solo lectura, swap , std::swap	Nunca
clear , rehash , reserve , operator=	Siempre
insert , emplace , emplace_hint , operator[]	Solo si causa rehash
erase	Solo al elemento eliminado

Notas

Las funciones de intercambio no invalidan ninguno de los iteradores dentro del contenedor, pero sí invalidan el iterador que marca el final de la región de intercambio.

Las referencias y punteros a la clave o los datos almacenados en el contenedor solo se invalidan al eliminar ese elemento, incluso cuando el iterador correspondiente queda invalidado.

Parámetros de plantilla

Esta sección está incompleta
Motivo: Agregar descripciones de los parámetros de plantilla.

Tipos miembro

Tipo	Definición
`key_type`	`Key`
`mapped_type`	`T`
`value_type`	`std::pair<const Key, T>`
`size_type`	tipo entero sin signo (normalmente std::size_t)
`difference_type`	tipo entero con signo (normalmente 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 y ConstexprIterator(desde C++26) a `value_type`
`const_iterator`	LegacyForwardIterator y ConstexprIterator(desde C++26) a `const value_type`
`local_iterator`	un tipo de iterador cuya categoría, valor, diferencia, puntero y tipos de referencia son los mismos que `iterator`. Este iterador se puede usar para iterar a través de un único cubo pero no entre cubos
`const_local_iterator`	un tipo de iterador cuya categoría, valor, diferencia, puntero y tipos de referencia son los mismos que `const_iterator`. Este iterador se puede usar para iterar a través de un único cubo pero no entre cubos
`node_type` (desde C++17)	una especialización de manejador de nodo que representa un nodo del contenedor
`insert_return_type` (desde C++17)	tipo que describe el resultado de insertar un `node_type`, una especialización de template< class Iter, class NodeType > struct /* unspecified */ { Iter position; bool inserted; NodeType node; }; instanciada con los argumentos de plantilla `iterator` y `node_type`.

Funciones miembro

(constructor)	construye el `unordered_map` (función miembro pública)
(destructor)	destruye el `unordered_map` (función miembro pública)
operator=	asigna valores al contenedor (función miembro pública)
get_allocator	devuelve el asignador asociado (función miembro pública)
Iteradores
begin cbegin	devuelve un iterador al inicio (función miembro pública)
end cend	devuelve un iterador al final (función miembro pública)
Capacidad
empty	comprueba si el contenedor está vacío (función miembro pública)
size	devuelve el número de elementos (función miembro pública)
max_size	devuelve el número máximo posible de elementos (función miembro pública)
Modificadores
clear	borra el contenido (función miembro pública)
insert	inserta elementos o nodos (desde C++17) (función miembro pública)
insert_range (C++23)	inserta un rango de elementos (función miembro pública)
insert_or_assign (C++17)	inserta un elemento o asigna al elemento actual si la clave ya existe (función miembro pública)
emplace	construye el elemento in situ (función miembro pública)
emplace_hint	construye elementos in-situ usando una pista (función miembro pública)
try_emplace (C++17)	inserta in-situ si la clave no existe, no hace nada si la clave existe (función miembro pública)
erase	elimina elementos (función miembro pública)
swap	intercambia los contenidos (función miembro pública)
extract (C++17)	extrae nodos del contenedor (función miembro pública)
merge (C++17)	empalma nodos desde otro contenedor (función miembro pública)
Búsqueda
at	acceder al elemento especificado con verificación de límites (función miembro pública)
operator[]	acceder o insertar elemento especificado (función miembro pública)
count	devuelve el número de elementos que coinciden con una clave específica (función miembro pública)
find	encuentra elemento con clave específica (función miembro pública)
contains (C++20)	verifica si el contenedor contiene un elemento con clave específica (función miembro pública)
equal_range	devuelve el rango de elementos que coinciden con una clave específica (función miembro pública)
Interfaz de Bucket
begin (size_type) cbegin (size_type)	devuelve un iterador al inicio del bucket especificado (función miembro pública)
end (size_type) cend (size_type)	devuelve un iterador al final del bucket especificado (función miembro pública)
bucket_count	devuelve el número de cubos (función miembro pública)
max_bucket_count	devuelve el número máximo de buckets (función miembro pública)
bucket_size	devuelve el número de elementos en un bucket específico (función miembro pública)
bucket	devuelve el bucket para una clave específica (función miembro pública)
Política de hash
load_factor	devuelve el número promedio de elementos por bucket (función miembro pública)
max_load_factor	gestiona el número máximo promedio de elementos por bucket (función miembro pública)
rehash	reserva al menos el número especificado de cubos y regenera la tabla hash (función miembro pública)
reserve	reserva espacio para al menos el número especificado de elementos y regenera la tabla hash (función miembro pública)
Observadores
hash_function	devuelve la función utilizada para hashear las claves (función miembro pública)
key_eq	devuelve la función utilizada para comparar claves por igualdad (función miembro pública)

Funciones no miembro

operator== operator!= (C++11) (C++11) (removed in C++20)	compara los valores en el unordered_map (plantilla de función)
std::swap (std::unordered_map) (C++11)	especializa el algoritmo std::swap (plantilla de función)
erase_if (std::unordered_map) (C++20)	borra todos los elementos que cumplen criterios específicos (plantilla de función)

Guías de deducción

(desde C++17)

Notas

Macro de prueba de características	Valor	Estándar	Característica
`__cpp_lib_containers_ranges`	`202202L`	(C++23)	Construcción e inserción de rangos para contenedores
`__cpp_lib_constexpr_unordered_map`	`202502L`	(C++26)	constexpr `std::unordered_map`

Ejemplo

Ejecutar este código

#include <iostream>
#include <string>
#include <unordered_map>
int main()
{
    // Crear un unordered_map de tres cadenas (que mapean a cadenas)
    std::unordered_map<std::string, std::string> u =
    {
        {"RED", "#FF0000"},
        {"GREEN", "#00FF00"},
        {"BLUE", "#0000FF"}
    };
    // Función lambda auxiliar para imprimir pares clave-valor
    auto print_key_value = [](const auto& key, const auto& value)
    {
        std::cout << "Clave:[" << key << "] Valor:[" << value << "]\n";
    };
    std::cout << "Iterar e imprimir pares clave-valor de unordered_map, siendo\n"
                 "explícito con sus tipos:\n";
    for (const std::pair<const std::string, std::string>& n : u)
        print_key_value(n.first, n.second);
    std::cout << "\nIterar e imprimir pares clave-valor usando enlace estructurado de C++17:\n";
    for (const auto& [key, value] : u)
        print_key_value(key, value);
    // Agregar dos nuevas entradas al unordered_map
    u["BLACK"] = "#000000";
    u["WHITE"] = "#FFFFFF";
    std::cout << "\nMostrar valores por clave:\n"
                 "El HEX del color ROJO es:[" << u["RED"] << "]\n"
                 "El HEX del color NEGRO es:[" << u["BLACK"] << "]\n\n";
    std::cout << "Usar operator[] con clave inexistente para insertar un nuevo par clave-valor:\n";
    print_key_value("new_key", u["new_key"]);
    std::cout << "\nIterar e imprimir pares clave-valor, usando `auto`;\n"
                 "new_key es ahora una de las claves en el mapa:\n";
    for (const auto& n : u)
        print_key_value(n.first, n.second);
}

Salida posible:

Iterar e imprimir pares clave-valor de unordered_map, siendo
explícito con sus tipos:
Clave:[BLUE] Valor:[#0000FF]
Clave:[GREEN] Valor:[#00FF00]
Clave:[RED] Valor:[#FF0000]
Iterar e imprimir pares clave-valor usando enlace estructurado de C++17:
Clave:[BLUE] Valor:[#0000FF]
Clave:[GREEN] Valor:[#00FF00]
Clave:[RED] Valor:[#FF0000]
Mostrar valores por clave:
El HEX del color ROJO es:[#FF0000]
El HEX del color NEGRO es:[#000000]
Usar operator[] con clave inexistente para insertar un nuevo par clave-valor:
Clave:[new_key] Valor:[]
Iterar e imprimir pares clave-valor, usando `auto`;
new_key es ahora una de las claves en el mapa:
Clave:[new_key] Valor:[]
Clave:[WHITE] Valor:[#FFFFFF]
Clave:[BLACK] Valor:[#000000]
Clave:[BLUE] Valor:[#0000FF]
Clave:[GREEN] Valor:[#00FF00]
Clave:[RED] Valor:[#FF0000]

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares de C++ publicados anteriormente.

DR	Aplicado a	Comportamiento publicado	Comportamiento correcto
LWG 2050	C++11	las definiciones de `reference` , `const_reference` , `pointer` y `const_pointer` se basaban en `allocator_type`	basadas en `value_type` y std::allocator_traits

Véase también

unordered_multimap (C++11)	colección de pares clave-valor, dispersados por claves (plantilla de clase)
map	colección de pares clave-valor, ordenados por claves, claves únicas (plantilla de clase)
flat_map (C++23)	adapta dos contenedores para proporcionar una colección de pares clave-valor, ordenados por claves únicas (plantilla de clase)

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

node-handle (C++17)
Sequence
array (C++11)
vector
vector <bool>
inplace_vector (C++26)
hive (C++26)
deque
forward_list (C++11)
list
Associative
set
multiset
map
multimap
Unordered associative
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
Adaptors
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
Views
span (C++20)
mdspan (C++23)
Tables
Iterator invalidation
Member function table
Non-member function table

es.cppreference.net

Namespaces

Variants

std:: unordered_map

Contenido

Invalidación de iteradores

Notas

Parámetros de plantilla

Tipos miembro

Funciones miembro

Iteradores

Capacidad

Modificadores

Búsqueda

Interfaz de Bucket

Política de hash

Observadores

Funciones no miembro

Guías de deducción

Notas

Ejemplo

Informes de defectos

Véase también