added pull to open-addressing containers (#309)

* added pull to open-addressing containers

* added pull_tests.cpp

* guarded pull against exceptions in mid init_type construction

doc/modules/ROOT/pages/changes.adoc

@@ -6,6 +6,11 @@
 :github-pr-url: https://github.com/boostorg/unordered/pull
 :cpp: C++
 
+== Release 1.89.0
+
+* Added `pull(const_iterator)` to open-addressing containers. This operation
+allows for efficient removal and retrieval of an element via move construction.
+
 == Release 1.88.0
 
 * Migrated the documentation to a multipage format using Antora.

doc/modules/ROOT/pages/reference/unordered_flat_map.adoc

@@ -168,6 +168,7 @@ namespace unordered {
     void      xref:#unordered_flat_map_swap[swap](unordered_flat_map& other)
       noexcept(boost::allocator_traits<Allocator>::is_always_equal::value ||
                boost::allocator_traits<Allocator>::propagate_on_container_swap::value);
+    init_type xref:#unordered_flat_map_pull[pull](const_iterator position);
     void      xref:#unordered_flat_map_clear[clear]() noexcept;
 
     template<class H2, class P2>
@@ -1126,6 +1127,16 @@ Throws:;; Nothing unless `key_equal` or `hasher` throw on swapping.
 
 ---
 
+==== pull
+```c++
+init_type pull(const_iterator position);
+```
+
+Move-constructs an `init_value` `x` from the element pointed to by `position`,
+erases the element and returns `x`.
+
+---
+
 ==== clear
 ```c++
 void clear() noexcept;

doc/modules/ROOT/pages/reference/unordered_flat_set.adoc

@@ -135,6 +135,7 @@ namespace unordered {
     void      xref:#unordered_flat_set_swap[swap](unordered_flat_set& other)
       noexcept(boost::allocator_traits<Allocator>::is_always_equal::value ||
                boost::allocator_traits<Allocator>::propagate_on_container_swap::value);
+    init_type xref:#unordered_flat_set_pull[pull](const_iterator position);
     void      xref:#unordered_flat_set_clear[clear]() noexcept;
 
     template<class H2, class P2>
@@ -932,6 +933,16 @@ Throws:;; Nothing unless `key_equal` or `hasher` throw on swapping.
 
 ---
 
+==== pull
+```c++
+init_type pull(const_iterator position);
+```
+
+Move-constructs an `init_value` `x` from the element pointed to by `position`,
+erases the element and returns `x`.
+
+---
+
 ==== clear
 ```c++
 void clear() noexcept;

doc/modules/ROOT/pages/reference/unordered_node_map.adoc

@@ -172,6 +172,7 @@ namespace unordered {
     node_type xref:#unordered_node_map_extract_by_position[extract](const_iterator position);
     node_type xref:#unordered_node_map_extract_by_key[extract](const key_type& key);
     template<class K> node_type xref:#unordered_node_map_extract_by_key[extract](K&& key);
+    init_type xref:#unordered_node_map_pull[pull](const_iterator position);
     void      xref:#unordered_node_map_clear[clear]() noexcept;
 
     template<class H2, class P2>
@@ -1224,6 +1225,16 @@ Notes:;; The `template<class K>` overload only participates in overload resoluti
 
 ---
 
+==== pull
+```c++
+init_type pull(const_iterator position);
+```
+
+Move-constructs an `init_value` `x` from the element pointed to by `position`,
+erases the element and returns `x`.
+
+---
+
 ==== clear
 ```c++
 void clear() noexcept;

doc/modules/ROOT/pages/reference/unordered_node_set.adoc

@@ -140,6 +140,7 @@ namespace unordered {
     node_type xref:#unordered_node_set_extract_by_position[extract](const_iterator position);
     node_type xref:#unordered_node_set_extract_by_key[extract](const key_type& key);
     template<class K> node_type xref:#unordered_node_set_extract_by_key[extract](K&& key);
+    init_type xref:#unordered_node_set_pull[pull](const_iterator position);
     void      xref:#unordered_node_set_clear[clear]() noexcept;
 
     template<class H2, class P2>
@@ -1034,6 +1035,16 @@ Notes:;; The `template<class K>` overload only participates in overload resoluti
 
 ---
 
+==== pull
+```c++
+init_type pull(const_iterator position);
+```
+
+Move-constructs an `init_value` `x` from the element pointed to by `position`,
+erases the element and returns `x`.
+
+---
+
 ==== clear
 ```c++
 void clear() noexcept;