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)
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)

Contenidos

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 de miembros

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 iterador cuya categoría, valor, diferencia, puntero y
tipos de referencia son los mismos que iterator . Este iterador
puede usarse para iterar a través de un solo cubo pero no entre cubos
const_local_iterator Un tipo iterador cuya categoría, valor, diferencia, puntero y
tipos de referencia son los mismos que const_iterator . Este iterador
puede usarse para iterar a través de un solo 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 /*no especificado*/
{
Iter     posición ;
bool insertado ;
NodeType nodo ;
} ;
instanciado con argumentos de plantilla iterator y node_type .

Funciones miembro

construye el unordered_map
(función miembro pública)
destruye el unordered_map
(función miembro pública)
asigna valores al contenedor
(función miembro pública)
devuelve el asignador asociado
(función miembro pública)
Iteradores
devuelve un iterador al inicio
(función miembro pública)
devuelve un iterador al final
(función miembro pública)
Capacidad
comprueba si el contenedor está vacío
(función miembro pública)
devuelve el número de elementos
(función miembro pública)
devuelve el número máximo posible de elementos
(función miembro pública)
Modificadores
borra el contenido
(función miembro pública)
inserta elementos o nodos (desde C++17)
(función miembro pública)
(C++23)
inserta un rango de elementos
(función miembro pública)
(C++17)
inserta un elemento o asigna al elemento actual si la clave ya existe
(función miembro pública)
construye el elemento in situ
(función miembro pública)
construye elementos in-situ usando una pista
(función miembro pública)
(C++17)
inserta in-situ si la clave no existe, no hace nada si la clave existe
(función miembro pública)
elimina elementos
(función miembro pública)
intercambia los contenidos
(función miembro pública)
(C++17)
extrae nodos del contenedor
(función miembro pública)
(C++17)
empalma nodos desde otro contenedor
(función miembro pública)
Búsqueda
acceder al elemento especificado con verificación de límites
(función miembro pública)
acceder o insertar elemento especificado
(función miembro pública)
devuelve el número de elementos que coinciden con una clave específica
(función miembro pública)
encuentra elemento con clave específica
(función miembro pública)
(C++20)
verifica si el contenedor contiene un elemento con clave específica
(función miembro pública)
devuelve el rango de elementos que coinciden con una clave específica
(función miembro pública)
Interfaz de Bucket
devuelve un iterador al inicio del bucket especificado
(función miembro pública)
devuelve un iterador al final del bucket especificado
(función miembro pública)
devuelve el número de cubos
(función miembro pública)
devuelve el número máximo de buckets
(función miembro pública)
devuelve el número de elementos en un bucket específico
(función miembro pública)
devuelve el bucket para una clave específica
(función miembro pública)
Política de hash
devuelve el número promedio de elementos por bucket
(función miembro pública)
gestiona el número máximo promedio de elementos por bucket
(función miembro pública)
reserva al menos el número especificado de cubos y regenera la tabla hash
(función miembro pública)
reserva espacio para al menos el número especificado de elementos y regenera la tabla hash
(función miembro pública)
Observadores
devuelve la función utilizada para hashear las claves
(función miembro pública)
devuelve la función utilizada para comparar claves por igualdad
(función miembro pública)

Funciones no miembro

(C++11) (C++11) (removed in C++20)
compara los valores en el unordered_map
(plantilla de función)
(C++11)
especializa el algoritmo std::swap
(plantilla de función)
(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

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