[#bsl-multimap-0ae]
= xref:bsl.adoc[bsl]::multimap
:relfileprefix: ../
:mrdocs:

This class template implements a value‐semantic container type holding an ordered sequence of key‐value pairs having possibly duplicate keys that provide a mapping from keys (of the template parameter type, `KEY`) to their associated values (of another template parameter type, `VALUE`).

== Synopsis

Declared in `<bslstl_multimap.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class KEY,
    class VALUE,
    class COMPARATOR = std::less<KEY>,
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[allocator<pair<KEY const, VALUE>>]>
class multimap;
----

== Description

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

* except for BDEX serialization * is _exception‐neutral_ * is _alias‐safe_ * is `const` _thread‐safe_ For terminology see {`bsldoc_glossary`}.

== Types

[cols="1,4"]
|===
| Name| Description
| xref:bsl/multimap-0ae/value_compare.adoc[`value_compare`] 
| This nested class defines a mechanism for comparing two objects of `value_type` by adapting an object of (template parameter) type `COMPARATOR`, which compares two objects of (template parameter) type `KEY` . Note that this class exactly matches its definition in the C++11 standard [23.4.4.1]; otherwise, we would have implemented it as a separate component‐local class.
|===


== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/multimap-0ae/allocator_type.adoc[`allocator_type`] 
| Allocator type for this container.
| xref:bsl/multimap-0ae/const_iterator.adoc[`const_iterator`] 
| Constant bidirectional iterator over `multimap` elements.
| xref:bsl/multimap-0ae/const_pointer.adoc[`const_pointer`] 
| Constant pointer type for elements in this container.
| xref:bsl/multimap-0ae/const_reference.adoc[`const_reference`] 
| Constant reference type for elements.
| xref:bsl/multimap-0ae/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| Const reverse iterator type for traversing the multimap in reverse order.
| xref:bsl/multimap-0ae/difference_type.adoc[`difference_type`] 
| Signed integer type measuring iterator distance.
| xref:bsl/multimap-0ae/iterator.adoc[`iterator`] 
| Bidirectional iterator over `multimap` elements.
| xref:bsl/multimap-0ae/key_compare.adoc[`key_compare`] 
| Comparator type for ordering keys.
| xref:bsl/multimap-0ae/key_type.adoc[`key_type`] 
| Key type for this multimap.
| xref:bsl/multimap-0ae/mapped_type.adoc[`mapped_type`] 
| Mapped value type for this multimap.
| xref:bsl/multimap-0ae/pointer.adoc[`pointer`] 
| Pointer type for elements in this container.
| xref:bsl/multimap-0ae/reference.adoc[`reference`] 
| Modifiable reference type for elements.
| xref:bsl/multimap-0ae/reverse_iterator.adoc[`reverse_iterator`] 
| Reverse iterator type for traversing the multimap in reverse order.
| xref:bsl/multimap-0ae/size_type.adoc[`size_type`] 
| Unsigned integer type measuring multimap size.
| xref:bsl/multimap-0ae/value_type.adoc[`value_type`] 
| Element type stored in this multimap.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/multimap-0ae/2constructor-005.adoc[`multimap`]         [.small]#[constructor]#
| Constructors
| xref:bsl/multimap-0ae/2destructor.adoc[`~multimap`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/multimap-0ae/operator_assign-07.adoc[`operator=`] 
| Assignment operators
| xref:bsl/multimap-0ae/begin-04a.adoc[`begin`] 
| `begin` overloads
| xref:bsl/multimap-0ae/cbegin.adoc[`cbegin`] 
| Return an iterator providing non‐modifiable access to the first `value_type` object in the ordered sequence of `value_type` objects maintained by this multimap, or the `cend` iterator if this multimap is empty.
| xref:bsl/multimap-0ae/cend.adoc[`cend`] 
| Return an iterator providing non‐modifiable access to the past‐the‐end element in the ordered sequence of `value_type` objects maintained by this multimap.
| xref:bsl/multimap-0ae/clear.adoc[`clear`] 
| Remove all entries from this multimap. Note that the multimap is empty after this call, but allocated memory may be retained for future use.
| xref:bsl/multimap-0ae/contains-05.adoc[`contains`] 
| Return `true` if this multimap contains an element whose key is equivalent to the specified `key`.
| xref:bsl/multimap-0ae/count-07.adoc[`count`] 
| Return the number of `value_type` objects within this multimap whose keys are equivalent to the specified `key`.
| xref:bsl/multimap-0ae/crbegin.adoc[`crbegin`] 
| Return a reverse iterator providing non‐modifiable access to the last `value_type` object in the ordered sequence of `value_type` objects maintained by this multimap, or `rend` if this multimap is empty.
| xref:bsl/multimap-0ae/crend.adoc[`crend`] 
| Return a reverse iterator providing non‐modifiable access to the prior‐to‐the‐beginning element in the ordered sequence of `value_type` objects maintained by this multimap.
| xref:bsl/multimap-0ae/emplace.adoc[`emplace`] 
| Insert into this 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 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/multimap-0ae/emplace_hint.adoc[`emplace_hint`] 
| Insert into this 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 amortized constant time if the specified `hint` is a valid immediate successor to the `value_type` object constructed from `args`). Return an iterator referring to the newly created and inserted object in this multimap. If `hint` is not a valid immediate successor to the `value_type` object implied by `args`, this operation has `O[log(N)]` complexity where `N` is the size of this 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/multimap-0ae/empty.adoc[`empty`] 
| Return `true` if this multimap contains no elements, and `false` otherwise.
| xref:bsl/multimap-0ae/end-07.adoc[`end`] 
| `end` overloads
| xref:bsl/multimap-0ae/equal_range-00.adoc[`equal_range`] 
| `equal_range` overloads
| xref:bsl/multimap-0ae/erase-039.adoc[`erase`] 
| `erase` overloads
| xref:bsl/multimap-0ae/find-0c.adoc[`find`] 
| `find` overloads
| xref:bsl/multimap-0ae/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this multimap.
| xref:bsl/multimap-0ae/insert-09.adoc[`insert`] 
| `insert` overloads
| xref:bsl/multimap-0ae/insert_range.adoc[`insert_range`] 
| Insert into this multimap the value of each `value_type` object in the specified `range`. The (template parameter) type `RANGE` must meet the requirements of 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 multimap, where `i` is a dereferenceable iterator obtained from `range` (see {Requirements on `KEY` and `VALUE`}). The behavior is undefined if `range` overlaps this multimap.
| xref:bsl/multimap-0ae/key_comp.adoc[`key_comp`] 
| Return the key‐comparison functor (or function pointer) used by this multimap; if a comparator was supplied at construction, return its value, otherwise return a default constructed `key_compare` object. Note that this comparator compares objects of type `KEY`, which is the key part of the `value_type` objects contained in this multimap.
| xref:bsl/multimap-0ae/lower_bound-079.adoc[`lower_bound`] 
| `lower_bound` overloads
| xref:bsl/multimap-0ae/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on the largest number of elements that this multimap could possibly hold. Note that there is no guarantee that the multimap can successfully grow to the returned size, or even close to that size without running out of resources.
| xref:bsl/multimap-0ae/rbegin-02.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/multimap-0ae/rend-06.adoc[`rend`] 
| `rend` overloads
| xref:bsl/multimap-0ae/size.adoc[`size`] 
| Return the number of elements in this multimap.
| xref:bsl/multimap-0ae/swap.adoc[`swap`] 
| Exchange the value and comparator 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 the (template parameter) type `COMPARATOR` provides a no‐throw swap operation, and provides the basic exception‐safety guarantee otherwise; if an exception is thrown, both objects are left in valid but unspecified states. This operation has `O[1]` complexity if either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the number of elements in this object and `other`, respectively. Note that this method's support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
| xref:bsl/multimap-0ae/upper_bound-00.adoc[`upper_bound`] 
| `upper_bound` overloads
| xref:bsl/multimap-0ae/value_comp.adoc[`value_comp`] 
| Return a functor for comparing two `value_type` objects by comparing their respective keys using `key_comp()`. Note that this comparator compares objects of type `value_type` (i.e., 'pair<const KEY, VALUE>').
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/multimap-07.adoc[`multimap<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/multimap-0d.adoc[`multimap<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `multimap`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/multimap-0e.adoc[`multimap<KEY, VALUE, COMPARATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `multimap`. Deduce the template parameter `COMPARATOR` from the other parameters passed to the constructor. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/multimap-01.adoc[`multimap<KEY, VALUE, COMPARATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `multimap`. Deduce the template parameter `COMPARATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/multimap-0a3.adoc[`multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `multimap`. Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the other parameters passed to the constructor. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/multimap-0f.adoc[`multimap<KEY, VALUE, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `multimap`. Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the other parameters passed to the constructor. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/multimap-09.adoc[`multimap<KEY, VALUE, std::less<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `multimap`. Deduce the template parameter `ALLOCATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
| xref:bsl/multimap-00.adoc[`multimap<KEY, VALUE, std::less<KEY>, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `multimap`. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase_if-0f.adoc[`erase_if`]
| Erase all the elements in the specified multimap `m` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_3way-081.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of the specified `lhs` and the specified `rhs` maps by using the comparison operators of `bsl::pair<const KEY, VALUE>` on each element; return the result of that comparison.
| xref:bsl/operator_eq-03.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `multimap` objects `lhs` and `rhs` have the same value if they have the same number of key‐value pairs, and each element in the ordered sequence of key‐value pairs of `lhs` has the same value as the corresponding element in the ordered sequence of key‐value pairs of `rhs`. This method requires that the (template parameter) types `KEY` and `VALUE` both be `equality‐comparable` (see {Requirements on `KEY` and `VALUE`}).
| xref:bsl/swap-073.adoc[`swap`]
| Exchange the value and comparator 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 the (template parameter) type `COMPARATOR` provides a no‐throw swap operation, and provides the basic exception‐safety guarantee otherwise; if an exception is thrown, both objects are left in valid but unspecified states. This operation has `O[1]` complexity if either `a` was created with the same allocator as `b` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the number of elements in `a` and `b`, respectively. Note that this function's support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
|===


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