P0646R1 Improving the return value of erase-like algorithms

Author: jwakely

source/compatibility.tex

@@ -2001,6 +2001,18 @@
 Valid \CppXVII{} code that \tcode{\#include}{s} headers with these names may be
 invalid in this International Standard.
 
+\rSec2[diff.cpp17.containers]{\ref{containers}: containers library}
+
+\diffrefs{forwardlist}{list}
+\change
+Return types of \tcode{remove}, \tcode{remove_if}, and \tcode{unique}
+changed from \tcode{void} to \tcode{container::size_type}.
+\rationale Improve efficiency and convenience of finding number of removed elements.
+\effect
+Code that depends on the return types might have different semantics in this International Standard.
+Translation units compiled against this version of \Cpp{} may be incompatible with
+translation units compiled against \CppXVII{}, either failing to link or having undefined behavior.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \rSec1[diff.library]{C standard library}
 \indextext{library!C standard}%

source/containers.tex

@@ -3883,11 +3883,11 @@
     void splice_after(const_iterator position, forward_list&& x,
                       const_iterator first, const_iterator last);
 
-    void remove(const T& value);
-    template<class Predicate> void remove_if(Predicate pred);
+    size_type remove(const T& value);
+    template<class Predicate> size_type remove_if(Predicate pred);
 
-    void unique();
-    template<class BinaryPredicate> void unique(BinaryPredicate binary_pred);
+    size_type unique();
+    template<class BinaryPredicate> size_type unique(BinaryPredicate binary_pred);
 
     void merge(forward_list& x);
     void merge(forward_list&& x);
@@ -4328,8 +4328,8 @@
 \indexlibrarymember{remove}{forward_list}%
 \indexlibrarymember{remove_if}{forward_list}%
 \begin{itemdecl}
-void remove(const T& value);
-template<class Predicate> void remove_if(Predicate pred);
+size_type remove(const T& value);
+template<class Predicate> size_type remove_if(Predicate pred);
 \end{itemdecl}
 
 \begin{itemdescr}
@@ -4339,6 +4339,9 @@
 \tcode{pred(*i)} is \tcode{true} (for \tcode{remove_if()}).
 Invalidates only the iterators and references to the erased elements.
 
+\pnum
+\returns The number of elements erased.
+
 \pnum
 \throws Nothing unless an exception is thrown by the equality comparison or the
 predicate.
@@ -4353,8 +4356,8 @@
 
 \indexlibrarymember{unique}{forward_list}%
 \begin{itemdecl}
-void unique();
-template<class BinaryPredicate> void unique(BinaryPredicate pred);
+size_type unique();
+template<class BinaryPredicate> size_type unique(BinaryPredicate pred);
 \end{itemdecl}
 
 \begin{itemdescr}
@@ -4365,6 +4368,9 @@
 *(i - 1))} (for the version with a predicate argument) holds.
 Invalidates only the iterators and references to the erased elements.
 
+\pnum
+\returns The number of elements erased.
+
 \pnum
 \throws Nothing unless an exception is thrown by the equality comparison or the predicate.
 
@@ -4574,12 +4580,12 @@
     void splice(const_iterator position, list& x, const_iterator first, const_iterator last);
     void splice(const_iterator position, list&& x, const_iterator first, const_iterator last);
 
-    void remove(const T& value);
-    template<class Predicate> void remove_if(Predicate pred);
+    size_type remove(const T& value);
+    template<class Predicate> size_type remove_if(Predicate pred);
 
-    void unique();
+    size_type unique();
     template<class BinaryPredicate>
-      void unique(BinaryPredicate binary_pred);
+      size_type unique(BinaryPredicate binary_pred);
 
     void merge(list& x);
     void merge(list&& x);
@@ -4961,8 +4967,8 @@
 
 \indexlibrary{\idxcode{remove}!\idxcode{list}}%
 \begin{itemdecl}
-void remove(const T& value);
-template<class Predicate> void remove_if(Predicate pred);
+size_type remove(const T& value);
+template<class Predicate> size_type remove_if(Predicate pred);
 \end{itemdecl}
 
 \begin{itemdescr}
@@ -4972,6 +4978,9 @@
 following conditions hold: \tcode{*i == value}, \tcode{pred(*i) != false}.
 Invalidates only the iterators and references to the erased elements.
 
+\pnum
+\returns The number of elements erased.
+
 \pnum
 \throws
 Nothing unless an exception is thrown by
@@ -4991,8 +5000,8 @@
 
 \indexlibrary{\idxcode{unique}!\idxcode{list}}%
 \begin{itemdecl}
-void unique();
-template<class BinaryPredicate> void unique(BinaryPredicate binary_pred);
+size_type unique();
+template<class BinaryPredicate> size_type unique(BinaryPredicate binary_pred);
 \end{itemdecl}
 
 \begin{itemdescr}
@@ -5005,6 +5014,9 @@
 \tcode{unique} with a predicate argument) holds.
 Invalidates only the iterators and references to the erased elements.
 
+\pnum
+\returns The number of elements erased.
+
 \pnum
 \throws
 Nothing unless an exception is thrown by