[#bsl-unordered_map-0bf]
= xref:bsl.adoc[bsl]::xref:bsl/unordered_map-02b.adoc[unordered_map]<xref:bsl/basic_string-0faf.adoc[basic_string<char>], xref:BloombergLP/bdljsn/Json.adoc[Json], xref:BloombergLP/bdlb/TransparentHash.adoc[TransparentHash], xref:BloombergLP/bdlb/TransparentEqualTo.adoc[TransparentEqualTo]>
:relfileprefix: ../
:mrdocs:

This class template implements a value‐semantic container type holding an unordered set of `KEY‐VALUE` pairs having unique keys that provide a mapping from keys (of template parameter type `KEY`) to their associated mapped values (of template parameter type `VALUE`).

== Synopsis

Declared in `<bslstl_unorderedmap.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<>
class xref:bsl/unordered_map-02b.adoc[unordered_map]<xref:bsl/basic_string-0faf.adoc[basic_string<char>], xref:BloombergLP/bdljsn/Json.adoc[Json], xref:BloombergLP/bdlb/TransparentHash.adoc[TransparentHash], xref:BloombergLP/bdlb/TransparentEqualTo.adoc[TransparentEqualTo]>;
----

== Description

This class: * supports a complete set of _value‐semantic_ operations * is _exception‐neutral_ (agnostic except for the `at` method) * is _alias‐safe_ * is `const` _thread‐safe_ For terminology see {`bsldoc_glossary`}.

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/unordered_map-0bf/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias to the (template parameter) `ALLOCATOR`.
| xref:bsl/unordered_map-0bf/const_iterator.adoc[`const_iterator`] 
| This `typedef` is an alias to `HashTableIterator<const value_type>`.
| xref:bsl/unordered_map-0bf/const_local_iterator.adoc[`const_local_iterator`] 
| This `typedef` is an alias to `HashTableBucketIterator<const value_type>`.
| xref:bsl/unordered_map-0bf/const_pointer.adoc[`const_pointer`] 
| This `typedef` is an alias to `AllocatorTraits::const_pointer`.
| xref:bsl/unordered_map-0bf/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias to `const value_type&`.
| xref:bsl/unordered_map-0bf/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to `AllocatorTraits::difference_type`.
| xref:bsl/unordered_map-0bf/hasher.adoc[`hasher`] 
| This `typedef` is an alias to the (template parameter) `HASH`.
| xref:bsl/unordered_map-0bf/iterator.adoc[`iterator`] 
| This `typedef` is an alias to `HashTableIterator<value_type>`.
| xref:bsl/unordered_map-0bf/key_equal.adoc[`key_equal`] 
| This `typedef` is an alias to the (template parameter) `EQUAL`.
| xref:bsl/unordered_map-0bf/key_type.adoc[`key_type`] 
| This `typedef` is an alias to the (template parameter) `KEY`.
| xref:bsl/unordered_map-0bf/local_iterator.adoc[`local_iterator`] 
| This `typedef` is an alias to `HashTableBucketIterator<value_type>`.
| xref:bsl/unordered_map-0bf/mapped_type.adoc[`mapped_type`] 
| This `typedef` is an alias to the (template parameter) `VALUE`.
| xref:bsl/unordered_map-0bf/pointer.adoc[`pointer`] 
| This `typedef` is an alias to `AllocatorTraits::pointer`.
| xref:bsl/unordered_map-0bf/reference.adoc[`reference`] 
| This `typedef` is an alias to `value_type&`.
| xref:bsl/unordered_map-0bf/size_type.adoc[`size_type`] 
| This `typedef` is an alias to `AllocatorTraits::size_type`.
| xref:bsl/unordered_map-0bf/value_type.adoc[`value_type`] 
| This `typedef` is an alias to `bsl::pair<const KEY, VALUE>`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/unordered_map-0bf/2constructor-0b0.adoc[`unordered_map`]         [.small]#[constructor]#
| Constructors
| xref:bsl/unordered_map-0bf/2destructor.adoc[`~unordered_map`] [.small]#[destructor]#
| Destroy this object and each of its elements.
| xref:bsl/unordered_map-0bf/operator_assign-0b.adoc[`operator=`] 
| Assignment operators
| xref:bsl/unordered_map-0bf/at-06.adoc[`at`] 
| `at` overloads
| xref:bsl/unordered_map-0bf/begin-0ff.adoc[`begin`] 
| `begin` overloads
| xref:bsl/unordered_map-0bf/bucket-04.adoc[`bucket`] 
| `bucket` overloads
| xref:bsl/unordered_map-0bf/bucket_count.adoc[`bucket_count`] 
| Return the number of buckets in the array of buckets maintained by this unordered map.
| xref:bsl/unordered_map-0bf/bucket_size.adoc[`bucket_size`] 
| Return the number of elements contained in the bucket at the specified `index` in the array of buckets maintained by this unordered map. The behavior is undefined unless `index < bucket_count()`.
| xref:bsl/unordered_map-0bf/cbegin-0f.adoc[`cbegin`] 
| `cbegin` overloads
| xref:bsl/unordered_map-0bf/cend-07.adoc[`cend`] 
| `cend` overloads
| xref:bsl/unordered_map-0bf/clear.adoc[`clear`] 
| Remove all entries from this unordered map. Note that this unordered map will be empty after calling this method, but allocated memory may be retained for future use.
| xref:bsl/unordered_map-0bf/contains-0d.adoc[`contains`] 
| Return `true` if this unordered map contains an element whose key is equivalent to the specified `key`.
| xref:bsl/unordered_map-0bf/count-03.adoc[`count`] 
| `count` overloads
| xref:bsl/unordered_map-0bf/emplace.adoc[`emplace`] 
| Insert into this unordered map a newly‐created `value_type` object, constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `args` to the corresponding constructor of `value_type`, if a key equivalent to such a value does not already exist in this map; otherwise, this method has no effect (other than possibly creating a temporary `value_type` object). Return a pair whose `first` member is an iterator referring to the (possibly newly created and inserted) object in this map whose key is equivalent to that of an object constructed from `args`, and whose `second` member is `true` if a new value was inserted, and `false` if an equivalent key was already present. This method requires that the (template parameter) types `KEY` and `VALUE` both be `emplace‐constructible` from `args` (see {Requirements on `value_type`}).
| xref:bsl/unordered_map-0bf/emplace_hint.adoc[`emplace_hint`] 
| Insert into this unordered map a newly‐created `value_type` object, constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `args` to the corresponding constructor of `value_type`, if a key equivalent to such a value does not already exist in this map; otherwise, this method has no effect (other than possibly creating a temporary `value_type` object). Return an iterator referring to the (possibly newly created and inserted) object in this map whose key is equivalent to that of an object constructed from `args`. The average and worst case complexity of this operation is not affected by the specified `hint`. This method requires that the (template parameter) types `KEY` and `VALUE` both be `emplace‐constructible` from `args` (see {Requirements on `value_type`}). The behavior is undefined unless `hint` is an iterator in the range `[begin() .. end()]` (both endpoints included). Note that `hint` is ignored (other than possibly asserting its validity in some build modes).
| xref:bsl/unordered_map-0bf/empty.adoc[`empty`] 
| Return `true` if this unordered map contains no elements, and `false` otherwise.
| xref:bsl/unordered_map-0bf/end-06.adoc[`end`] 
| `end` overloads
| xref:bsl/unordered_map-0bf/equal_range-06.adoc[`equal_range`] 
| `equal_range` overloads
| xref:bsl/unordered_map-0bf/erase-06.adoc[`erase`] 
| `erase` overloads
| xref:bsl/unordered_map-0bf/find-07.adoc[`find`] 
| `find` overloads
| xref:bsl/unordered_map-0bf/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this unordered map.
| xref:bsl/unordered_map-0bf/hash_function.adoc[`hash_function`] 
| Return (a copy of) the unary hash functor used by this unordered map to generate a hash value (of type `size_type`) for a `key_type` object.
| xref:bsl/unordered_map-0bf/insert-0a.adoc[`insert`] 
| `insert` overloads
| xref:bsl/unordered_map-0bf/insert_or_assign-01.adoc[`insert_or_assign`] 
| `insert_or_assign` overloads
| xref:bsl/unordered_map-0bf/insert_range.adoc[`insert_range`] 
| Insert into this map the value of each `value_type` object in the specified `range` if a key equivalent to the object is not already contained in this set. The (template parameter) type `RANGE` must meet the requirements the C++20 standard [ranges]providing access to values of a type convertible to `value_type`, and `value_type` must be `emplace‐constructible` from `*i` into this set, where `i` is a dereferenceable iterator obtained from `range` (see {Requirements on `KEY`}). The behavior is undefined if `range` overlaps this map.
| xref:bsl/unordered_map-0bf/key_eq.adoc[`key_eq`] 
| Return (a copy of) binary the key‐equality functor used by this unordered map that returns `true` if two `key_type` objects are equivalent, and `false` otherwise.
| xref:bsl/unordered_map-0bf/load_factor.adoc[`load_factor`] 
| Return the current ratio between the `size` of this unordered map and the number of buckets. The load factor is a measure of how full the container is, and a higher load factor typically leads to an increased number of collisions, thus resulting in a loss of performance.
| xref:bsl/unordered_map-0bf/max_bucket_count.adoc[`max_bucket_count`] 
| Return a theoretical upper bound on the largest number of buckets that this unordered map could possibly manage. Note that there is no guarantee that the unordered map can successfully grow to the returned size, or even close to that size, without running out of resources.
| xref:bsl/unordered_map-0bf/max_load_factor-099a1.adoc[`max_load_factor`] 
| `max_load_factor` overloads
| xref:bsl/unordered_map-0bf/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on the largest number of elements that this unordered map could possibly hold. Note that there is no guarantee that the unordered map can successfully grow to the returned size, or even close to that size, without running out of resources.
| xref:bsl/unordered_map-0bf/operator_subs-0a.adoc[`operator[]`] 
| Subscript operators
| xref:bsl/unordered_map-0bf/rehash.adoc[`rehash`] 
| Change the size of the array of buckets maintained by this unordered map to at least the specified `numBuckets`, and redistribute all the contained elements into the new sequence of buckets, according to their hash values. After this call, `load_factor` will be less than or equal to `max_load_factor`. This operation has no effect if rehashing the elements into `numBuckets` would cause this map to exceed its `max_load_factor`.
| xref:bsl/unordered_map-0bf/reserve.adoc[`reserve`] 
| Increase the number of buckets of this set to a quantity such that the ratio between the specified `numElements` and this quantity does not exceed `max_load_factor`. Note that this guarantees that, after the reserve, elements can be inserted to grow the container to `size() == numElements` without rehashing. Also note that memory allocations may still occur when growing the container to `size() == numElements`. Also note that this operation has no effect if `numElements <= size()`.
| xref:bsl/unordered_map-0bf/size.adoc[`size`] 
| Return the number of elements in this unordered map.
| xref:bsl/unordered_map-0bf/swap.adoc[`swap`] 
| Exchange the value, hasher, key‐equality functor, and `max_load_factor` of this object with those of the specified `other` object; also exchange the allocator of this object with that of `other` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This method provides the no‐throw exception‐safety guarantee if and only if both the (template parameter) types `HASH` and `EQUAL` provide no‐throw swap operations; if an exception is thrown, both objects are left in valid but unspecified states. This operation guarantees `O[1]` complexity. The behavior is undefined unless either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate_on_container_swap` trait.
| xref:bsl/unordered_map-0bf/try_emplace-092.adoc[`try_emplace`] 
| `try_emplace` overloads
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/operator_eq-024.adoc[bsl::operator==]`
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `unordered_map` objects have the same value if they have the same number of key‐value pairs, and for each key‐value pair that is contained in `lhs` there is a key‐value pair contained in `rhs` having the same value, and vice versa. Note that this method requires that the (template parameter) types `KEY` and `VALUE` both be `equality‐comparable` (see {Requirements on `value_type`}).
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#