154 lines
15 KiB
Markdown
154 lines
15 KiB
Markdown
[multimap]
|
||
|
||
# 23 Containers library [[containers]](./#containers)
|
||
|
||
## 23.4 Associative containers [[associative]](associative#multimap)
|
||
|
||
### 23.4.4 Class template multimap [multimap]
|
||
|
||
#### [23.4.4.1](#overview) Overview [[multimap.overview]](multimap.overview)
|
||
|
||
[1](#overview-1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12203)
|
||
|
||
Amultimap 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 typeT based on the keys[.](#overview-1.sentence-1)
|
||
|
||
Themultimap class
|
||
supports bidirectional iterators[.](#overview-1.sentence-2)
|
||
|
||
[2](#overview-2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12216)
|
||
|
||
A multimap meets all of the requirements
|
||
of a container ([[container.reqmts]](container.reqmts "23.2.2.2 Container requirements")),
|
||
of a reversible container ([[container.rev.reqmts]](container.rev.reqmts "23.2.2.3 Reversible container requirements")),
|
||
of an allocator-aware container ([[container.alloc.reqmts]](container.alloc.reqmts "23.2.2.5 Allocator-aware containers")), and
|
||
of an associative container ([[associative.reqmts]](associative.reqmts "23.2.7 Associative containers"))[.](#overview-2.sentence-1)
|
||
|
||
Amultimap also provides most operations described in [[associative.reqmts]](associative.reqmts "23.2.7 Associative containers") for equal keys[.](#overview-2.sentence-2)
|
||
|
||
This means that amultimap supports thea_eq operations in [[associative.reqmts]](associative.reqmts "23.2.7 Associative containers") but not thea_uniq operations[.](#overview-2.sentence-3)
|
||
|
||
For amultimap<Key,T> thekey_type isKey and thevalue_type ispair<const Key,T>[.](#overview-2.sentence-4)
|
||
|
||
Descriptions are provided here only for operations onmultimap that are not described in one of those tables
|
||
or for operations where there is additional semantic information[.](#overview-2.sentence-5)
|
||
|
||
[3](#overview-3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12249)
|
||
|
||
The types iterator and const_iterator meet
|
||
the constexpr iterator requirements ([[iterator.requirements.general]](iterator.requirements.general "24.3.1 General"))[.](#overview-3.sentence-1)
|
||
|
||
[ð](#lib:comp,multimap::value_compare)
|
||
|
||
namespace std {template<class Key, class T, class Compare = less<Key>, class Allocator = allocator<pair<const Key, T>>>class multimap {public:// typesusing 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]](container.requirements "23.2 Requirements")using difference_type = *implementation-defined*; // see [[container.requirements]](container.requirements "23.2 Requirements")using iterator = *implementation-defined*; // see [[container.requirements]](container.requirements "23.2 Requirements")using const_iterator = *implementation-defined*; // see [[container.requirements]](container.requirements "23.2 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]](#cons "23.4.4.2 Constructors"), construct/copy/destroyconstexpr 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*](container.intro.reqmts#concept:container-compatible-range "23.2.2.1 Introduction [container.intro.reqmts]")<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*](container.intro.reqmts#concept:container-compatible-range "23.2.2.1 Introduction [container.intro.reqmts]")<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; // iteratorsconstexpr 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; // capacityconstexpr bool empty() const noexcept; constexpr size_type size() const noexcept; constexpr size_type max_size() const noexcept; // [[multimap.modifiers]](#modifiers "23.4.4.3 Modifiers"), modifierstemplate<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*](container.intro.reqmts#concept:container-compatible-range "23.2.2.1 Introduction [container.intro.reqmts]")<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); // observersconstexpr key_compare key_comp() const; constexpr value_compare value_comp() const; // map operationsconstexpr 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](range.refinements#concept:input_range "25.4.6 Other range refinements [range.refinements]") 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](range.refinements#concept:input_range "25.4.6 Other range refinements [range.refinements]") 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](#cons) Constructors [[multimap.cons]](multimap.cons)
|
||
|
||
[ð](#lib:multimap,constructor)
|
||
|
||
`constexpr explicit multimap(const Compare& comp, const Allocator& = Allocator());
|
||
`
|
||
|
||
[1](#cons-1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12459)
|
||
|
||
*Effects*: Constructs an emptymultimap using the specified comparison object and allocator[.](#cons-1.sentence-1)
|
||
|
||
[2](#cons-2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12465)
|
||
|
||
*Complexity*: Constant[.](#cons-2.sentence-1)
|
||
|
||
[ð](#lib:multimap,constructor_)
|
||
|
||
`template<class InputIterator>
|
||
constexpr multimap(InputIterator first, InputIterator last,
|
||
const Compare& comp = Compare(), const Allocator& = Allocator());
|
||
`
|
||
|
||
[3](#cons-3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12478)
|
||
|
||
*Effects*: Constructs an emptymultimap using the specified comparison object and allocator,
|
||
and inserts elements from the range
|
||
[first, last)[.](#cons-3.sentence-1)
|
||
|
||
[4](#cons-4)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12486)
|
||
|
||
*Complexity*: Linear in N if the range
|
||
[first, last)
|
||
is already sorted with respect to comp and otherwise NlogN,
|
||
where N islast - first[.](#cons-4.sentence-1)
|
||
|
||
[ð](#lib:multimap,constructor__)
|
||
|
||
`template<[container-compatible-range](container.intro.reqmts#concept:container-compatible-range "23.2.2.1 Introduction [container.intro.reqmts]")<value_type> R>
|
||
constexpr multimap(from_range_t, R&& rg,
|
||
const Compare& comp = Compare(), const Allocator& = Allocator());
|
||
`
|
||
|
||
[5](#cons-5)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12504)
|
||
|
||
*Effects*: Constructs an empty multimap using the specified comparison object and allocator, and
|
||
inserts elements from the range rg[.](#cons-5.sentence-1)
|
||
|
||
[6](#cons-6)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12510)
|
||
|
||
*Complexity*: Linear in N if rg is already sorted with respect to comp and
|
||
otherwise NlogN, where N is ranges::distance(rg)[.](#cons-6.sentence-1)
|
||
|
||
#### [23.4.4.3](#modifiers) Modifiers [[multimap.modifiers]](multimap.modifiers)
|
||
|
||
[ð](#lib:insert,multimap)
|
||
|
||
`template<class P> constexpr iterator insert(P&& x);
|
||
template<class P> constexpr iterator insert(const_iterator position, P&& x);
|
||
`
|
||
|
||
[1](#modifiers-1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12525)
|
||
|
||
*Constraints*: is_constructible_v<value_type, P&&> is true[.](#modifiers-1.sentence-1)
|
||
|
||
[2](#modifiers-2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12529)
|
||
|
||
*Effects*: The first form is equivalent toreturn emplace(std::forward<P>(x))[.](#modifiers-2.sentence-1)
|
||
|
||
The second form is
|
||
equivalent to return emplace_hint(position, std::forward<P>(x))[.](#modifiers-2.sentence-2)
|
||
|
||
#### [23.4.4.4](#erasure) Erasure [[multimap.erasure]](multimap.erasure)
|
||
|
||
[ð](#lib:erase_if,multimap)
|
||
|
||
`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](#erasure-1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/containers.tex#L12546)
|
||
|
||
*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();
|