class template
<unordered_map>

std::unordered_map

template < class Key,                                    // unordered_map::key_type
           class T,                                      // unordered_map::mapped_type
           class Hash = hash<Key>,                       // unordered_map::hasher
           class Pred = equal_to<Key>,                   // unordered_map::key_equal
           class Alloc = allocator< pair<const Key,T> >  // unordered_map::allocator_type
           > class unordered_map;
Unordered Map
Unordered maps are associative containers that store elements formed by the combination of a key value and a mapped value, and which allows for fast retrieval of individual elements based on their keys.

In an unordered_map, the key value is generally used to uniquely identify the element, while the mapped value is an object with the content associated to this key. Types of key and mapped value may differ.

Internally, the elements in the unordered_map are not sorted in any particular order with respect to either their key or mapped values, but organized into buckets depending on their hash values to allow for fast access to individual elements directly by their key values (with a constant average time complexity on average).

unordered_map containers are faster than map containers to access individual elements by their key, although they are generally less efficient for range iteration through a subset of their elements.

Unordered maps implement the direct access operator (operator[]) which allows for direct access of the mapped value using its key value as argument.

Iterators in the container are at least forward iterators.

Container properties

Associative
Elements in associative containers are referenced by their key and not by their absolute position in the container.
Unordered
Unordered containers organize their elements using hash tables that allow for fast access to elements by their key.
Map
Each element associates a key to a mapped value: Keys are meant to identify the elements whose main content is the mapped value.
Unique keys
No two elements in the container can have equivalent keys.
Allocator-aware
The container uses an allocator object to dynamically handle its storage needs.

Template parameters

Key
Type of the key values. Each element in an unordered_map is uniquely identified by its key value.
Aliased as member type unordered_map::key_type.
T
Type of the mapped value. Each element in an unordered_map is used to store some data as its mapped value.
Aliased as member type unordered_map::mapped_type. Note that this is not the same as unordered_map::value_type (see below).
Hash
A unary function object type that takes an object of type key type as argument and returns a unique value of type size_t based on it. This can either be a class implementing a function call operator or a pointer to a function (see constructor for an example). This defaults to hash<Key>, which returns a hash value with a probability of collision approaching 1.0/std::numeric_limits<size_t>::max().
The unordered_map object uses the hash values returned by this function to organize its elements internally, speeding up the process of locating individual elements.
Aliased as member type unordered_map::hasher.
Pred
A binary predicate that takes two arguments of the key type and returns a bool. The expression pred(a,b), where pred is an object of this type and a and b are key values, shall return true if a is to be considered equivalent to b. This can either be a class implementing a function call operator or a pointer to a function (see constructor for an example). This defaults to equal_to<Key>, which returns the same as applying the equal-to operator (a==b).
The unordered_map object uses this expression to determine whether two element keys are equivalent. No two elements in an unordered_map container can have keys that yield true using this predicate.
Aliased as member type unordered_map::key_equal.
Alloc
Type of the allocator object used to define the storage allocation model. By default, the allocator class template is used, which defines the simplest memory allocation model and is value-independent.
Aliased as member type unordered_map::allocator_type.

In the reference for the unordered_map member functions, these same names (Key, T, Hash, Pred and Alloc) are assumed for the template parameters.

Iterators to elements of unordered_map containers access to both the key and the mapped value. For this, the class defines what is called its value_type, which is a pair class with its first value corresponding to the const version of the key type (template parameter Key) and its second value corresponding to the mapped value (template parameter T):
 
typedef pair<const Key, T> value_type;


Iterators of a unordered_map container point to elements of this value_type. Thus, for an iterator called it that points to an element of a map, its key and mapped value can be accessed respectively with:
1
2
3
4
unordered_map<Key,T>::iterator it;
(*it).first;             // the key value (of type Key)
(*it).second;            // the mapped value (of type T)
(*it);                   // the "element value" (of type pair<const Key,T>) 

Naturally, any other direct access operator, such as -> or [] can be used, for example:
1
2
it->first;               // same as (*it).first   (the key value)
it->second;              // same as (*it).second  (the mapped value) 


Member types

The following aliases are member types of unordered_map. They are widely used as parameter and return types by member functions:

member typedefinitionnotes
key_typethe first template parameter (Key)
mapped_typethe second template parameter (T)
value_typepair<const key_type,mapped_type>
hasherthe third template parameter (Hash)defaults to: hash<key_type>
key_equalthe fourth template parameter (Pred)defaults to: equal_to<key_type>
allocator_typethe fifth template parameter (Alloc)defaults to: allocator<value_type>
referencevalue_type&
const_referenceconst value_type&
pointerallocator_traits<Alloc>::pointerfor the default allocator: value_type*
const_pointerallocator_traits<Alloc>::const_pointerfor the default allocator: const value_type*
iteratora forward iterator to value_type
const_iteratora forward iterator to const value_type
local_iteratora forward iterator to value_type
const_local_iteratora forward iterator to const value_type
size_typean unsigned integral typeusually the same as size_t
difference_typea signed integral typeusually the same as ptrdiff_t

Member functions


Capacity


Iterators


Element access


Element lookup


Modifiers


Buckets


Hash policy


Observers


Non-member function overloads