home | help 
std::saturate_cast(3)	       C++ Standard Libary	   std::saturate_cast(3)

NAME
     std::saturate_cast - std::saturate_cast

Synopsis
	Defined in header <numeric>
	template< class T, class U >		    (since C++26)
	constexpr T saturate_cast( U x ) noexcept;

	Converts  the value x to a value of type T, clamping x between the mini-
     mum and
	maximum values of type T.

	It is a compile-time error if either T or U is not a signed or	unsigned
     integer type
	(including standard integer type and extended integer type).

Parameters
	x - an integer value

Return value
	  * x, if x is representable as a value of type T. Otherwise,
	  *  either  the  largest  or  smallest  representable	value of type T,
     whichever is
	    closer to the value of x.

Exceptions
	Throws no exceptions.

Notes
	      Feature-test macro	 Value	  Std	       Feature
	__cpp_lib_saturation_arithmetic 202311L (C++26) Saturation arithmetic

Possible implementation
	See libstdc++ (gcc).

Example
	Can be previewed on Compiler Explorer.

     // Run this code

      #include <cstdint>
      #include <limits>
      #include <numeric>

      int main()
      {
	  constexpr std::int16_t x1{696};

	  constexpr std::int8_t x2 = std::saturate_cast<std::int8_t>(x1);
	  static_assert(x2 == std::numeric_limits<std::int8_t>::max());

	  constexpr std::uint8_t x3 = std::saturate_cast<std::uint8_t>(x1);
	  static_assert(x3 == std::numeric_limits<std::uint8_t>::max());

	  constexpr std::int16_t y1{-696};

	  constexpr std::int8_t y2 = std::saturate_cast<std::int8_t>(y1);
	  static_assert(y2 == std::numeric_limits<std::int8_t>::min());

	  constexpr std::uint8_t y3 = std::saturate_cast<std::uint8_t>(y1);
	  static_assert(y3 == 0);
      }

See also
	bit_cast reinterpret the object representation of one type  as	that  of
     another
	(C++20)  (function template)
	clamp	 clamps a value between a pair of boundary values
	(C++17)  (function template)
	in_range  checks  if an integer value is in the range of a given integer
     type
	(C++20)  (function template)

http://cppreference.com 	   2024.06.10		   std::saturate_cast(3)
home | help