[#bsl-map-0a7]
= xref:bsl.adoc[bsl]::map
:relfileprefix: ../
:mrdocs:

This class template implements a value‐semantic container type holding an ordered sequence of key‐value pairs having unique 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_map.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 map;
----

== 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/map-0a7/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 [map.overview]; otherwise, we would have implemented it as a separate component‐local class.
|===


== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/map-0a7/allocator_type.adoc[`allocator_type`] 
| Alias for the allocator type `ALLOCATOR`.
| xref:bsl/map-0a7/const_iterator.adoc[`const_iterator`] 
| Constant bidirectional iterator over `map` elements.
| xref:bsl/map-0a7/const_pointer.adoc[`const_pointer`] 
| Alias for the const pointer type supplied by the allocator traits.
| xref:bsl/map-0a7/const_reference.adoc[`const_reference`] 
| Alias for a constant reference to a map element.
| xref:bsl/map-0a7/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| Reverse iterator type for traversing the map in reverse order.
| xref:bsl/map-0a7/difference_type.adoc[`difference_type`] 
| Signed integer type measuring iterator distance.
| xref:bsl/map-0a7/iterator.adoc[`iterator`] 
| Bidirectional iterator over `map` elements.
| xref:bsl/map-0a7/key_compare.adoc[`key_compare`] 
| Alias for the key‐comparison functor type `COMPARATOR`.
| xref:bsl/map-0a7/key_type.adoc[`key_type`] 
| Alias for the key type `KEY`.
| xref:bsl/map-0a7/mapped_type.adoc[`mapped_type`] 
| Alias for the mapped value type `VALUE`.
| xref:bsl/map-0a7/pointer.adoc[`pointer`] 
| Alias for the pointer type supplied by the allocator traits.
| xref:bsl/map-0a7/reference.adoc[`reference`] 
| Alias for a modifiable reference to a map element.
| xref:bsl/map-0a7/reverse_iterator.adoc[`reverse_iterator`] 
| Reverse iterator over `map` elements.
| xref:bsl/map-0a7/size_type.adoc[`size_type`] 
| Alias for the size type supplied by the allocator traits.
| xref:bsl/map-0a7/value_type.adoc[`value_type`] 
| Alias for the map element type `pair<const KEY, VALUE>`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/map-0a7/2constructor-0bc.adoc[`map`]         [.small]#[constructor]#
| Constructors
| xref:bsl/map-0a7/2destructor.adoc[`~map`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/map-0a7/operator_assign-0c.adoc[`operator=`] 
| Assignment operators
| xref:bsl/map-0a7/at-0a.adoc[`at`] 
| `at` overloads
| xref:bsl/map-0a7/begin-0f.adoc[`begin`] 
| `begin` overloads
| xref:bsl/map-0a7/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 map, or the `cend` iterator if this map is empty.
| xref:bsl/map-0a7/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 map.
| xref:bsl/map-0a7/clear.adoc[`clear`] 
| Remove all entries from this map. Note that the map is empty after this call, but allocated memory may be retained for future use.
| xref:bsl/map-0a7/contains-06.adoc[`contains`] 
| Return `true` if this map contains an element whose key is equivalent to the specified `key`.
| xref:bsl/map-0a7/count-05.adoc[`count`] 
| `count` overloads
| xref:bsl/map-0a7/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 map, or `crend` if this map is empty.
| xref:bsl/map-0a7/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 map.
| xref:bsl/map-0a7/emplace.adoc[`emplace`] 
| Insert into this 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 `KEY` and `VALUE`}).
| xref:bsl/map-0a7/emplace_hint.adoc[`emplace_hint`] 
| Insert into this 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` (in amortized constant time if the specified `hint` is a valid immediate successor to the `value_type` object constructed from `args`), 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`. 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 map. 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/map-0a7/empty.adoc[`empty`] 
| Return `true` if this map contains no elements, and `false` otherwise.
| xref:bsl/map-0a7/end-06.adoc[`end`] 
| `end` overloads
| xref:bsl/map-0a7/equal_range-0e.adoc[`equal_range`] 
| `equal_range` overloads
| xref:bsl/map-0a7/erase-0d.adoc[`erase`] 
| `erase` overloads
| xref:bsl/map-0a7/find-08.adoc[`find`] 
| `find` overloads
| xref:bsl/map-0a7/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this map.
| xref:bsl/map-0a7/insert-03.adoc[`insert`] 
| `insert` overloads
| xref:bsl/map-0a7/insert_or_assign-0f.adoc[`insert_or_assign`] 
| `insert_or_assign` overloads
| xref:bsl/map-0a7/insert_range.adoc[`insert_range`] 
| Insert into this map the value of each `value_type` object in the specified `range` if the key equivalent of that object is not already contained in this map. 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 map, where `i` is a dereferenceable iterator obtained from `range` (see {Requirements on `KEY` and `VALUE`}). The behavior is undefined if `range` overlaps this map.
| xref:bsl/map-0a7/key_comp.adoc[`key_comp`] 
| Return the key‐comparison functor (or function pointer) used by this map; 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 map.
| xref:bsl/map-0a7/lower_bound-03.adoc[`lower_bound`] 
| `lower_bound` overloads
| xref:bsl/map-0a7/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on the largest number of elements that this map could possibly hold. Note that there is no guarantee that the map can successfully grow to the returned size, or even close to that size without running out of resources.
| xref:bsl/map-0a7/operator_subs-0e4.adoc[`operator[]`] 
| Subscript operators
| xref:bsl/map-0a7/rbegin-01.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/map-0a7/rend-0d8.adoc[`rend`] 
| `rend` overloads
| xref:bsl/map-0a7/size.adoc[`size`] 
| Return the number of elements in this map.
| xref:bsl/map-0a7/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/map-0a7/try_emplace-0c.adoc[`try_emplace`] 
| `try_emplace` overloads
| xref:bsl/map-0a7/upper_bound-00.adoc[`upper_bound`] 
| `upper_bound` overloads
| xref:bsl/map-0a7/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., `bsl::pair<const KEY, VALUE>`).
|===


== Specializations

[cols="1,4"]
|===
| Name| Description
| xref:bsl/map-0af.adoc[`map<TimeInterval, Node*>`] 
| This class template implements a value‐semantic container type holding an ordered sequence of key‐value pairs having unique keys that provide a mapping from keys (of the template parameter type, `KEY`) to their associated values (of another template parameter type, `VALUE`).
| xref:bsl/map-0c7.adoc[`map<int, pair<shared_ptr<Statistics>, shared_ptr<Collector<OsLinux>>>>`] 
| This class template implements a value‐semantic container type holding an ordered sequence of key‐value pairs having unique keys that provide a mapping from keys (of the template parameter type, `KEY`) to their associated values (of another template parameter type, `VALUE`).
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/map-0da.adoc[`map<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `map`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/map-0b.adoc[`map<KEY, VALUE>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `map`. This deduction guide does not participate unless the supplied allocator is convertible to `bsl::allocator<bsl::pair<const KEY, VALUE>>`.
| xref:bsl/map-06.adoc[`map<KEY, VALUE, COMPARATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `map`. 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/map-0ac.adoc[`map<KEY, VALUE, COMPARATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `map`. 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/map-0d4.adoc[`map<KEY, VALUE, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the initializer_list supplied to the constructor of `map`. 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/map-03.adoc[`map<KEY, VALUE, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameters `KEY` and `VALUE` from the `value_type` of the iterators supplied to the constructor of `map`. 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/map-0cb.adoc[`map<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 `map`. 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/map-02.adoc[`map<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 `map`. 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-01.adoc[`erase_if`]
| Erase all the elements in the specified map `m` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_3way-044.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-04b.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `map` 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-0cc.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]#