documented P2363 overloads for unordered_flat_map

doc/unordered/unordered_flat_map.adoc

@@ -134,23 +134,31 @@ namespace boost {
       std::pair<iterator, bool> xref:#unordered_flat_map_try_emplace[try_emplace](const key_type& k, Args&&... args);
     template<class... Args>
       std::pair<iterator, bool> xref:#unordered_flat_map_try_emplace[try_emplace](key_type&& k, Args&&... args);
+    template<class K, class... Args>
+      std::pair<iterator, bool> xref:#unordered_flat_map_try_emplace[try_emplace](K&& k, Args&&... args);
     template<class... Args>
       iterator xref:#unordered_flat_map_try_emplace_with_hint[try_emplace](const_iterator hint, const key_type& k, Args&&... args);
     template<class... Args>
       iterator xref:#unordered_flat_map_try_emplace_with_hint[try_emplace](const_iterator hint, key_type&& k, Args&&... args);
+    template<class K, class... Args>
+      iterator xref:#unordered_flat_map_try_emplace_with_hint[try_emplace](const_iterator hint, K&& k, Args&&... args);
     template<class M>
       std::pair<iterator, bool> xref:#unordered_flat_map_insert_or_assign[insert_or_assign](const key_type& k, M&& obj);
     template<class M>
       std::pair<iterator, bool> xref:#unordered_flat_map_insert_or_assign[insert_or_assign](key_type&& k, M&& obj);
+    template<class K, class M>
+      std::pair<iterator, bool> xref:#unordered_flat_map_insert_or_assign[insert_or_assign](K&& k, M&& obj);
     template<class M>
       iterator xref:#unordered_flat_map_insert_or_assign_with_hint[insert_or_assign](const_iterator hint, const key_type& k, M&& obj);
     template<class M>
       iterator xref:#unordered_flat_map_insert_or_assign_with_hint[insert_or_assign](const_iterator hint, key_type&& k, M&& obj);
+    template<class K, class M>
+      iterator xref:#unordered_flat_map_insert_or_assign_with_hint[insert_or_assign](const_iterator hint, K&& k, M&& obj);
 
     void      xref:#unordered_flat_map_erase_by_position[erase](iterator position);
     void      xref:#unordered_flat_map_erase_by_position[erase](const_iterator position);
     size_type xref:#unordered_flat_map_erase_by_key[erase](const key_type& k);
-    template<class K> size_type xref:#unordered_flat_map_transparent_erase_by_key[erase](K&& k);
+    template<class K> size_type xref:#unordered_flat_map_erase_by_key[erase](K&& k);
     iterator  xref:#unordered_flat_map_erase_range[erase](const_iterator first, const_iterator last);
     void      xref:#unordered_flat_map_swap[swap](unordered_flat_map& other)
       noexcept(boost::allocator_traits<Allocator>::is_always_equal::value ||
@@ -189,8 +197,11 @@ namespace boost {
     // element access
     mapped_type& xref:#unordered_flat_map_operator[operator[+]+](const key_type& k);
     mapped_type& xref:#unordered_flat_map_operator[operator[+]+](key_type&& k);
+    template<class K> mapped_type& xref:#unordered_flat_map_operator[operator[+]+](K&& k);
     mapped_type& xref:#unordered_flat_map_at[at](const key_type& k);
     const mapped_type& xref:#unordered_flat_map_at[at](const key_type& k) const;
+    template<class K> mapped_type& xref:#unordered_flat_map_at[at](const K& k);
+    template<class K> const mapped_type& xref:#unordered_flat_map_at[at](const K& k) const;
 
     // bucket interface
     size_type xref:#unordered_flat_map_bucket_count[bucket_count]() const noexcept;
@@ -860,6 +871,8 @@ template<class... Args>
   std::pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
 template<class... Args>
   std::pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
+template<class K, class... Args>
+  std::pair<iterator, bool> try_emplace(K&& k, Args&&... args);
 ```
 
 Inserts a new node into the container if there is no existing element with key `k` contained within it.
@@ -876,15 +889,23 @@ if there is an element with an equivalent key; otherwise, the construction is of
 +
 --
 ```c++
+// first two overloads
 value_type(std::piecewise_construct,
            std::forward_as_tuple(boost::forward<Key>(k)),
            std::forward_as_tuple(boost::forward<Args>(args)...))
+
+// third overload
+value_type(std::piecewise_construct,
+           std::forward_as_tuple(boost::forward<K>(k)),
+           std::forward_as_tuple(boost::forward<Args>(args)...))
 ```
 
 unlike xref:#unordered_flat_map_emplace[emplace], which simply forwards all arguments to ``value_type``'s constructor.
 
 Can invalidate iterators pointers and references, 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.
+
 --
 
 ---
@@ -895,6 +916,8 @@ template<class... Args>
   iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
 template<class... Args>
   iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
+template<class K, class... Args>
+  iterator try_emplace(const_iterator hint, K&& k, Args&&... args);
 ```
 
 Inserts a new node into the container if there is no existing element with key `k` contained within it.
@@ -911,15 +934,23 @@ if there is an element with an equivalent key; otherwise, the construction is of
 +
 --
 ```c++
+// first two overloads
 value_type(std::piecewise_construct,
            std::forward_as_tuple(boost::forward<Key>(k)),
            std::forward_as_tuple(boost::forward<Args>(args)...))
+
+// third overload
+value_type(std::piecewise_construct,
+           std::forward_as_tuple(boost::forward<K>(k)),
+           std::forward_as_tuple(boost::forward<Args>(args)...))
 ```
 
 unlike xref:#unordered_flat_map_emplace_hint[emplace_hint], which simply forwards all arguments to ``value_type``'s constructor.
 
 Can invalidate iterators pointers and references, 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.
+
 --
 
 ---
@@ -930,6 +961,8 @@ template<class M>
   std::pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
 template<class M>
   std::pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
+template<class K, class M>
+  std::pair<iterator, bool> insert_or_assign(K&& k, M&& obj);
 ```
 
 Inserts a new element into the container or updates an existing one by assigning to the contained value.
@@ -938,9 +971,15 @@ If there is an element with key `k`, then it is updated by assigning `boost::for
 
 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]
@@ -948,7 +987,9 @@ Returns:;; The `bool` component of the return type is `true` if an insert took p
 +
 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 pointers and references, but only if the insert causes the load to be greater than the maximum load. +
+Notes:;; Can invalidate iterators pointers and references, 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.
 
 ---
 
@@ -958,6 +999,8 @@ template<class M>
   iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
 template<class M>
   iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);
+template<class K, class M>
+  iterator insert_or_assign(const_iterator hint, K&& k, M&& obj);
 ```
 
 Inserts a new element into the container or updates an existing one by assigning to the contained value.
@@ -966,9 +1009,15 @@ If there is an element with key `k`, then it is updated by assigning `boost::for
 
 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.
@@ -976,7 +1025,9 @@ value_type(std::piecewise_construct,
 [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, pointers and references, but only if the insert causes the load to be greater than the maximum load.
+Notes:;; Can invalidate iterators, pointers and references, 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.
 
 ---
 
@@ -998,28 +1049,15 @@ Throws:;; Nothing.
 ==== Erase by Key
 ```c++
 size_type erase(const key_type& 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`.
-
----
-
-==== Transparent Erase by Key
-```c++
 template<class K> size_type erase(K&& k);
 ```
 
 Erase all elements with key equivalent to `k`.
 
-This 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.
-
 [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.
 
 ---
 
@@ -1172,13 +1210,16 @@ Notes:;; The `template <typename K>` overloads only participate in overload reso
 ```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, pointers and references, but only if the insert causes the load to be greater than the maximum load.
+Notes:;; Can invalidate iterators, pointers and references, 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.
 
 ---
 
@@ -1186,11 +1227,14 @@ Notes:;; Can invalidate iterators, pointers and references, but only if the inse
 ```c++
 mapped_type& at(const key_type& k);
 const mapped_type& at(const key_type& k) const;
+template<class K> mapped_type& at(const K& k);
+template<class K> const mapped_type& at(const K& k) const;
 ```
 
 [horizontal]
 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.
 
 ---