[#bsl-unordered_multimap-0b0]
= xref:bsl.adoc[bsl]::unordered_multimap
:relfileprefix: ../
:mrdocs:

This class template implements a value‐semantic container type holding a collection of (possibly equivalent) keys (of the template parameter type `KEY`), each mapped to their associated values (of another template parameter type `VALUE`).

== Synopsis

Declared in `<bslstl_unorderedmultimap.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class KEY,
    class VALUE,
    class HASH = xref:bsl/hash-06.adoc[bsl::hash<KEY>],
    class EQUAL = xref:bsl/equal_to-0d.adoc[bsl::equal_to<KEY>],
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[bsl::allocator<bsl::pair<KEY const, VALUE>>]>
class unordered_multimap;
----

== Description

This class: * supports a complete set of _value‐semantic_ operations

* except for BDEX serialization * 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_multimap-0b0/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias for `allocator_type`.
| xref:bsl/unordered_multimap-0b0/const_iterator.adoc[`const_iterator`] 
| This `typedef` is an alias for `const_iterator`.
| xref:bsl/unordered_multimap-0b0/const_local_iterator.adoc[`const_local_iterator`] 
| This `typedef` is an alias for `const_local_iterator`.
| xref:bsl/unordered_multimap-0b0/const_pointer.adoc[`const_pointer`] 
| This `typedef` is an alias to `AllocatorTraits::const_pointer`.
| xref:bsl/unordered_multimap-0b0/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias for `const_reference`.
| xref:bsl/unordered_multimap-0b0/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias for `difference_type`.
| xref:bsl/unordered_multimap-0b0/hasher.adoc[`hasher`] 
| This `typedef` is an alias to the (template parameter) `HASH`.
| xref:bsl/unordered_multimap-0b0/iterator.adoc[`iterator`] 
| This `typedef` is an alias for `iterator`.
| xref:bsl/unordered_multimap-0b0/key_equal.adoc[`key_equal`] 
| This `typedef` is an alias for `key_equal`.
| xref:bsl/unordered_multimap-0b0/key_type.adoc[`key_type`] 
| This `typedef` is an alias for `key_type`.
| xref:bsl/unordered_multimap-0b0/local_iterator.adoc[`local_iterator`] 
| This `typedef` is an alias for `local_iterator`.
| xref:bsl/unordered_multimap-0b0/mapped_type.adoc[`mapped_type`] 
| This `typedef` is an alias for `mapped_type`.
| xref:bsl/unordered_multimap-0b0/pointer.adoc[`pointer`] 
| This `typedef` is an alias for `pointer`.
| xref:bsl/unordered_multimap-0b0/reference.adoc[`reference`] 
| This `typedef` is an alias to `value_type&`.
| xref:bsl/unordered_multimap-0b0/size_type.adoc[`size_type`] 
| This `typedef` is an alias for `size_type`.
| xref:bsl/unordered_multimap-0b0/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_multimap-0b0/2constructor-06.adoc[`unordered_multimap`]         [.small]#[constructor]#
| Constructors
| xref:bsl/unordered_multimap-0b0/2destructor.adoc[`~unordered_multimap`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/unordered_multimap-0b0/operator_assign-0b.adoc[`operator=`] 
| Assignment operators
| xref:bsl/unordered_multimap-0b0/begin-096.adoc[`begin`] 
| `begin` overloads
| xref:bsl/unordered_multimap-0b0/bucket-00d.adoc[`bucket`] 
| `bucket` overloads
| xref:bsl/unordered_multimap-0b0/bucket_count.adoc[`bucket_count`] 
| Return the number of buckets in the array of buckets maintained by this unordered multimap.
| xref:bsl/unordered_multimap-0b0/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 container. The behavior is undefined unless `index < bucket_count()`.
| xref:bsl/unordered_multimap-0b0/cbegin-01.adoc[`cbegin`] 
| `cbegin` overloads
| xref:bsl/unordered_multimap-0b0/cend-03.adoc[`cend`] 
| `cend` overloads
| xref:bsl/unordered_multimap-0b0/clear.adoc[`clear`] 
| Remove all entries from this unordered multimap. Note that this object will be empty after this call, but allocated memory may be retained for future use.
| xref:bsl/unordered_multimap-0b0/contains-0e.adoc[`contains`] 
| Return `true` if this unordered map contains an element whose key is equivalent to the specified `key`.
| xref:bsl/unordered_multimap-0b0/count-09.adoc[`count`] 
| `count` overloads
| xref:bsl/unordered_multimap-0b0/emplace.adoc[`emplace`] 
| Insert into this unordered multimap 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`. Return an iterator referring to the newly created and inserted object in this unordered multimap. This method requires that the (template parameter) types `KEY` and `VALUE` both be `emplace‐constructible` from `args` (see {Requirements on `KEY` and `VALUE`}).
| xref:bsl/unordered_multimap-0b0/emplace_hint.adoc[`emplace_hint`] 
| Insert into this unordered multimap 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` (in constant time if the specified `hint` refers to an element in this container with a key equivalent to the key of the newly created `value_type` object), and return an iterator referring to the newly created and inserted object. If `hint` does not refer to an element in this container with a key equivalent to the key of the newly created `value_type` object, this operation has worst case `O[N]` and average case constant‐time complexity, where `N` is the size of this unordered multimap. This method requires that the (template parameter) types `KEY` and `VALUE` both be `emplace‐constructible` from `args` (see {Requirements on `KEY` and `VALUE`}). The behavior is undefined unless `hint` is an iterator in the range `[begin() .. end()]` (both endpoints included).
| xref:bsl/unordered_multimap-0b0/empty.adoc[`empty`] 
| Return `true` if this unordered multimap contains no elements, and `false` otherwise.
| xref:bsl/unordered_multimap-0b0/end-0d.adoc[`end`] 
| `end` overloads
| xref:bsl/unordered_multimap-0b0/equal_range-0c.adoc[`equal_range`] 
| `equal_range` overloads
| xref:bsl/unordered_multimap-0b0/erase-0b5.adoc[`erase`] 
| `erase` overloads
| xref:bsl/unordered_multimap-0b0/find-00.adoc[`find`] 
| `find` overloads
| xref:bsl/unordered_multimap-0b0/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this unordered multimap.
| xref:bsl/unordered_multimap-0b0/hash_function.adoc[`hash_function`] 
| Return (a copy of) the hash unary functor used by this unordered multimap to generate a hash value (of type `size_type`) for a `key_type` object.
| xref:bsl/unordered_multimap-0b0/insert-0a.adoc[`insert`] 
| `insert` overloads
| xref:bsl/unordered_multimap-0b0/insert_range.adoc[`insert_range`] 
| Insert into this unordered multimap the value of each `value_type` object in the specified `range`. Note that `RANGE` must meet the requirements of an input range and the values from `range` must have a type matching or convertible to `value_type`.
| xref:bsl/unordered_multimap-0b0/key_eq.adoc[`key_eq`] 
| Return (a copy of) the key‐equivalence binary functor that returns `true` if the value of two `key_type` objects are equivalent, and `false` otherwise.
| xref:bsl/unordered_multimap-0b0/load_factor.adoc[`load_factor`] 
| Return the current ratio between the `size` of this container 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_multimap-0b0/max_bucket_count.adoc[`max_bucket_count`] 
| Return a theoretical upper bound on the largest number of buckets that this container could possibly manage. Note that there is no guarantee that the unordered multimap can successfully grow to the returned size, or even close to that size without running out of resources.
| xref:bsl/unordered_multimap-0b0/max_load_factor-0f.adoc[`max_load_factor`] 
| `max_load_factor` overloads
| xref:bsl/unordered_multimap-0b0/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on the largest number of elements that this unordered multimap could possibly hold. Note that there is no guarantee that the unordered multimap can successfully grow to the returned size, or even close to that size without running out of resources.
| xref:bsl/unordered_multimap-0b0/rehash.adoc[`rehash`] 
| Change the size of the array of buckets maintained by this container to the specified `numBuckets`, and redistribute all the contained elements into the new sequence of buckets, according to their hash values. Note that this operation has no effect if rehashing the elements into `numBuckets` would cause this unordered multimap to exceed its `max_load_factor`.
| xref:bsl/unordered_multimap-0b0/reserve.adoc[`reserve`] 
| Increase the number of buckets of this unordered multimap to a quantity such that the ratio between the specified `numElements` and the new number of buckets 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_multimap-0b0/size.adoc[`size`] 
| Return the number of elements in this unordered multimap.
| xref:bsl/unordered_multimap-0b0/swap.adoc[`swap`] 
| Exchange the contents of this object with those of `other`.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/unordered_multimap-0d8.adoc[`unordered_multimap<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-02.adoc[`unordered_multimap<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-048a.adoc[`unordered_multimap<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-07.adoc[`unordered_multimap<KEY, VALUE>`] 
| of the iterators supplied to the constructor of `unordered_multimap`. Deduce the template parameter `ALLOCATOR` from the other parameter passed to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-044.adoc[`unordered_multimap<KEY, VALUE, HASH>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. Deduce the template parameter `HASH` from the other parameters supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-08f.adoc[`unordered_multimap<KEY, VALUE, HASH>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. Deduce the template parameter `HASH` from the other parameters passed to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-00.adoc[`unordered_multimap<KEY, VALUE, HASH, EQUAL>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. Deduce the template parameters `HASH`, `EQUAL` and `ALLOCATOR` from the other parameters supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-06.adoc[`unordered_multimap<KEY, VALUE, HASH, EQUAL>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. Deduce the template parameters `HASH` and "EQUAL' from the other parameters passed to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/unordered_multimap-0e.adoc[`unordered_multimap<KEY, VALUE, HASH, EQUAL, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. Deduce the template parameters `HASH`, `EQUAL` and `ALLOCATOR` from the other parameters supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless: (1) the supplied `HASH` is invokable with a `KEY`, (2) the supplied `EQUAL` is invokable with two `KEY`s, and (3) the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-0d6.adoc[`unordered_multimap<KEY, VALUE, HASH, EQUAL, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. Deduce the template parameters `HASH`, `EQUAL` and `ALLOCATOR` from the other parameters passed to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-048e.adoc[`unordered_multimap<KEY, VALUE, HASH, bsl::equal_to<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. Deduce the template parameters `HASH` and `ALLOCATOR` from the other parameters supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied `HASH` is invokable with a `KEY`, and the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-084.adoc[`unordered_multimap<KEY, VALUE, HASH, bsl::equal_to<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. Deduce the template parameters `HASH` and `ALLOCATOR` from the other parameters passed to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied hash is invokable with a `KEY`, and the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-04c.adoc[`unordered_multimap<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. Deduce the template parameter `ALLOCATOR` from the other parameters supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-0b8.adoc[`unordered_multimap<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-0b6.adoc[`unordered_multimap<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. Deduce the template parameter `ALLOCATOR` from the other parameter passed to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/unordered_multimap-04e.adoc[`unordered_multimap<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `unordered_multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/operator_eq-068.adoc[bsl::operator==]`
| Same as the related overload above for `operator==`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase_if-0aa.adoc[`erase_if`]
| Erase all the elements in the specified unordered_multimap `m` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_eq-08a.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `unordered_multimap` objects have the same value if they have the same number of key‐value pairs, and each key‐value pair that is contained in one of the objects is also contained in the other object. This method requires that the (template parameter) types `KEY` and `VALUE` both be `equality‐comparable` (see {Requirements on `KEY` and `VALUE`}).
| xref:bsl/swap-08c.adoc[`swap`]
| Exchange the value, hasher, key‐equality functor, and `max_load_factor` of the specified `a` object with those of the specified `b` object; also exchange the allocator of `a` with that of `b` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This function 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 `a` was created with the same allocator as `b` or `ALLOCATOR` has the `propagate_on_container_swap` trait.
|===


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