[#bsl-multiset-03]
= xref:bsl.adoc[bsl]::multiset
:relfileprefix: ../
:mrdocs:

This class template implements a value‐semantic container type holding an ordered sequence of possibly duplicate keys (of the template parameter type, `KEY`).

== Synopsis

Declared in `<bslstl_multiset.h>`

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

== 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/multiset-03/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias to the (template parameter) `ALLOCATOR`.
| xref:bsl/multiset-03/const_iterator.adoc[`const_iterator`] 
| This `typedef` is an alias to `iterator`.
| xref:bsl/multiset-03/const_pointer.adoc[`const_pointer`] 
| This `typedef` is an alias to the allocator const‐pointer type.
| xref:bsl/multiset-03/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias for `const_reference`.
| xref:bsl/multiset-03/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| This `typedef` is an alias to the const reverse iterator type.
| xref:bsl/multiset-03/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to the allocator difference type.
| xref:bsl/multiset-03/iterator.adoc[`iterator`] 
| This `typedef` is an alias to the red‐black tree iterator type.
| xref:bsl/multiset-03/key_compare.adoc[`key_compare`] 
| This `typedef` is an alias to the (template parameter) `COMPARATOR`.
| xref:bsl/multiset-03/key_type.adoc[`key_type`] 
| This `typedef` is an alias to the (template parameter) `KEY` type.
| xref:bsl/multiset-03/pointer.adoc[`pointer`] 
| This `typedef` is an alias to the allocator pointer type.
| xref:bsl/multiset-03/reference.adoc[`reference`] 
| This `typedef` is an alias to `value_type&`.
| xref:bsl/multiset-03/reverse_iterator.adoc[`reverse_iterator`] 
| This `typedef` is an alias to the reverse iterator type.
| xref:bsl/multiset-03/size_type.adoc[`size_type`] 
| This `typedef` is an alias to the allocator size type.
| xref:bsl/multiset-03/value_compare.adoc[`value_compare`] 
| This `typedef` is an alias to `key_compare`.
| xref:bsl/multiset-03/value_type.adoc[`value_type`] 
| This `typedef` is an alias to `key_type`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/multiset-03/2constructor-05.adoc[`multiset`]         [.small]#[constructor]#
| Constructors
| xref:bsl/multiset-03/2destructor.adoc[`~multiset`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/multiset-03/operator_assign-09.adoc[`operator=`] 
| Assignment operators
| xref:bsl/multiset-03/begin-00.adoc[`begin`] 
| `begin` overloads
| xref:bsl/multiset-03/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 multiset, or the `end` iterator if this multiset is empty.
| xref:bsl/multiset-03/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 multiset.
| xref:bsl/multiset-03/clear.adoc[`clear`] 
| Remove all entries from this multiset. Note that the multiset is empty after this call, but allocated memory may be retained for future use.
| xref:bsl/multiset-03/contains-0b.adoc[`contains`] 
| Return `true` if this map contains an element whose key is equivalent to the specified `key`.
| xref:bsl/multiset-03/count-064.adoc[`count`] 
| Return the number of `value_type` objects within this multiset that are equivalent to the specified `key`.
| xref:bsl/multiset-03/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 multiset, or `rend` if this multiset is empty.
| xref:bsl/multiset-03/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 multiset.
| xref:bsl/multiset-03/emplace.adoc[`emplace`] 
| Insert into this multiset 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 multiset. This method requires that the (template parameter) type `KEY` be `emplace‐constructible` from `args` (see {Requirements on `KEY`}).
| xref:bsl/multiset-03/emplace_hint.adoc[`emplace_hint`] 
| Insert into this multiset 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 multiset. 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 multiset. This method requires that the (template parameter) type `KEY` be `emplace‐constructible` from `args` (see {Requirements on `KEY`}). The behavior is undefined unless `hint` is an iterator in the range `[begin() .. end()]` (both endpoints included).
| xref:bsl/multiset-03/empty.adoc[`empty`] 
| Return `true` if this multiset contains no elements, and `false` otherwise.
| xref:bsl/multiset-03/end-05.adoc[`end`] 
| `end` overloads
| xref:bsl/multiset-03/equal_range-00.adoc[`equal_range`] 
| `equal_range` overloads
| xref:bsl/multiset-03/erase-0f.adoc[`erase`] 
| `erase` overloads
| xref:bsl/multiset-03/find-0b.adoc[`find`] 
| `find` overloads
| xref:bsl/multiset-03/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this multiset.
| xref:bsl/multiset-03/insert-07.adoc[`insert`] 
| `insert` overloads
| xref:bsl/multiset-03/insert_range.adoc[`insert_range`] 
| Insert into this multiset 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`}). The behavior is undefined if `range` overlaps this multiset.
| xref:bsl/multiset-03/key_comp.adoc[`key_comp`] 
| Return the key‐comparison functor (or function pointer) used by this multiset; 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 type of the `value_type` objects contained in this multiset.
| xref:bsl/multiset-03/lower_bound-04.adoc[`lower_bound`] 
| `lower_bound` overloads
| xref:bsl/multiset-03/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on the largest number of elements that this multiset could possibly hold. Note that there is no guarantee that the multiset can successfully grow to the returned size, or even close to that size without running out of resources.
| xref:bsl/multiset-03/rbegin-01.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/multiset-03/rend-0f.adoc[`rend`] 
| `rend` overloads
| xref:bsl/multiset-03/size.adoc[`size`] 
| Return the number of elements in this multiset.
| xref:bsl/multiset-03/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/multiset-03/upper_bound-0e.adoc[`upper_bound`] 
| `upper_bound` overloads
| xref:bsl/multiset-03/value_comp.adoc[`value_comp`] 
| Return a functor for comparing two `value_type` objects using `key_comp()`. Note that since `value_type` is an alias to `KEY` for `multiset`, this method returns the same functor as `key_comp()`.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/multiset-02.adoc[`multiset<KEY>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `multiset`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/multiset-06a.adoc[`multiset<KEY>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `multiset`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/multiset-005.adoc[`multiset<KEY, COMPARATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `multiset`. Deduce the template parameter `COMPARATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/multiset-0a.adoc[`multiset<KEY, COMPARATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `multiset`. Deduce the template parameter `COMPARATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/multiset-05.adoc[`multiset<KEY, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `multiset`. Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the other parameters passed to the constructor.
| xref:bsl/multiset-060.adoc[`multiset<KEY, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `multiset`. Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the other parameters passed to the constructor. This guide does not participate unless the supplied (or defaulted) `ALLOCATOR` meets the requirements of a standard allocator.
| xref:bsl/multiset-00e.adoc[`multiset<KEY, std::less<KEY>, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `multiset`. Deduce the template parameter `ALLOCATOR` from the other parameter passed to the constructor.
| xref:bsl/multiset-0f.adoc[`multiset<KEY, std::less<KEY>, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `multiset`. 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.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase_if-030.adoc[`erase_if`]
| Erase all the elements in the specified multiset `ms` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_3way-0ff.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of the specified `lhs` and the specified `rhs` multisets by using the comparison operators of `KEY` on each element; return the result of that comparison.
| xref:bsl/operator_eq-0a8.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `multiset` objects `lhs` and `rhs` have the same value if they have the same number of keys, and each element in the ordered sequence of keys of `lhs` has the same value as the corresponding element in the ordered sequence of keys of `rhs`. This method requires that the (template parameter) type `KEY` be `equality‐comparable` (see {Requirements on `KEY`}).
| xref:bsl/swap-001.adoc[`swap`]
| Exchange the values of the specified `a` and `b` multisets.
|===


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