Merge 2021-10 LWG Motion 13

P2077R3 Heterogeneous erasure overloads for associative containers

Author: tkoeppe

source/compatibility.tex

@@ -96,6 +96,29 @@
 std::format("{}", t.bit);       // ill-formed, previously returned \tcode{"0"}
 \end{codeblock}
 
+\rSec2[diff.cpp20.containers]{\ref{containers}: containers library}
+
+\diffref{associative.reqmts,unord.req}
+\change
+Heterogeneous \tcode{extract} and \tcode{erase} overloads
+for associative containers.
+\rationale
+Improve efficiency of erasing elements from associative containers.
+\effect
+Valid \CppXX{} code may fail to compile in this revision of \Cpp{}.
+For example:
+\begin{codeblock}
+struct B {
+  auto operator<=>(const B&) const = default;
+};
+
+struct D : private B {
+  void f(std::set<B, std::less<>>& s) {
+    s.erase(*this);             // ill formed; previously well-formed
+  }
+};
+\end{codeblock}
+
 \rSec1[diff.cpp17]{\Cpp{} and ISO \CppXVII{}}
 
 \rSec2[diff.cpp17.general]{General}

source/containers.tex

@@ -1720,6 +1720,16 @@
 \tcode{c(r, ke)} and \tcode{!c(ke, r)}, with \tcode{c(r, ke)} implying
 \tcode{!c(ke, r)}.
 \item
+\tcode{kx} is a value such that
+\begin{itemize}
+\item
+\tcode{a} is partitioned with respect to \tcode{c(r, rx)} and \tcode{!c(kx, r)},
+with \tcode{c(r, kx)} implying \tcode{!c(kx, r)}
+\item
+\tcode{kx} is not convertible to
+either \tcode{iterator} or \tcode{const_iterator},
+\end{itemize}
+\item
 \tcode{A} denotes the storage allocator used by \tcode{X}, if any, or \tcode{allocator<X::value_type>} otherwise,
 \item
 \tcode{m} denotes an allocator of a type convertible to \tcode{A},
@@ -2001,6 +2011,14 @@
  \tcode{node_type}. &
  $\log (\tcode{a.size()})$       \\ \rowsep
 
+\tcode{a_tran.\brk{}extract(\brk{}kx)}       &
+ \tcode{node_type}          &
+ \effects Removes the first element in the container with key \tcode{r}
+ such that \tcode{!c(r, kx) \&\& !c(kx, r)} is \tcode{true}.\br
+ \returns A \tcode{node_type} owning the element if found,
+ otherwise an empty \tcode{node_type}. &
+ $\log(\tcode{a_tran.size()})$       \\ \rowsep
+
 \tcode{a.\brk{}extract(\brk{}q)}              &
  \tcode{node_type}             &
  \effects Removes the element pointed to by \tcode{q}.\br
@@ -2030,6 +2048,13 @@
  \returns The number of erased elements.  &
  $\log (\tcode{a.size()}) + \tcode{a.count(k)}$       \\ \rowsep
 
+\tcode{a_tran.\brk{}erase(kx)}      &
+ \tcode{size_type}           &
+ \effects Erases all elements in the container with key \tcode{r}
+ such that \tcode{!c(r, kx) \&\& !c(kx, r)} is \tcode{true}.\br
+ \returns The number of erased elements.  &
+ $\log(\tcode{a_tran.size())} + \tcode{a_tran.count(kx)}$       \\ \rowsep
+
 \tcode{a.erase(q)}              &
  \tcode{iterator}               &
  \effects Erases the element pointed to by \tcode{q}.\br
@@ -2204,10 +2229,16 @@
 \pnum
 The member function templates
 \tcode{find}, \tcode{count}, \tcode{contains},
-\tcode{lower_bound}, \tcode{upper_bound}, and \tcode{equal_range}
+\tcode{lower_bound}, \tcode{upper_bound}, \tcode{equal_range},
+\tcode{erase}, and \tcode{extract}
 shall not participate in overload resolution unless
 the \grammarterm{qualified-id} \tcode{Compare::is_transparent} is valid
 and denotes a type\iref{temp.deduct}.
+Additionally, the member function templates \tcode{extract} and \tcode{erase}
+shall not participate in overload resolution if
+\tcode{is_convertible_v<K\&\&, iterator> || is_convertible_v<K\&\&, const_iterator>}
+is \tcode{true},
+where \tcode{K} is the type substituted as the first template argument.
 
 \pnum
 A deduction guide for an associative container shall not participate in overload resolution
@@ -2428,6 +2459,16 @@
   \end{itemize}
   where \tcode{r1} and \tcode{r2} are keys of elements in \tcode{a_tran},
 \item
+\tcode{kx} is a value such that
+  \begin{itemize}
+  \item \tcode{eq(r1, kx) == eq(kx, r1)},
+  \item \tcode{hf(r1) == hf(kx)} if \tcode{eq(r1, kx)} is \tcode{true},
+  \item \tcode{(eq(r1, kx) \&\& eq(r1, r2)) == eq(r2, kx)}, and
+  \item \tcode{kx} is not convertible to
+    either \tcode{iterator} or \tcode{const_iterator}
+  \end{itemize}
+  where \tcode{r1} and \tcode{r2} are keys of elements in \tcode{a_tran},
+\item
 \tcode{n} denotes a value of type \tcode{size_type},
 \item
 \tcode{z} denotes a value of type \tcode{float}, and
@@ -2813,6 +2854,13 @@
  \tcode{node_type}. &
  Average case \bigoh{1}, worst case \bigoh{\tcode{a.size()}}.  \\ \rowsep
 %
+\tcode{a_tran.\brk{}extract(kx)}              &
+ \tcode{node_type}             &
+ \effects Removes an element in the container with key equivalent to \tcode{kx}.\br
+ \returns A \tcode{node_type} owning the element if found,
+    otherwise an empty \tcode{node_type}. &
+ Average case \bigoh{1}, worst case \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}.  \\ \rowsep
+%
 \tcode{a.extract(q)}              &
  \tcode{node_type}             &
  \effects Removes the element pointed to by \tcode{q}.\br
@@ -2845,6 +2893,14 @@
     \bigoh{\tcode{a.size()}}.
 \\ \rowsep
 %
+\tcode{a_tran.\brk{}erase(kx)}
+&   \tcode{size_type}
+&   \effects Erases all elements with key equivalent to \tcode{kx}.\br
+    \returns The number of elements erased.
+&    Average case \bigoh{\tcode{a_tran.}\br{}\tcode{count(kx)}}, worst case
+    \bigoh{\tcode{a_tran.}\br{}\tcode{size()}}.
+\\ \rowsep
+%
 \tcode{a.erase(q)}
 &   \tcode{iterator}
 &   \effects Erases the element pointed to by \tcode{q}.\br
@@ -3126,12 +3182,18 @@
 
 \pnum
 The member function templates
-\tcode{find}, \tcode{count}, \tcode{equal_range}, and \tcode{contains}
+\tcode{find}, \tcode{count}, \tcode{equal_range}, \tcode{contains},
+\tcode{extract}, and \tcode{erase}
 shall not participate in overload resolution unless
 the \grammarterm{qualified-id}s
 \tcode{Pred::is_transparent} and
 \tcode{Hash::is_transparent}
 are both valid and denote types\iref{temp.deduct}.
+Additionally, the member function templates \tcode{extract} and \tcode{erase}
+shall not participate in overload resolution if
+\tcode{is_convertible_v<K\&\&, iterator> || is_convertible_v<K\&\&, const_iterator>}
+is \tcode{true},
+where \tcode{K} is the type substituted as the first template argument.
 
 \pnum
 A deduction guide for an unordered associative container shall not participate in overload resolution
@@ -6674,6 +6736,7 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     insert_return_type insert(node_type&& nh);
     iterator           insert(const_iterator hint, node_type&& nh);
 
@@ -6697,6 +6760,7 @@
     iterator  erase(iterator position);
     iterator  erase(const_iterator position);
     size_type erase(const key_type& x);
+    template<class K> size_type erase(K&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(map&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -7213,12 +7277,14 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     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& x);
+    template<class K> size_type erase(K&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(multimap&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -7513,12 +7579,14 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     insert_return_type 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& x);
+    template<class K> size_type erase(K&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(set&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -7787,12 +7855,14 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     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& x);
+    template<class K> size_type erase(K&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(multiset&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -8216,6 +8286,7 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     insert_return_type insert(node_type&& nh);
     iterator           insert(const_iterator hint, node_type&& nh);
 
@@ -8239,6 +8310,7 @@
     iterator  erase(iterator position);
     iterator  erase(const_iterator position);
     size_type erase(const key_type& k);
+    template<class K> size_type erase(K&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(unordered_map&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -8811,12 +8883,14 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     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&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(unordered_multimap&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -9176,12 +9250,14 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     insert_return_type 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&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(unordered_set&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&
@@ -9501,12 +9577,14 @@
 
     node_type extract(const_iterator position);
     node_type extract(const key_type& x);
+    template<class K> node_type extract(K&& x);
     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&& x);
     iterator  erase(const_iterator first, const_iterator last);
     void      swap(unordered_multiset&)
       noexcept(allocator_traits<Allocator>::is_always_equal::value &&

source/support.tex

@@ -562,6 +562,8 @@
 #define @\defnlibxname{cpp_lib_apply}@                             201603L // also in \libheader{tuple}
 #define @\defnlibxname{cpp_lib_array_constexpr}@                   201811L // also in \libheader{iterator}, \libheader{array}
 #define @\defnlibxname{cpp_lib_as_const}@                          201510L // also in \libheader{utility}
+#define @\defnlibxname{cpp_lib_associative_heterogeneous_erasure}@ 202110L
+  // also in \libheader{map}, \libheader{set}, \libheader{unordered_map}, \libheader{unordered_set}
 #define @\defnlibxname{cpp_lib_assume_aligned}@                    201811L // also in \libheader{memory}
 #define @\defnlibxname{cpp_lib_atomic_flag_test}@                  201907L // also in \libheader{atomic}
 #define @\defnlibxname{cpp_lib_atomic_float}@                      201711L // also in \libheader{atomic}