Merge 2023-11 LWG Motion 2

P0543R3 Saturation arithmetic

Author: tkoeppe

source/algorithms.tex

@@ -9621,6 +9621,18 @@
     constexpr T midpoint(T a, T b) noexcept;
   template<class T>
     constexpr T* midpoint(T* a, T* b);
+
+  // \ref{numeric.sat}, saturation arithmetic
+  template<class T>
+    constexpr T add_sat(T x, T y) noexcept;                     // freestanding
+  template<class T>
+    constexpr T sub_sat(T x, T y) noexcept;                     // freestanding
+  template<class T>
+    constexpr T mul_sat(T x, T y) noexcept;                     // freestanding
+  template<class T>
+    constexpr T div_sat(T x, T y) noexcept;                     // freestanding
+  template<class T, class U>
+    constexpr T saturate_cast(U x) noexcept;                    // freestanding
 }
 \end{codeblock}
 
@@ -10755,6 +10767,119 @@
 where the result of the division is truncated towards zero.
 \end{itemdescr}
 
+\rSec2[numeric.sat]{Saturation arithmetic}
+
+\rSec3[numeric.sat.func]{Arithmetic functions}
+
+\pnum
+\begin{note}
+In the following descriptions, an arithmetic operation
+is performed as a mathematical operation with infinite range and then
+it is determined whether the mathematical result fits into the result type.
+\end{note}
+
+\indexlibraryglobal{add_sat}%
+\begin{itemdecl}
+template<class T>
+  constexpr T add_sat(T x, T y) noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\tcode{T} is a signed or unsigned integer type\iref{basic.fundamental}.
+
+\pnum
+\returns
+If $\tcode{x} + \tcode{y}$ is representable as a value of type \tcode{T}, $\tcode{x} + \tcode{y}$;
+otherwise, either the largest or smallest representable value of type \tcode{T},
+whichever is closer to the value of $\tcode{x} + \tcode{y}$.
+\end{itemdescr}
+
+\indexlibraryglobal{sub_sat}%
+\begin{itemdecl}
+template<class T>
+  constexpr T sub_sat(T x, T y) noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\tcode{T} is a signed or unsigned integer type\iref{basic.fundamental}.
+
+\pnum
+\returns
+If $\tcode{x} - \tcode{y}$ is representable as a value of type \tcode{T}, $\tcode{x} - \tcode{y}$;
+otherwise, either the largest or smallest representable value of type \tcode{T},
+whichever is closer to the value of $\tcode{x} - \tcode{y}$.
+\end{itemdescr}
+
+\indexlibraryglobal{mul_sat}%
+\begin{itemdecl}
+template<class T>
+  constexpr T mul_sat(T x, T y) noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\tcode{T} is a signed or unsigned integer type\iref{basic.fundamental}.
+
+\pnum
+\returns
+If $\tcode{x} \times \tcode{y}$ is representable as a value of type \tcode{T}, $\tcode{x} \times \tcode{y}$;
+otherwise, either the largest or smallest representable value of type \tcode{T},
+whichever is closer to the value of $\tcode{x} \times \tcode{y}$.
+\end{itemdescr}
+
+\indexlibraryglobal{div_sat}%
+\begin{itemdecl}
+template<class T>
+  constexpr T div_sat(T x, T y) noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\tcode{T} is a signed or unsigned integer type\iref{basic.fundamental}.
+
+\pnum
+\expects
+\tcode{y != 0} is \tcode{true}.
+
+\pnum
+\returns
+If \tcode{T} is a signed integer type
+and \tcode{x == numeric_limits<T>::min() \&\& y == -1} is \tcode{true},
+\tcode{numeric_limits<T>::max()}, otherwise, \tcode{x / y}.
+
+\pnum
+\remarks
+A function call expression
+that violates the precondition in the \Fundescx{Preconditions} element
+is not a core constant expression\iref{expr.const}.
+\end{itemdescr}
+
+\rSec3[numeric.sat.cast]{Casting}
+
+\indexlibraryglobal{saturate_cast}%
+\begin{itemdecl}
+template<class R, class T>
+  constexpr R saturate_cast(T x) noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\tcode{R} and \tcode{T} are signed or unsigned integer types\iref{basic.fundamental}.
+
+\pnum
+\returns
+If \tcode{x} is representable as a value of type \tcode{R}, \tcode{x};
+otherwise, either the largest or smallest representable value of type \tcode{R},
+whichever is closer to the value of \tcode{x}.
+\end{itemdescr}
+
 \rSec1[specialized.algorithms]{Specialized \tcode{<memory>} algorithms}
 
 \rSec2[specialized.algorithms.general]{General}

source/lib-intro.tex

@@ -1492,6 +1492,7 @@
 \ref{c.strings}          & Null-terminated sequence utilities & \tcode{<cstring>}, \tcode{<cwchar>} \\ \rowsep
 \ref{iterators}          & Iterators library         & \tcode{<iterator>}         \\ \rowsep
 \ref{ranges}             & Ranges library            & \tcode{<ranges>}           \\ \rowsep
+\ref{algorithms}         & Algorithms library        & \tcode{<numeric>}          \\ \rowsep
 \ref{c.math}             & Mathematical functions for floating-point types & \tcode{<cmath>} \\ \rowsep
 \ref{atomics}            & Atomics                   & \tcode{<atomic>}           \\ \rowsep
 \end{libsumtab}

source/support.tex

@@ -742,6 +742,7 @@
   // freestanding, also in \libheader{functional}, \libheader{type_traits}
 #define @\defnlibxname{cpp_lib_robust_nonmodifying_seq_ops}@       201304L // also in \libheader{algorithm}
 #define @\defnlibxname{cpp_lib_sample}@                            201603L // also in \libheader{algorithm}
+#define @\defnlibxname{cpp_lib_saturation_arithmetic}@             202311L // also in \libheader{numeric}
 #define @\defnlibxname{cpp_lib_scoped_lock}@                       201703L // also in \libheader{mutex}
 #define @\defnlibxname{cpp_lib_semaphore}@                         201907L // also in \libheader{semaphore}
 #define @\defnlibxname{cpp_lib_shared_mutex}@                      201505L // also in \libheader{shared_mutex}