23 Containers library [containers]

23.4 Associative containers [associative]

23.4.4 Class template multimap [multimap]

23.4.4.1 Overview [multimap.overview]

1
#
A multimap is an associative container that supports equivalent keys (i.e., possibly containing multiple copies of the same key value) and provides for fast retrieval of values of another type T based on the keys.
The multimap class supports bidirectional iterators.
2
#
A multimap meets all of the requirements of a container ([container.reqmts]), of a reversible container ([container.rev.reqmts]), of an allocator-aware container ([container.alloc.reqmts]), and of an associative container ([associative.reqmts]).
A multimap also provides most operations described in [associative.reqmts] for equal keys.
This means that a multimap supports the a_eq operations in [associative.reqmts] but not the a_uniq operations.
For a multimap<Key,T> the key_type is Key and the value_type is pair<const Key,T>.
Descriptions are provided here only for operations on multimap that are not described in one of those tables or for operations where there is additional semantic information.
3
#
The types iterator and const_iterator meet the constexpr iterator requirements ([iterator.requirements.general]).
🔗
namespace std { template<class Key, class T, class Compare = less<Key>, class Allocator = allocator<pair<const Key, T>>> class multimap { public: // types using key_type = Key; using mapped_type = T; using value_type = pair<const Key, T>; using key_compare = Compare; using allocator_type = Allocator; using pointer = typename allocator_traits<Allocator>::pointer; using const_pointer = typename allocator_traits<Allocator>::const_pointer; using reference = value_type&; using const_reference = const value_type&; using size_type = implementation-defined; // see [container.requirements] using difference_type = implementation-defined; // see [container.requirements] using iterator = implementation-defined; // see [container.requirements] using const_iterator = implementation-defined; // see [container.requirements] using reverse_iterator = std::reverse_iterator<iterator>; using const_reverse_iterator = std::reverse_iterator<const_iterator>; using node_type = unspecified; class value_compare { protected: Compare comp; constexpr value_compare(Compare c) : comp(c) { } public: constexpr bool operator()(const value_type& x, const value_type& y) const { return comp(x.first, y.first); } }; // [multimap.cons], construct/copy/destroy constexpr multimap() : multimap(Compare()) { } constexpr explicit multimap(const Compare& comp, const Allocator& = Allocator()); template<class InputIterator> constexpr multimap(InputIterator first, InputIterator last, const Compare& comp = Compare(), const Allocator& = Allocator()); template<container-compatible-range<value_type> R> constexpr multimap(from_range_t, R&& rg, const Compare& comp = Compare(), const Allocator& = Allocator()); constexpr multimap(const multimap& x); constexpr multimap(multimap&& x); constexpr explicit multimap(const Allocator&); constexpr multimap(const multimap&, const type_identity_t<Allocator>&); constexpr multimap(multimap&&, const type_identity_t<Allocator>&); constexpr multimap(initializer_list<value_type>, const Compare& = Compare(), const Allocator& = Allocator()); template<class InputIterator> constexpr multimap(InputIterator first, InputIterator last, const Allocator& a) : multimap(first, last, Compare(), a) { } template<container-compatible-range<value_type> R> constexpr multimap(from_range_t, R&& rg, const Allocator& a)) : multimap(from_range, std::forward<R>(rg), Compare(), a) { } constexpr multimap(initializer_list<value_type> il, const Allocator& a) : multimap(il, Compare(), a) { } constexpr ~multimap(); constexpr multimap& operator=(const multimap& x); constexpr multimap& operator=(multimap&& x) noexcept(allocator_traits<Allocator>::is_always_equal::value && is_nothrow_move_assignable_v<Compare>); constexpr multimap& operator=(initializer_list<value_type>); constexpr allocator_type get_allocator() const noexcept; // iterators constexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept; constexpr iterator end() noexcept; constexpr const_iterator end() const noexcept; constexpr reverse_iterator rbegin() noexcept; constexpr const_reverse_iterator rbegin() const noexcept; constexpr reverse_iterator rend() noexcept; constexpr const_reverse_iterator rend() const noexcept; constexpr const_iterator cbegin() const noexcept; constexpr const_iterator cend() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept; constexpr const_reverse_iterator crend() const noexcept; // capacity constexpr bool empty() const noexcept; constexpr size_type size() const noexcept; constexpr size_type max_size() const noexcept; // [multimap.modifiers], modifiers template<class... Args> constexpr iterator emplace(Args&&... args); template<class... Args> constexpr iterator emplace_hint(const_iterator position, Args&&... args); constexpr iterator insert(const value_type& x); constexpr iterator insert(value_type&& x); template<class P> constexpr iterator insert(P&& x); constexpr iterator insert(const_iterator position, const value_type& x); constexpr iterator insert(const_iterator position, value_type&& x); template<class P> constexpr iterator insert(const_iterator position, P&& x); template<class InputIterator> constexpr void insert(InputIterator first, InputIterator last); template<container-compatible-range<value_type> R> constexpr void insert_range(R&& rg); constexpr void insert(initializer_list<value_type>); constexpr node_type extract(const_iterator position); constexpr node_type extract(const key_type& x); template<class K> node_type extract(K&& x); constexpr iterator insert(node_type&& nh); constexpr iterator insert(const_iterator hint, node_type&& nh); constexpr iterator erase(iterator position); constexpr iterator erase(const_iterator position); constexpr size_type erase(const key_type& x); template<class K> constexpr size_type erase(K&& x); constexpr iterator erase(const_iterator first, const_iterator last); constexpr void swap(multimap&) noexcept(allocator_traits<Allocator>::is_always_equal::value && is_nothrow_swappable_v<Compare>); constexpr void clear() noexcept; template<class C2> constexpr void merge(multimap<Key, T, C2, Allocator>& source); template<class C2> constexpr void merge(multimap<Key, T, C2, Allocator>&& source); template<class C2> constexpr void merge(map<Key, T, C2, Allocator>& source); template<class C2> constexpr void merge(map<Key, T, C2, Allocator>&& source); // observers constexpr key_compare key_comp() const; constexpr value_compare value_comp() const; // map operations constexpr iterator find(const key_type& x); constexpr const_iterator find(const key_type& x) const; template<class K> constexpr iterator find(const K& x); template<class K> constexpr const_iterator find(const K& x) const; constexpr size_type count(const key_type& x) const; template<class K> constexpr size_type count(const K& x) const; constexpr bool contains(const key_type& x) const; template<class K> constexpr bool contains(const K& x) const; constexpr iterator lower_bound(const key_type& x); constexpr const_iterator lower_bound(const key_type& x) const; template<class K> constexpr iterator lower_bound(const K& x); template<class K> constexpr const_iterator lower_bound(const K& x) const; constexpr iterator upper_bound(const key_type& x); constexpr const_iterator upper_bound(const key_type& x) const; template<class K> constexpr iterator upper_bound(const K& x); template<class K> constexpr const_iterator upper_bound(const K& x) const; constexpr pair<iterator, iterator> equal_range(const key_type& x); constexpr pair<const_iterator, const_iterator> equal_range(const key_type& x) const; template<class K> constexpr pair<iterator, iterator> equal_range(const K& x); template<class K> constexpr pair<const_iterator, const_iterator> equal_range(const K& x) const; }; template<class InputIterator, class Compare = less<iter-key-type<InputIterator>>, class Allocator = allocator<iter-to-alloc-type<InputIterator>>> multimap(InputIterator, InputIterator, Compare = Compare(), Allocator = Allocator()) -> multimap<iter-key-type<InputIterator>, iter-mapped-type<InputIterator>, Compare, Allocator>; template<ranges::input_range R, class Compare = less<range-key-type<R>>, class Allocator = allocator<range-to-alloc-type<R>>> multimap(from_range_t, R&&, Compare = Compare(), Allocator = Allocator()) -> multimap<range-key-type<R>, range-mapped-type<R>, Compare, Allocator>; template<class Key, class T, class Compare = less<Key>, class Allocator = allocator<pair<const Key, T>>> multimap(initializer_list<pair<Key, T>>, Compare = Compare(), Allocator = Allocator()) -> multimap<Key, T, Compare, Allocator>; template<class InputIterator, class Allocator> multimap(InputIterator, InputIterator, Allocator) -> multimap<iter-key-type<InputIterator>, iter-mapped-type<InputIterator>, less<iter-key-type<InputIterator>>, Allocator>; template<ranges::input_range R, class Allocator> multimap(from_range_t, R&&, Allocator) -> multimap<range-key-type<R>, range-mapped-type<R>, less<range-key-type<R>>, Allocator>; template<class Key, class T, class Allocator> multimap(initializer_list<pair<Key, T>>, Allocator) -> multimap<Key, T, less<Key>, Allocator>; }

23.4.4.2 Constructors [multimap.cons]

🔗
constexpr explicit multimap(const Compare& comp, const Allocator& = Allocator());
1
#
Effects: Constructs an empty multimap using the specified comparison object and allocator.
2
#
Complexity: Constant.
🔗
template<class InputIterator> constexpr multimap(InputIterator first, InputIterator last, const Compare& comp = Compare(), const Allocator& = Allocator());
3
#
Effects: Constructs an empty multimap using the specified comparison object and allocator, and inserts elements from the range [first, last).
4
#
Complexity: Linear in N if the range [first, last) is already sorted with respect to comp and otherwise , where N is last - first.
🔗
template<container-compatible-range<value_type> R> constexpr multimap(from_range_t, R&& rg, const Compare& comp = Compare(), const Allocator& = Allocator());
5
#
Effects: Constructs an empty multimap using the specified comparison object and allocator, and inserts elements from the range rg.
6
#
Complexity: Linear in N if rg is already sorted with respect to comp and otherwise , where N is ranges​::​distance(rg).

23.4.4.3 Modifiers [multimap.modifiers]

🔗
template<class P> constexpr iterator insert(P&& x); template<class P> constexpr iterator insert(const_iterator position, P&& x);
1
#
Constraints: is_constructible_v<value_type, P&&> is true.
2
#
Effects: The first form is equivalent to return emplace(std​::​forward<P>(x)).
The second form is equivalent to return emplace_hint(position, std​::​forward<P>(x)).

23.4.4.4 Erasure [multimap.erasure]

🔗
template<class Key, class T, class Compare, class Allocator, class Predicate> typename multimap<Key, T, Compare, Allocator>::size_type constexpr erase_if(multimap<Key, T, Compare, Allocator>& c, Predicate pred);
1
#
Effects: Equivalent to: auto original_size = c.size(); for (auto i = c.begin(), last = c.end(); i != last; ) { if (pred(*i)) { i = c.erase(i); } else { ++i; } } return original_size - c.size();