Class Template unordered_multimap
boost::unordered_multimap
— An unordered associative container that associates keys with another value. The same key can be stored multiple times.
Synopsis
// #include <boost/unordered/unordered_map.hpp> namespace boost { namespace unordered { template<class Key, class T, class Hash = boost::hash<Key>, class Pred = std::equal_to<Key>, class Allocator = std::allocator<std::pair<const Key, T>>> class unordered_multimap { public: // types using key_type = Key; using mapped_type = T; using value_type = std::pair<const Key, T>; using hasher = Hash; using key_equal = Pred; using allocator_type = Allocator; using pointer = typename std::allocator_traits<Allocator>::pointer; using const_pointer = typename std::allocator_traits<Allocator>::const_pointer; using reference = value_type&; using const_reference = const value_type&; using size_type = std::size_t; using difference_type = std::ptrdiff_t; using iterator = implementation-defined; using const_iterator = implementation-defined; using local_iterator = implementation-defined; using const_local_iterator = implementation-defined; using node_type = implementation-defined; // construct/copy/destroy unordered_multimap(); explicit unordered_multimap(size_type n, const hasher& hf = hasher(), const key_equal& eql = key_equal(), const allocator_type& a = allocator_type()); template<class InputIterator> unordered_multimap(InputIterator f, InputIterator l, size_type n = implementation-defined, const hasher& hf = hasher(), const key_equal& eql = key_equal(), const allocator_type& a = allocator_type()); unordered_multimap(const unordered_multimap& other); unordered_multimap(unordered_multimap&& other); template<class InputIterator> unordered_multimap(InputIterator f, InputIterator l, const allocator_type& a); explicit unordered_multimap(const Allocator& a); unordered_multimap(const unordered_multimap& other, const Allocator& a); unordered_multimap(unordered_multimap&& other, const Allocator& a); unordered_multimap(std::initializer_list<value_type> il, size_type n = implementation-defined, const hasher& hf = hasher(), const key_equal& eql = key_equal(), const allocator_type& a = allocator_type()); unordered_multimap(size_type n, const allocator_type& a); unordered_multimap(size_type n, const hasher& hf, const allocator_type& a); template<class InputIterator> unordered_multimap(InputIterator f, InputIterator l, size_type n, const allocator_type& a); template<class InputIterator> unordered_multimap(InputIterator f, InputIterator l, size_type n, const hasher& hf, const allocator_type& a); unordered_multimap(std::initializer_list<value_type> il, const allocator_type& a); unordered_multimap(std::initializer_list<value_type> il, size_type n, const allocator_type& a); unordered_multimap(std::initializer_list<value_type> il, size_type n, const hasher& hf, const allocator_type& a); ~unordered_multimap(); unordered_multimap& operator=(const unordered_multimap& other); unordered_multimap& operator=(unordered_multimap&& other) noexcept(boost::allocator_traits<Allocator>::is_always_equal::value && boost::is_nothrow_move_assignable_v<Hash> && boost::is_nothrow_move_assignable_v<Pred>); unordered_multimap& operator=(std::initializer_list<value_type> il); allocator_type get_allocator() const noexcept; // iterators iterator begin() noexcept; const_iterator begin() const noexcept; iterator end() noexcept; const_iterator end() const noexcept; const_iterator cbegin() const noexcept; const_iterator cend() const noexcept; // capacity [[nodiscard]] bool empty() const noexcept; size_type size() const noexcept; size_type max_size() const noexcept; // modifiers template<class... Args> iterator emplace(Args&&... args); template<class... Args> iterator emplace_hint(const_iterator position, Args&&... args); iterator insert(const value_type& obj); iterator insert(value_type&& obj); template<class P> iterator insert(P&& obj); iterator insert(const_iterator hint, const value_type& obj); iterator insert(const_iterator hint, value_type&& obj); template<class P> iterator insert(const_iterator hint, P&& obj); template<class InputIterator> void insert(InputIterator first, InputIterator last); void insert(std::initializer_list<value_type> il); node_type extract(const_iterator position); node_type extract(const key_type& k); template<class K> node_type extract(K&& k); iterator insert(node_type&& nh); iterator insert(const_iterator hint, node_type&& nh); iterator erase(iterator position); iterator erase(const_iterator position); size_type erase(const key_type& k); template<class K> size_type erase(K&& k); iterator erase(const_iterator first, const_iterator last); void quick_erase(const_iterator position); void erase_return_void(const_iterator position); void swap(unordered_multimap& other) noexcept(boost::allocator_traits<Allocator>::is_always_equal::value && boost::is_nothrow_swappable_v<Hash> && boost::is_nothrow_swappable_v<Pred>); void clear() noexcept; template<class H2, class P2> void merge(unordered_multimap<Key, T, H2, P2, Allocator>& source); template<class H2, class P2> void merge(unordered_multimap<Key, T, H2, P2, Allocator>&& source); template<class H2, class P2> void merge(unordered_map<Key, T, H2, P2, Allocator>& source); template<class H2, class P2> void merge(unordered_map<Key, T, H2, P2, Allocator>&& source); // observers hasher hash_function() const; key_equal key_eq() const; // map operations iterator find(const key_type& k); const_iterator find(const key_type& k) const; template<class K> iterator find(const K& k); template<class K> const_iterator find(const K& k) const; template<typename CompatibleKey, typename CompatibleHash, typename CompatiblePredicate> iterator find(CompatibleKey const& k, CompatibleHash const& hash, CompatiblePredicate const& eq); template<typename CompatibleKey, typename CompatibleHash, typename CompatiblePredicate> const_iterator find(CompatibleKey const& k, CompatibleHash const& hash, CompatiblePredicate const& eq) const; size_type count(const key_type& k) const; template<class K> size_type count(const K& k) const; bool contains(const key_type& k) const; template<class K> bool contains(const K& k) const; std::pair<iterator, iterator> equal_range(const key_type& k); std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const; template<class K> std::pair<iterator, iterator> equal_range(const K& k); template<class K> std::pair<const_iterator, const_iterator> equal_range(const K& k) const; // bucket interface size_type bucket_count() const noexcept; size_type max_bucket_count() const noexcept; size_type bucket_size(size_type n) const; size_type bucket(const key_type& k) const; template<class K> size_type bucket(const K& k) const; local_iterator begin(size_type n); const_local_iterator begin(size_type n) const; local_iterator end(size_type n); const_local_iterator end(size_type n) const; const_local_iterator cbegin(size_type n) const; const_local_iterator cend(size_type n) const; // hash policy float load_factor() const noexcept; float max_load_factor() const noexcept; void max_load_factor(float z); void rehash(size_type n); void reserve(size_type n); }; // Deduction Guides template<class InputIterator, class Hash = boost::hash<iter-key-type<InputIterator>>, class Pred = std::equal_to<iter-key-type<InputIterator>>, class Allocator = std::allocator<iter-to-alloc-type<InputIterator>>> unordered_multimap(InputIterator, InputIterator, typename see below::size_type = see below, Hash = Hash(), Pred = Pred(), Allocator = Allocator()) -> unordered_multimap<iter-key-type<InputIterator>, iter-mapped-type<InputIterator>, Hash, Pred, Allocator>; template<class Key, class T, class Hash = boost::hash<Key>, class Pred = std::equal_to<Key>, class Allocator = std::allocator<std::pair<const Key, T>>> unordered_multimap(std::initializer_list<std::pair<Key, T>>, typename see below::size_type = see below, Hash = Hash(), Pred = Pred(), Allocator = Allocator()) -> unordered_multimap<Key, T, Hash, Pred, Allocator>; template<class InputIterator, class Allocator> unordered_multimap(InputIterator, InputIterator, typename see below::size_type, Allocator) -> unordered_multimap<iter-key-type<InputIterator>, iter-mapped-type<InputIterator>, boost::hash<iter-key-type<InputIterator>>, std::equal_to<iter-key-type<InputIterator>>, Allocator>; template<class InputIterator, class Allocator> unordered_multimap(InputIterator, InputIterator, Allocator) -> unordered_multimap<iter-key-type<InputIterator>, iter-mapped-type<InputIterator>, boost::hash<iter-key-type<InputIterator>>, std::equal_to<iter-key-type<InputIterator>>, Allocator>; template<class InputIterator, class Hash, class Allocator> unordered_multimap(InputIterator, InputIterator, typename see below::size_type, Hash, Allocator) -> unordered_multimap<iter-key-type<InputIterator>, iter-mapped-type<InputIterator>, Hash, std::equal_to<iter-key-type<InputIterator>>, Allocator>; template<class Key, class T, class Allocator> unordered_multimap(std::initializer_list<std::pair<Key, T>>, typename see below::size_type, Allocator) -> unordered_multimap<Key, T, boost::hash<Key>, std::equal_to<Key>, Allocator>; template<class Key, class T, class Allocator> unordered_multimap(std::initializer_list<std::pair<Key, T>>, Allocator) -> unordered_multimap<Key, T, boost::hash<Key>, std::equal_to<Key>, Allocator>; template<class Key, class T, class Hash, class Allocator> unordered_multimap(std::initializer_list<std::pair<Key, T>>, typename see below::size_type, Hash, Allocator) -> unordered_multimap<Key, T, Hash, std::equal_to<Key>, Allocator>; } // namespace unordered } // namespace boost
Description
Template Parameters
Key |
|
T |
|
Hash |
A unary function object type that acts a hash function for a |
Pred |
A binary function object that implements an equivalence relation on values of type |
Allocator |
An allocator whose value type is the same as the container’s value type. Allocators using fancy pointers are supported. |
The elements are organized into buckets. Keys with the same hash code are stored in the same bucket.
The number of buckets can be automatically increased by a call to insert, or as the result of calling rehash.
Typedefs
typedef implementation-defined iterator;
An iterator whose value type is value_type
.
The iterator category is at least a forward iterator.
Convertible to const_iterator
.
typedef implementation-defined const_iterator;
A constant iterator whose value type is value_type
.
The iterator category is at least a forward iterator.
typedef implementation-defined local_iterator;
An iterator with the same value type, difference type and pointer and reference type as iterator.
A local_iterator
object can be used to iterate through a single bucket.
typedef implementation-defined const_local_iterator;
A constant iterator with the same value type, difference type and pointer and reference type as const_iterator.
A const_local_iterator object can be used to iterate through a single bucket.
typedef implementation-defined node_type;
See node_handle_map for details.
Constructors
Default Constructor
unordered_multimap();
Constructs an empty container using hasher()
as the hash function,
key_equal()
as the key equality predicate, allocator_type()
as the allocator
and a maximum load factor of 1.0
.
Postconditions: |
|
Requires: |
If the defaults are used, |
Bucket Count Constructor
explicit unordered_multimap(size_type n,
const hasher& hf = hasher(),
const key_equal& eql = key_equal(),
const allocator_type& a = allocator_type());
Constructs an empty container with at least n
buckets, using hf
as the hash
function, eql
as the key equality predicate, a
as the allocator and a maximum
load factor of 1.0
.
Postconditions: |
|
Requires: |
If the defaults are used, |
Iterator Range Constructor
template<class InputIterator>
unordered_multimap(InputIterator f, InputIterator l,
size_type n = implementation-defined,
const hasher& hf = hasher(),
const key_equal& eql = key_equal(),
const allocator_type& a = allocator_type());
Constructs an empty container with at least n
buckets, using hf
as the hash function, eql
as the key equality predicate, a
as the allocator and a maximum load factor of 1.0
and inserts the elements from [f, l)
into it.
Requires: |
If the defaults are used, |
Copy Constructor
unordered_multimap(const unordered_multimap& other);
The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator.
If Allocator::select_on_container_copy_construction
exists and has the right signature, the allocator will be constructed from its result.
Requires: |
|
Move Constructor
unordered_multimap(unordered_multimap&& other);
The move constructor.
Notes: |
This is implemented using Boost.Move. |
Requires: |
|
Iterator Range Constructor with Allocator
template<class InputIterator>
unordered_multimap(InputIterator f, InputIterator l, const allocator_type& a);
Constructs an empty container using a
as the allocator, with the default hash function and key equality predicate and a maximum load factor of 1.0
and inserts the elements from [f, l)
into it.
Requires: |
|
Allocator Constructor
explicit unordered_multimap(const Allocator& a);
Constructs an empty container, using allocator a
.
Copy Constructor with Allocator
unordered_multimap(const unordered_multimap& other, const Allocator& a);
Constructs an container, copying other
's contained elements, hash function, predicate, maximum load factor, but using allocator a
.
Move Constructor with Allocator
unordered_multimap(unordered_multimap&& other, const Allocator& a);
Construct a container moving other
's contained elements, and having the hash function, predicate and maximum load factor, but using allocate a
.
Notes: |
This is implemented using Boost.Move. |
Requires: |
|
Initializer List Constructor
unordered_multimap(std::initializer_list<value_type> il,
size_type n = implementation-defined,
const hasher& hf = hasher(),
const key_equal& eql = key_equal(),
const allocator_type& a = allocator_type());
Constructs an empty container with at least n
buckets, using hf
as the hash function, eql
as the key equality predicate, a
as the allocator and a maximum load factor of 1.0
and inserts the elements from il
into it.
Requires: |
If the defaults are used, |
Bucket Count Constructor with Allocator
unordered_multimap(size_type n, const allocator_type& a);
Constructs an empty container with at least n
buckets, using hf
as the hash function, the default hash function and key equality predicate, a
as the allocator and a maximum load factor of 1.0
.
Postconditions: |
|
Requires: |
|
Bucket Count Constructor with Hasher and Allocator
unordered_multimap(size_type n, const hasher& hf, const allocator_type& a);
Constructs an empty container with at least n
buckets, using hf
as the hash function, the default key equality predicate, a
as the allocator and a maximum load factor of 1.0
.
Postconditions: |
|
Requires: |
|
Iterator Range Constructor with Bucket Count and Allocator
template<class InputIterator>
unordered_multimap(InputIterator f, InputIterator l, size_type n, const allocator_type& a);
Constructs an empty container with at least n
buckets, using a
as the allocator, with the default hash function and key equality predicate and a maximum load factor of 1.0
and inserts the elements from [f, l)
into it.
Requires: |
|
Iterator Range Constructor with Bucket Count and Hasher
template<class InputIterator>
unordered_multimap(InputIterator f, InputIterator l, size_type n, const hasher& hf,
const allocator_type& a);
Constructs an empty container with at least n
buckets, using hf
as the hash function, a
as the allocator, with the default key equality predicate and a maximum load factor of 1.0
and inserts the elements from [f, l)
into it.
Requires: |
|
initializer_list Constructor with Allocator
unordered_multimap(std::initializer_list<value_type> il, const allocator_type& a);
Constructs an empty container using a
as the allocator and a maximum load factor of 1.0 and inserts the elements from il
into it.
Requires: |
|
initializer_list Constructor with Bucket Count and Allocator
unordered_multimap(std::initializer_list<value_type> il, size_type n, const allocator_type& a);
Constructs an empty container with at least n
buckets, using a
as the allocator and a maximum load factor of 1.0 and inserts the elements from il
into it.
Requires: |
|
initializer_list Constructor with Bucket Count and Hasher and Allocator
unordered_multimap(std::initializer_list<value_type> il, size_type n, const hasher& hf,
const allocator_type& a);
Constructs an empty container with at least n
buckets, using hf
as the hash function, a
as the allocator and a maximum load factor of 1.0 and inserts the elements from il
into it.
Requires: |
|
Destructor
~unordered_multimap();
Note: |
The destructor is applied to every element, and all memory is deallocated |
Assignment
Copy Assignment
unordered_multimap& operator=(const unordered_multimap& other);
The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator.
If Alloc::propagate_on_container_copy_assignment
exists and Alloc::propagate_on_container_copy_assignment::value
is true
, the allocator is overwritten, if not the copied elements are created using the existing allocator.
Requires: |
|
Move Assignment
unordered_multimap& operator=(unordered_multimap&& other)
noexcept(boost::allocator_traits<Allocator>::is_always_equal::value &&
boost::is_nothrow_move_assignable_v<Hash> &&
boost::is_nothrow_move_assignable_v<Pred>);
The move assignment operator.
If Alloc::propagate_on_container_move_assignment
exists and Alloc::propagate_on_container_move_assignment::value
is true
, the allocator is overwritten, if not the moved elements are created using the existing allocator.
Requires: |
|
Initializer List Assignment
unordered_multimap& operator=(std::initializer_list<value_type> il);
Assign from values in initializer list. All existing elements are either overwritten by the new elements or destroyed.
Requires: |
|
Iterators
begin
iterator begin() noexcept;
const_iterator begin() const noexcept;
Returns: |
An iterator referring to the first element of the container, or if the container is empty the past-the-end value for the container. |
end
iterator end() noexcept;
const_iterator end() const noexcept;
Returns: |
An iterator which refers to the past-the-end value for the container. |
Modifiers
emplace
template<class... Args> iterator emplace(Args&&... args);
Inserts an object, constructed with the arguments args
, in the container.
Requires: |
|
Returns: |
An iterator pointing to the inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
emplace_hint
template<class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
Inserts an object, constructed with the arguments args, in the container.
position
is a suggestion to where the element should be inserted.
Requires: |
|
Returns: |
An iterator pointing to the inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Copy Insert
iterator insert(const value_type& obj);
Inserts obj
in the container.
Requires: |
|
Returns: |
An iterator pointing to the inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Move Insert
iterator insert(value_type&& obj);
Inserts obj
in the container.
Requires: |
|
Returns: |
An iterator pointing to the inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Emplace Insert
template<class P> iterator insert(P&& obj);
Inserts an element into the container by performing emplace(std::forward<P>(value))
.
Only participates in overload resolution if std::is_constructible<value_type, P&&>::value
is true
.
Returns: |
An iterator pointing to the inserted element. |
Copy Insert with Hint
iterator insert(const_iterator hint, const value_type& obj);
Inserts obj
in the container.
hint
is a suggestion to where the element should be inserted.
Requires: |
|
Returns: |
An iterator pointing to the inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Move Insert with Hint
iterator insert(const_iterator hint, value_type&& obj);
Inserts obj
in the container.
hint
is a suggestion to where the element should be inserted.
Requires: |
|
Returns: |
An iterator pointing to the inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Emplace Insert with Hint
template<class P> iterator insert(const_iterator hint, P&& obj);
Inserts an element into the container by performing emplace_hint(hint, std::forward<P>(value))
.
Only participates in overload resolution if std::is_constructible<value_type, P&&>::value
is true
.
hint
is a suggestion to where the element should be inserted.
Returns: |
An iterator pointing to the inserted element. |
Notes: |
The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Insert Iterator Range
template<class InputIterator> void insert(InputIterator first, InputIterator last);
Inserts a range of elements into the container.
Requires: |
|
Throws: |
When inserting a single element, if an exception is thrown by an operation other than a call to |
Notes: |
Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Insert Initializer List
void insert(std::initializer_list<value_type> il);
Inserts a range of elements into the container.
Requires: |
|
Throws: |
When inserting a single element, if an exception is thrown by an operation other than a call to |
Notes: |
Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. |
Extract by Iterator
node_type extract(const_iterator position);
Removes the element pointed to by position
.
Returns: |
A |
Notes: |
A node extracted using this method can be inserted into a compatible |
Extract by Key
node_type extract(const key_type& k);
template<class K> node_type extract(K&& k);
Removes an element with key equivalent to k
.
Returns: |
A |
Throws: |
Only throws an exception if it is thrown by |
Notes: |
A node extracted using this method can be inserted into a compatible The |
Insert with node_handle
iterator insert(node_type&& nh);
If nh
is empty, has no effect.
Otherwise inserts the element owned by nh
.
Requires: |
|
Returns: |
If Otherwise returns an iterator pointing to the newly inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to |
Notes: |
Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. This can be used to insert a node extracted from a compatible |
Insert with Hint and node_handle
iterator insert(const_iterator hint, node_type&& nh);
If nh
is empty, has no effect.
Otherwise inserts the element owned by nh
.
hint
is a suggestion to where the element should be inserted.
Requires: |
|
Returns: |
If Otherwise returns an iterator pointing to the newly inserted element. |
Throws: |
If an exception is thrown by an operation other than a call to hasher the function has no effect. |
Notes: |
The standard is fairly vague on the meaning of the hint. But the only practical way to use it, and the only way that Boost.Unordered supports is to point to an existing element with the same key. Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor. Pointers and references to elements are never invalidated. This can be used to insert a node extracted from a compatible |
Erase by Position
iterator erase(iterator position);
iterator erase(const_iterator position);
Erase the element pointed to by position
.
Returns: |
The iterator following |
Throws: |
Only throws an exception if it is thrown by |
Notes: |
In older versions this could be inefficient because it had to search through several buckets to find the position of the returned iterator. The data structure has been changed so that this is no longer the case, and the alternative erase methods have been deprecated. |
Erase by Key
size_type erase(const key_type& k);
template<class K> size_type erase(K&& k);
Erase all elements with key equivalent to k
.
Returns: |
The number of elements erased. |
Throws: |
Only throws an exception if it is thrown by |
Notes: |
The |
Erase Range
iterator erase(const_iterator first, const_iterator last);
Erases the elements in the range from first
to last
.
Returns: |
The iterator following the erased elements - i.e. |
Throws: |
Only throws an exception if it is thrown by In this implementation, this overload doesn’t call either function object’s methods so it is no throw, but this might not be true in other implementations. |
quick_erase
void quick_erase(const_iterator position);
Erase the element pointed to by position
.
Throws: |
Only throws an exception if it is thrown by In this implementation, this overload doesn’t call either function object’s methods so it is no throw, but this might not be true in other implementations. |
Notes: |
This method was implemented because returning an iterator to the next element from erase was expensive, but the container has been redesigned so that is no longer the case. So this method is now deprecated. |
erase_return_void
void erase_return_void(const_iterator position);
Erase the element pointed to by position
.
Throws: |
Only throws an exception if it is thrown by In this implementation, this overload doesn’t call either function object’s methods so it is no throw, but this might not be true in other implementations. |
Notes: |
This method was implemented because returning an iterator to the next element from erase was expensive, but the container has been redesigned so that is no longer the case. So this method is now deprecated. |
swap
void swap(unordered_multimap& other)
noexcept(boost::allocator_traits<Allocator>::is_always_equal::value &&
boost::is_nothrow_swappable_v<Hash> &&
boost::is_nothrow_swappable_v<Pred>);
Swaps the contents of the container with the parameter.
If Allocator::propagate_on_container_swap
is declared and Allocator::propagate_on_container_swap::value
is true
then the containers' allocators are swapped. Otherwise, swapping with unequal allocators results in undefined behavior.
Throws: |
Doesn’t throw an exception unless it is thrown by the copy constructor or copy assignment operator of |
Notes: |
The exception specifications aren’t quite the same as the C++11 standard, as the equality predicate and hash function are swapped using their copy constructors. |
clear
void clear() noexcept;
Erases all elements in the container.
Postconditions: |
|
Throws: |
Never throws an exception. |
merge
template<class H2, class P2>
void merge(unordered_multimap<Key, T, H2, P2, Allocator>& source);
template<class H2, class P2>
void merge(unordered_multimap<Key, T, H2, P2, Allocator>&& source);
template<class H2, class P2>
void merge(unordered_map<Key, T, H2, P2, Allocator>& source);
template<class H2, class P2>
void merge(unordered_map<Key, T, H2, P2, Allocator>&& source);
Attempt to "merge" two containers by iterating source
and extracting all nodes in source
and inserting them into *this
.
Because source
can have a different hash function and key equality predicate, the key of each node in
source
is rehashed using this->hash_function()
and then, if required, compared using this->key_eq()
.
The behavior of this function is undefined if this->get_allocator() != source.get_allocator()
.
This function does not copy or move any elements and instead simply relocates the nodes from source
into *this
.
Notes: |
|
Lookup
find
iterator find(const key_type& k);
const_iterator find(const key_type& k) const;
template<class K>
iterator find(const K& k);
template<class K>
const_iterator find(const K& k) const;
template<typename CompatibleKey, typename CompatibleHash, typename CompatiblePredicate>
iterator find(CompatibleKey const& k, CompatibleHash const& hash,
CompatiblePredicate const& eq);
template<typename CompatibleKey, typename CompatibleHash, typename CompatiblePredicate>
const_iterator find(CompatibleKey const& k, CompatibleHash const& hash,
CompatiblePredicate const& eq) const;
Returns: |
An iterator pointing to an element with key equivalent to |
Notes: |
The templated overloads containing The |
count
size_type count(const key_type& k) const;
template<class K>
size_type count(const K& k) const;
Returns: |
The number of elements with key equivalent to |
Notes: |
The |
contains
bool contains(const key_type& k) const;
template<class K>
bool contains(const K& k) const;
Returns: |
A boolean indicating whether or not there is an element with key equal to |
Notes: |
The |
equal_range
std::pair<iterator, iterator> equal_range(const key_type& k);
std::pair<const_iterator, const_iterator> equal_range(const key_type& k) const;
template<class K>
std::pair<iterator, iterator> equal_range(const K& k);
template<class K>
std::pair<const_iterator, const_iterator> equal_range(const K& k) const;
Returns: |
A range containing all elements with key equivalent to |
Notes: |
The |
Bucket Interface
max_bucket_count
size_type max_bucket_count() const noexcept;
Returns: |
An upper bound on the number of buckets. |
bucket_size
size_type bucket_size(size_type n) const;
Requires: |
|
Returns: |
The number of elements in bucket |
bucket
size_type bucket(const key_type& k) const;
template<class K> size_type bucket(const K& k) const;
Returns: |
The index of the bucket which would contain an element with key |
Postconditions: |
The return value is less than |
Notes: |
The |
begin
local_iterator begin(size_type n);
const_local_iterator begin(size_type n) const;
Requires: |
|
Returns: |
A local iterator pointing the first element in the bucket with index |
end
local_iterator end(size_type n);
const_local_iterator end(size_type n) const;
Requires: |
|
Returns: |
A local iterator pointing the 'one past the end' element in the bucket with index |
Hash Policy
max_load_factor
float max_load_factor() const noexcept;
Returns: |
Returns the current maximum load factor. |
Set max_load_factor
void max_load_factor(float z);
Effects: |
Changes the container’s maximum load factor, using |
rehash
void rehash(size_type n);
Changes the number of buckets so that there are at least n
buckets, and so that the load factor is less than or equal to the maximum load factor. When applicable, this will either grow or shrink the bucket_count()
associated with the container.
When size() == 0
, rehash(0)
will deallocate the underlying buckets array.
Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated.
Throws: |
The function has no effect if an exception is thrown, unless it is thrown by the container’s hash function or comparison function. |
reserve
void reserve(size_type n);
Equivalent to a.rehash(ceil(n / a.max_load_factor()))
, or a.rehash(1)
if n > 0
and a.max_load_factor() == std::numeric_limits<float>::infinity()
.
Similar to rehash
, this function can be used to grow or shrink the number of buckets in the container.
Invalidates iterators, and changes the order of elements. Pointers and references to elements are not invalidated.
Throws: |
The function has no effect if an exception is thrown, unless it is thrown by the container’s hash function or comparison function. |
Deduction Guides
A deduction guide will not participate in overload resolution if any of the following are true:
-
It has an
InputIterator
template parameter and a type that does not qualify as an input iterator is deduced for that parameter. -
It has an
Allocator
template parameter and a type that does not qualify as an allocator is deduced for that parameter. -
It has a
Hash
template parameter and an integral type or a type that qualifies as an allocator is deduced for that parameter. -
It has a
Pred
template parameter and a type that qualifies as an allocator is deduced for that parameter.
A size_type
parameter type in a deduction guide refers to the size_type
member type of the
container type deduced by the deduction guide. Its default value coincides with the default value
of the constructor selected.
iter-value-type
template<class InputIterator> using iter-value-type = typename std::iterator_traits<InputIterator>::value_type; // exposition only
iter-key-type
template<class InputIterator> using iter-key-type = std::remove_const_t< std::tuple_element_t<0, iter-value-type<InputIterator>>>; // exposition only
iter-mapped-type
template<class InputIterator> using iter-mapped-type = std::tuple_element_t<1, iter-value-type<InputIterator>>; // exposition only
iter-to-alloc-type
template<class InputIterator> using iter-to-alloc-type = std::pair< std::add_const_t<std::tuple_element_t<0, iter-value-type<InputIterator>>>, std::tuple_element_t<1, iter-value-type<InputIterator>>>; // exposition only
Equality Comparisons
operator==
template<class Key, class T, class Hash, class Pred, class Alloc>
bool operator==(const unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
const unordered_multimap<Key, T, Hash, Pred, Alloc>& y);
Return true
if x.size() == y.size()
and for every equivalent key group in x
, there is a group in y
for the same key, which is a permutation (using operator==
to compare the value types).
Notes: |
Behavior is undefined if the two containers don’t have equivalent equality predicates. |
operator!=
template<class Key, class T, class Hash, class Pred, class Alloc>
bool operator!=(const unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
const unordered_multimap<Key, T, Hash, Pred, Alloc>& y);
Return false
if x.size() == y.size()
and for every equivalent key group in x
, there is a group in y
for the same key, which is a permutation (using operator==
to compare the value types).
Notes: |
Behavior is undefined if the two containers don’t have equivalent equality predicates. |
Swap
template<class Key, class T, class Hash, class Pred, class Alloc>
void swap(unordered_multimap<Key, T, Hash, Pred, Alloc>& x,
unordered_multimap<Key, T, Hash, Pred, Alloc>& y)
noexcept(noexcept(x.swap(y)));
Swaps the contents of x
and y
.
If Allocator::propagate_on_container_swap
is declared and Allocator::propagate_on_container_swap::value
is true
then the containers' allocators are swapped. Otherwise, swapping with unequal allocators results in undefined behavior.
Effects: |
|
Throws: |
Doesn’t throw an exception unless it is thrown by the copy constructor or copy assignment operator of |
Notes: |
The exception specifications aren’t quite the same as the C++11 standard, as the equality predicate and hash function are swapped using their copy constructors. |
erase_if
template<class K, class T, class H, class P, class A, class Predicate>
typename unordered_multimap<K, T, H, P, A>::size_type
erase_if(unordered_multimap<K, T, H, P, A>& c, Predicate pred);
Traverses the container c
and removes all elements for which the supplied predicate returns true
.
Returns: |
The number of erased elements. |
Notes: |
Equivalent to:
|
Serialization
unordered_multimap
s can be archived/retrieved by means of
Boost.Serialization using the API provided
by this library. Both regular and XML archives are supported.
Saving an unordered_multimap to an archive
Saves all the elements of an unordered_multimap
x
to an archive (XML archive) ar
.
Requires: |
|
Loading an unordered_multimap from an archive
Deletes all preexisting elements of an unordered_multimap
x
and inserts
from an archive (XML archive) ar
restored copies of the elements of the
original unordered_multimap
other
saved to the storage read by ar
.
Requires: |
|
Note: |
If the archive was saved using a release of Boost prior to Boost 1.84,
the configuration macro |
Saving an iterator/const_iterator to an archive
Saves the positional information of an iterator
(const_iterator
) it
to an archive (XML archive) ar
. it
can be and end()
iterator.
Requires: |
The |
Loading an iterator/const_iterator from an archive
Makes an iterator
(const_iterator
) it
point to the restored position of
the original iterator
(const_iterator
) saved to the storage read by
an archive (XML archive) ar
.
Requires: |
If |