<numeric> Support

Saturating arithmetic avoids the possibility of overflow or underflow by clamping the value to a defined range should either of these situations occur. This means that on overflow the function returns the type’s maximum, and on underflow it returns the type’s minimum (0 for uint256). The following functions are provided for saturating arithmetic, and they do not require C++26.

Multiplication is where a 256-bit type overflows most easily: the product of any two values at or above 2¹²⁸ does not fit, and saturating_mul returns the maximum (or, for a negative signed product, the minimum) for those instead of the wrapped value.

An unsigned quotient is never larger than the dividend, so the uint256 overload of saturating_div cannot overflow and returns the same result as the plain operator/. For the signed overload the only value that can overflow is BOOST_INT256_INT256_MIN / -1, which saturates to BOOST_INT256_INT256_MAX; every other non-zero divisor gives the same result as the plain operator/. Division by zero is a precondition violation and therefore undefined behavior (the divisor must be non-zero), exactly as for the plain division operator; saturating_div adds no zero-divisor check.

See the saturating arithmetic example for a program that exercises every function above, ending with the int256 overloads and BOOST_INT256_INT256_MIN / -1.

This function converts a uint256 or int256 to a TargetType, saturating rather than wrapping when the value is out of the target’s range. TargetType is constrained (via SFINAE) to the library’s set of reduced integer types: the standard signed and unsigned integer types (excluding bool and plain char), uint256, int256, and the compiler’s native 128-bit integer types where available. Should the TargetType not be able to represent the value it is set to either std::numeric_limits<TargetType>::max() or std::numeric_limits<TargetType>::min() depending on whether the situation is overflow or underflow.

This is the safe counterpart of the implicit conversion operators, which keep the low bits instead. See also in_range, which reports whether the value would fit without converting it. saturating_cast(uint256_max) saturates to BOOST_INT256_INT256_MAX, and saturating_cast(int256_min) saturates to 0, since a negative source has no representable unsigned value below it.

Computes the greatest common divisor of the magnitudes of a and b.

Returns 0 when both a and b are 0; otherwise returns the greatest common divisor of abs(a) and abs(b), which is non-negative. In particular, gcd(a, 0) returns abs(a) and gcd(0, b) returns abs(b). This matches the results of std::gcd for every operand whose magnitude is representable in the result type. Both overloads are noexcept and usable in a constant expression.

Computes the least common multiple of the magnitudes of a and b.

Returns 0 when either a or b is 0; otherwise returns the least common multiple of abs(a) and abs(b). This matches the results of std::lcm for every operand whose magnitude, and whose least common multiple, is representable in the result type. Both overloads are noexcept and usable in a constant expression.

Computes the midpoint of a and b, rounding towards a.

The sum is never formed, so midpoint cannot overflow: midpoint(max, max - 10) is correct for both signs, while (a + b) / 2 at that magnitude is not. That is what makes it usable as the step of a binary search over the whole range of the type; see the numeric algorithms example, which also covers the signed overload, including a midpoint spanning zero (midpoint(int256{-100}, int256{100}) == 0).

operator/ only ever rounds towards zero. These functions divide with each of the other rounding modes, and are the 256-bit counterparts of the std::div_* family proposed for the standard library by wg21.link/p3724[P3724 (Integer division)]. They do not require C++26, and every one of them is constexpr and available on device.