xref:#unordered_node_map_initializer_list_constructor[unordered_node_map](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());
xref:#unordered_node_map_bucket_count_constructor_with_allocator[unordered_node_map](size_type n, const allocator_type& a);
xref:#unordered_node_map_bucket_count_constructor_with_hasher_and_allocator[unordered_node_map](size_type n, const hasher& hf, const allocator_type& a);
template<class InputIterator>
xref:#unordered_node_map_iterator_range_constructor_with_bucket_count_and_allocator[unordered_node_map](InputIterator f, InputIterator l, size_type n, const allocator_type& a);
template<class InputIterator>
xref:#unordered_node_map_iterator_range_constructor_with_bucket_count_and_hasher[unordered_node_map](InputIterator f, InputIterator l, size_type n, const hasher& hf,
const allocator_type& a);
xref:#unordered_node_map_initializer_list_constructor_with_allocator[unordered_node_map](std::initializer_list<value_type> il, const allocator_type& a);
xref:#unordered_node_map_initializer_list_constructor_with_bucket_count_and_allocator[unordered_node_map](std::initializer_list<value_type> il, size_type n,
const allocator_type& a);
xref:#unordered_node_map_initializer_list_constructor_with_bucket_count_and_hasher_and_allocator[unordered_node_map](std::initializer_list<value_type> il, size_type n, const hasher& hf,
.2+|`std::pair<const Key, T>` must be https://en.cppreference.com/w/cpp/named_req/EmplaceConstructible[EmplaceConstructible^]
into the container from any `std::pair` object convertible to it, and it also must be
https://en.cppreference.com/w/cpp/named_req/Erasable[Erasable^] from the container.
|_T_
|_Hash_
|A unary function object type that acts a hash function for a `Key`. It takes a single argument of type `Key` and returns a value of type `std::size_t`.
|_Pred_
|A binary function object that induces an equivalence relation on values of type `Key`. It takes two arguments of type `Key` and returns a value of type `bool`.
|_Allocator_
|An allocator whose value type is the same as the container's value type.
`std::allocator_traits<Allocator>::pointer` and `std::allocator_traits<Allocator>::const_pointer`
must be convertible to/from `value_type*` and `const value_type*`, respectively.
|===
The element nodes of the container are held into an internal _bucket array_. A node is inserted into a bucket determined by the
hash code of its element, but if the bucket is already occupied (a _collision_), an available one in the vicinity of the
original position is used.
The size of the bucket array can be automatically increased by a call to `insert`/`emplace`, or as a result of calling
`rehash`/`reserve`. The _load factor_ of the container (number of elements divided by number of buckets) is never
greater than `max_load_factor()`, except possibly for small sizes where the implementation may decide to
allow for higher loads.
If `xref:hash_traits_hash_is_avalanching[hash_is_avalanching]<Hash>::value` is `true`, the hash function
is used as-is; otherwise, a bit-mixing post-processing stage is added to increase the quality of hashing
at the expense of extra computational cost.
---
=== Typedefs
[source,c++,subs=+quotes]
----
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`.
---
[source,c++,subs=+quotes]
----
typedef _implementation-defined_ const_iterator;
----
A constant iterator whose value type is `value_type`.
The iterator category is at least a forward iterator.
---
[source,c++,subs=+quotes]
----
typedef _implementation-defined_ node_type;
----
A class for holding extracted container elements, modelling
struct _insert_return_type_ // name is exposition only
{
Iterator position;
bool inserted;
NodeType node;
};
----
with `Iterator` = `iterator` and `NodeType` = `node_type`.
---
=== Constructors
==== Default Constructor
```c++
unordered_node_map();
```
Constructs an empty container using `hasher()` as the hash function,
`key_equal()` as the key equality predicate and `allocator_type()` as the allocator.
[horizontal]
Postconditions:;; `size() == 0`
Requires:;; If the defaults are used, `hasher`, `key_equal` and `allocator_type` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== Bucket Count Constructor
```c++
explicit unordered_node_map(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, and `a` as the allocator.
[horizontal]
Postconditions:;; `size() == 0`
Requires:;; If the defaults are used, `hasher`, `key_equal` and `allocator_type` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
Constructs an empty container with at least `n` buckets, using `hf` as the hash function, `eql` as the key equality predicate and `a` as the allocator, and inserts the elements from `[f, l)` into it.
[horizontal]
Requires:;; If the defaults are used, `hasher`, `key_equal` and `allocator_type` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
Constructs an empty container using `a` as the allocator, with the default hash function and key equality predicate and inserts the elements from `[f, l)` into it.
[horizontal]
Requires:;; `hasher`, `key_equal` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== Allocator Constructor
```c++
explicit unordered_node_map(Allocator const& a);
```
Constructs an empty container, using allocator `a`.
If `a == other.get_allocator()`, the element nodes of `other` are transferred directly to the new container;
otherwise, elements are moved-constructed from those of `other`. The hash function and predicate are moved-constructed
from `other`, and the allocator is copy-constructed from `a`.
---
==== Initializer List Constructor
[source,c++,subs="+quotes"]
----
unordered_node_map(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 and `a`, and inserts the elements from `il` into it.
[horizontal]
Requires:;; If the defaults are used, `hasher`, `key_equal` and `allocator_type` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== Bucket Count Constructor with Allocator
```c++
unordered_node_map(size_type n, allocator_type const& a);
```
Constructs an empty container with at least `n` buckets, using `hf` as the hash function, the default hash function and key equality predicate and `a` as the allocator.
[horizontal]
Postconditions:;; `size() == 0`
Requires:;; `hasher` and `key_equal` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== Bucket Count Constructor with Hasher and Allocator
```c++
unordered_node_map(size_type n, hasher const& hf, allocator_type const& a);
```
Constructs an empty container with at least `n` buckets, using `hf` as the hash function, the default key equality predicate and `a` as the allocator.
[horizontal]
Postconditions:;; `size() == 0`
Requires:;; `key_equal` needs to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== Iterator Range Constructor with Bucket Count and Allocator
[source,c++,subs="+quotes"]
----
template<class InputIterator>
unordered_node_map(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 and default hash function and key equality predicate, and inserts the elements from `[f, l)` into it.
[horizontal]
Requires:;; `hasher`, `key_equal` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== Iterator Range Constructor with Bucket Count and Hasher
[source,c++,subs="+quotes"]
----
template<class InputIterator>
unordered_node_map(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 inserts the elements from `[f, l)` into it.
[horizontal]
Requires:;; `key_equal` needs to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== initializer_list Constructor with Allocator
```c++
unordered_node_map(std::initializer_list<value_type> il, const allocator_type& a);
```
Constructs an empty container using `a` and default hash function and key equality predicate, and inserts the elements from `il` into it.
[horizontal]
Requires:;; `hasher` and `key_equal` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== initializer_list Constructor with Bucket Count and Allocator
```c++
unordered_node_map(std::initializer_list<value_type> il, size_type n, const allocator_type& a);
```
Constructs an empty container with at least `n` buckets, using `a` and default hash function and key equality predicate, and inserts the elements from `il` into it.
[horizontal]
Requires:;; `hasher` and `key_equal` need to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
==== initializer_list Constructor with Bucket Count and Hasher and Allocator
```c++
unordered_node_map(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 default key equality predicate,and inserts the elements from `il` into it.
[horizontal]
Requires:;; `key_equal` needs to be https://en.cppreference.com/w/cpp/named_req/DefaultConstructible[DefaultConstructible^].
---
=== Destructor
```c++
~unordered_node_map();
```
[horizontal]
Note:;; The destructor is applied to every element, and all memory is deallocated
The assignment operator. Destroys previously existing elements, copy-assigns the hash function and predicate from `other`,
copy-assigns the allocator from `other` if `Alloc::propagate_on_container_copy_assignment` exists and `Alloc::propagate_on_container_copy_assignment::value` is `true`,
and finally inserts copies of the elements of `other`.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/CopyInsertable[CopyInsertable^]
The move assignment operator. Destroys previously existing elements, swaps the hash function and predicate from `other`,
and move-assigns the allocator from `other` if `Alloc::propagate_on_container_move_assignment` exists and `Alloc::propagate_on_container_move_assignment::value` is `true`.
If at this point the allocator is equal to `other.get_allocator()`, the internal bucket array of `other` is transferred directly to the new container;
otherwise, inserts move-constructed copies of the elements of `other`.
Inserts `obj` in the container if and only if there is no element in the container with an equivalent key.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/CopyInsertable[CopyInsertable^].
Returns:;; The `bool` component of the return type is `true` if an insert took place. +
+
If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
A call of the form `insert(x)`, where `x` is equally convertible to both `const value_type&` and `const init_type&`, is not ambiguous and selects the `init_type` overload.
Inserts `obj` in the container if and only if there is no element in the container with an equivalent key.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/MoveInsertable[MoveInsertable^].
Returns:;; The `bool` component of the return type is `true` if an insert took place. +
+
If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
A call of the form `insert(x)`, where `x` is equally convertible to both `value_type&&` and `init_type&&`, is not ambiguous and selects the `init_type` overload.
Inserts `obj` in the container if and only if there is no element in the container with an equivalent key.
`hint` is a suggestion to where the element should be inserted. This implementation ignores it.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/CopyInsertable[CopyInsertable^].
Returns:;; The `bool` component of the return type is `true` if an insert took place. +
+
If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
A call of the form `insert(hint, x)`, where `x` is equally convertible to both `const value_type&` and `const init_type&`, is not ambiguous and selects the `init_type` overload.
Inserts `obj` in the container if and only if there is no element in the container with an equivalent key.
`hint` is a suggestion to where the element should be inserted. This implementation ignores it.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/MoveInsertable[MoveInsertable^].
Returns:;; The `bool` component of the return type is `true` if an insert took place. +
+
If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
A call of the form `insert(hint, x)`, where `x` is equally convertible to both `value_type&&` and `init_type&&`, is not ambiguous and selects the `init_type` overload.
Inserts a range of elements into the container. Elements are inserted if and only if there is no element in the container with an equivalent key.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/EmplaceConstructible[EmplaceConstructible^] into the container from `*first`.
Throws:;; When inserting a single element, if an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load.
---
==== Insert Initializer List
```c++
void insert(std::initializer_list<value_type>);
```
Inserts a range of elements into the container. Elements are inserted if and only if there is no element in the container with an equivalent key.
[horizontal]
Requires:;; `value_type` is https://en.cppreference.com/w/cpp/named_req/EmplaceConstructible[EmplaceConstructible^] into the container from `*first`.
Throws:;; When inserting a single element, if an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load.
---
==== Insert Node
```c++
insert_return_type insert(node_type&& nh);
```
If `nh` is not empty, inserts the associated element in the container if and only if there is no element in the container with a key equivalent to `nh.key()`.
`nh` is empty when the function returns.
[horizontal]
Returns:;; An `insert_return_type` object constructed from `position`, `inserted` and `node`: +
* If `nh` is empty, `inserted` is `false`, `position` is `end()`, and `node` is empty.
* Otherwise if the insertion took place, `inserted` is true, `position` points to the inserted element, and `node` is empty.
* If the insertion failed, `inserted` is false, `node` has the previous value of `nh`, and `position` points to an element with a key equivalent to `nh.key()`.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Behavior is undefined if `nh` is not empty and the allocators of `nh` and the container are not equal.
If `nh` is not empty, inserts the associated element in the container if and only if there is no element in the container with a key equivalent to `nh.key()`.
`nh` becomes empty if insertion took place, otherwise it is not changed.
`hint` is a suggestion to where the element should be inserted. This implementation ignores it.
[horizontal]
Returns:;; The iterator returned is `end()` if `nh` is empty.
If insertion took place, then the iterator points to the newly inserted element; otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Behavior is undefined if `nh` is not empty and the allocators of `nh` and the container are not equal.
unlike xref:#unordered_node_map_emplace[emplace], which simply forwards all arguments to ``value_type``'s constructor.
Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load.
The `template <class K, class... Args>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs and neither `iterator` nor `const_iterator` are implicitly convertible from `K`. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
unlike xref:#unordered_node_map_emplace_hint[emplace_hint], which simply forwards all arguments to ``value_type``'s constructor.
Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load.
The `template <class K, class... Args>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs and neither `iterator` nor `const_iterator` are implicitly convertible from `K`. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
Inserts a new element into the container or updates an existing one by assigning to the contained value.
If there is an element with key `k`, then it is updated by assigning `boost::forward<M>(obj)`.
If there is no such element, it is added to the container as:
```c++
// first two overloads
value_type(std::piecewise_construct,
std::forward_as_tuple(boost::forward<Key>(k)),
std::forward_as_tuple(boost::forward<M>(obj)))
// third overload
value_type(std::piecewise_construct,
std::forward_as_tuple(boost::forward<K>(k)),
std::forward_as_tuple(boost::forward<M>(obj)))
```
[horizontal]
Returns:;; The `bool` component of the return type is `true` if an insert took place. +
+
If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
The `template<class K, class M>` only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
Inserts a new element into the container or updates an existing one by assigning to the contained value.
If there is an element with key `k`, then it is updated by assigning `boost::forward<M>(obj)`.
If there is no such element, it is added to the container as:
```c++
// first two overloads
value_type(std::piecewise_construct,
std::forward_as_tuple(boost::forward<Key>(k)),
std::forward_as_tuple(boost::forward<M>(obj)))
// third overload
value_type(std::piecewise_construct,
std::forward_as_tuple(boost::forward<K>(k)),
std::forward_as_tuple(boost::forward<M>(obj)))
```
`hint` is a suggestion to where the element should be inserted. This implementation ignores it.
[horizontal]
Returns:;; If an insert took place, then the iterator points to the newly inserted element. Otherwise, it points to the element with equivalent key.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
The `template<class K, class M>` only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
---
==== Erase by Position
```c++
void erase(iterator position);
void erase(const_iterator position);
```
Erase the element pointed to by `position`.
[horizontal]
Throws:;; Nothing.
---
==== Erase by Key
```c++
size_type erase(const key_type& k);
template<class K> size_type erase(K&& k);
```
Erase all elements with key equivalent to `k`.
[horizontal]
Returns:;; The number of elements erased.
Throws:;; Only throws an exception if it is thrown by `hasher` or `key_equal`.
Notes:;; The `template<class K>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs and neither `iterator` nor `const_iterator` are implicitly convertible from `K`. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
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.
[horizontal]
Throws:;; Nothing unless `key_equal` or `hasher` throw on swapping.
---
==== Extract by Position
```c++
node_type extract(const_iterator position);
```
Extracts the element pointed to by `position`.
[horizontal]
Returns:;; A `node_type` object holding the extracted element.
Throws:;; Nothing.
---
==== Extract by Key
```c++
node_type erase(const key_type& k);
template<class K> node_type erase(K&& k);
```
Extracts the element with key equivalent to `k`, if it exists.
[horizontal]
Returns:;; A `node_type` object holding the extracted element, or empty if no element was extracted.
Throws:;; Only throws an exception if it is thrown by `hasher` or `key_equal`.
Notes:;; The `template<class K>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs and neither `iterator` nor `const_iterator` are implicitly convertible from `K`. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
Transfers all the element nodes from `source` whose key is not already present in `*this`.
---
=== Observers
==== get_allocator
```
allocator_type get_allocator() const noexcept;
```
[horizontal]
Returns:;; The container's allocator.
---
==== hash_function
```
hasher hash_function() const;
```
[horizontal]
Returns:;; The container's hash function.
---
==== key_eq
```
key_equal key_eq() const;
```
[horizontal]
Returns:;; The container's key equality predicate
---
=== Lookup
==== find
```c++
iterator find(const key_type& k);
const_iterator find(const key_type& k) const;
template<class K>
iterator find(const K& k);
```
[horizontal]
Returns:;; An iterator pointing to an element with key equivalent to `k`, or `end()` if no such element exists.
Notes:;; The `template <typename K>` overloads only participate in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
---
==== count
```c++
size_type count(const key_type& k) const;
template<class K>
size_type count(const K& k) const;
```
[horizontal]
Returns:;; The number of elements with key equivalent to `k`.
Notes:;; The `template <typename K>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
---
==== contains
```c++
bool contains(const key_type& k) const;
template<class K>
bool contains(const K& k) const;
```
[horizontal]
Returns:;; A boolean indicating whether or not there is an element with key equal to `key` in the container
Notes:;; The `template <typename K>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
Returns:;; A range containing all elements with key equivalent to `k`. If the container doesn't contain any such elements, returns `std::make_pair(b.end(), b.end())`.
Notes:;; The `template <typename K>` overloads only participate in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
---
==== operator++[++++]++
```c++
mapped_type& operator[](const key_type& k);
mapped_type& operator[](key_type&& k);
template<class K> mapped_type& operator[](K&& k);
```
[horizontal]
Effects:;; If the container does not already contain an element with a key equivalent to `k`, inserts the value `std::pair<key_type const, mapped_type>(k, mapped_type())`.
Returns:;; A reference to `x.second` where `x` is the element already in the container, or the newly inserted element with a key equivalent to `k`.
Throws:;; If an exception is thrown by an operation other than a call to `hasher` the function has no effect.
Notes:;; Can invalidate iterators, but only if the insert causes the load to be greater than the maximum load. +
+
The `template<class K>` overload only participates in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
Returns:;; A reference to `x.second` where `x` is the (unique) element whose key is equivalent to `k`.
Throws:;; An exception object of type `std::out_of_range` if no such element is present.
Notes:;; The `template<class K>` overloads only participate in overload resolution if `Hash::is_transparent` and `Pred::is_transparent` are valid member typedefs. The library assumes that `Hash` is callable with both `K` and `Key` and that `Pred` is transparent. This enables heterogeneous lookup which avoids the cost of instantiating an instance of the `Key` type.
---
=== Bucket Interface
==== bucket_count
```c++
size_type bucket_count() const noexcept;
```
[horizontal]
Returns:;; The size of the bucket array.
---
=== Hash Policy
==== load_factor
```c++
float load_factor() const noexcept;
```
[horizontal]
Returns:;; `static_cast<float>(size())/static_cast<float>(bucket_count())`, or `0` if `bucket_count() == 0`.
---
==== max_load_factor
```c++
float max_load_factor() const noexcept;
```
[horizontal]
Returns:;; Returns the container's maximum load factor.
---
==== Set max_load_factor
```c++
void max_load_factor(float z);
```
[horizontal]
Effects:;; Does nothing, as the user is not allowed to change this parameter. Kept for compatibility with `boost::unordered_map`.
---
==== max_load
```c++
size_type max_load() const noexcept;
```
[horizontal]
Returns:;; The maximum number of elements the container can hold without rehashing, assuming that no further elements will be erased.
Note:;; After construction, rehash or clearance, the container's maximum load is at least `max_load_factor() * bucket_count()`.
This number may decrease on erasure under high-load conditions.
---
==== rehash
```c++
void rehash(size_type n);
```
Changes if necessary the size of the bucket array 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.
[horizontal]
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
```c++
void reserve(size_type n);
```
Equivalent to `a.rehash(ceil(n / a.max_load_factor()))`.
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.
[horizontal]
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__
[listings,subs="+macros,+quotes"]
-----
template<class InputIterator>
using __iter-value-type__ =
typename std::iterator_traits<InputIterator>::value_type; // exposition only
-----
==== __iter-key-type__
[listings,subs="+macros,+quotes"]
-----
template<class InputIterator>
using __iter-key-type__ = std::remove_const_t<
std::tuple_element_t<0, xref:#unordered_map_iter_value_type[__iter-value-type__]<InputIterator>>>; // exposition only
-----
==== __iter-mapped-type__
[listings,subs="+macros,+quotes"]
-----
template<class InputIterator>
using __iter-mapped-type__ =
std::tuple_element_t<1, xref:#unordered_map_iter_value_type[__iter-value-type__]<InputIterator>>; // exposition only
Return `true` if `x.size() == y.size()` and for every element in `x`, there is an element in `y` with the same key, with an equal value (using `operator==` to compare the value types).
[horizontal]
Notes:;; Behavior is undefined if the two containers don't have equivalent equality predicates.
---
==== operator!=
```c++
template<class Key, class T, class Hash, class Pred, class Alloc>
Return `false` if `x.size() == y.size()` and for every element in `x`, there is an element in `y` with the same key, with an equal value (using `operator==` to compare the value types).
[horizontal]
Notes:;; Behavior is undefined if the two containers don't have equivalent equality predicates.
=== Swap
```c++
template<class Key, class T, class Hash, class Pred, class Alloc>
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.
[horizontal]
Effects:;; `x.swap(y)`
Throws:;; Nothing unless `key_equal` or `hasher` throw on swapping.
---
=== erase_if
```c++
template<class K, class T, class H, class P, class A, class Predicate>
