pw_numeric

Oveview

Efficient mathematical utilities for embedded. Main docs: https://pigweed.dev/pw_numeric.

Functions
template<typename A , typename B , typename T >
constexpr bool	pw::CheckedAdd (A a, B b, T &result)
template<typename T , typename A , typename B >
constexpr std::optional< T >	pw::CheckedAdd (A a, B b)
template<typename T , typename Inc >
constexpr bool	pw::CheckedIncrement (T &base, Inc inc)
template<typename A , typename B , typename T >
constexpr bool	pw::CheckedSub (A a, B b, T &result)
template<typename T , typename A , typename B >
constexpr std::optional< T >	pw::CheckedSub (A a, B b)
template<typename T , typename Dec >
constexpr bool	pw::CheckedDecrement (T &base, Dec dec)
template<typename A , typename B , typename T >
constexpr bool	pw::CheckedMul (A a, B b, T &result)
template<typename T , typename A , typename B >
constexpr std::optional< T >	pw::CheckedMul (A a, B b)
template<typename T >
constexpr T	pw::IntegerDivisionRoundNearest (T dividend, T divisor)
template<typename T >
constexpr T	pw::add_sat (T lhs, T rhs) noexcept
template<typename T >
constexpr T	pw::mul_sat (T lhs, T rhs) noexcept

Function Documentation

add_sat()

template<typename T >

constexpr T pw::add_sat ( T  lhs, T  rhs  )

constexprnoexcept

Polyfill of C++26's std::add_sat. Returns the sum of two integers, giving the integer's maximum or minimum value if the sum would otherwise have overflowed.

For example, add_sat<uint8_t>(250, 6) returns 255 instead of the overflowed value (0).

CheckedAdd() [1/2]

template<typename T , typename A , typename B >

constexpr std::optional< T > pw::CheckedAdd ( A  a, B  b  )

constexpr

Adds two numbers, checking for overflow.

Template Parameters

T	The type of the result, which is checked for overflow.
A	The type of the first addend, a.
B	The type of the second addend, b.

Parameters

[in]	a	The first addend.
[in]	b	The second addend.

Returns

The sum (a + b) if addition was successful, or nullopt if the addition would overflow.

Note

The template argument must be provided, e.g. pw::CheckedAdd<uint32_t>(...).

CheckedAdd() [2/2]

template<typename A , typename B , typename T >

constexpr bool pw::CheckedAdd ( A  a, B  b, T &  result  )

constexpr

Adds two numbers, checking for overflow.

Template Parameters

A	The type of the first addend, a.
B	The type of the second addend, b.
T	The type of the result, which is checked for overflow.

Parameters

[in]	a	The first addend.
[in]	b	The second addend.
[out]	result	Reference to t

Returns

The sum (a + b) if addition was successful, or false if the addition would overflow and result is unmodified.

Note

The template argument must be provided, e.g. pw::CheckedAdd<uint32_t>(...).

CheckedDecrement()

template<typename T , typename Dec >

constexpr bool pw::CheckedDecrement ( T &  base, Dec  dec  )

constexpr

Decrements a variable by some amount.

Template Parameters

T	The type of the variable to be decremented.
Dec	The type of the variable to subtract.

Parameters

[in]	base	The variable to be decremented.
[in]	dec	The number to subtract from base.

Returns

True if the subtraction was successful and base was decremented (base -= dec); False if the subtraction would overflow and base is unmodified.

CheckedIncrement()

template<typename T , typename Inc >

constexpr bool pw::CheckedIncrement ( T &  base, Inc  inc  )

constexpr

Increments a variable by some amount.

Template Parameters

T	The type of the variable to be incremented.
Inc	The type of the variable to add.

Parameters

[in]	base	The variable to be incremented.
[in]	inc	The number to add to base.

Returns

True if the addition was successful and base was incremented (base += inc); False if the addition would overflow and base is unmodified.

CheckedMul() [1/2]

template<typename T , typename A , typename B >

constexpr std::optional< T > pw::CheckedMul ( A  a, B  b  )

constexpr

Multiplies two numbers, checking for overflow.

Template Parameters

T	The type of the result, which is checked for overflow.
A	The type of the first factor, a.
B	The type of the second factor, b.

Parameters

[in]	a	The first factor.
[in]	b	The second factor.

Returns

The product (a * b) if multiplication was successful, or nullopt if the multiplication would overflow.

Note

The template argument must be provided, e.g. pw::CheckedMul<uint32_t>(...).

CheckedMul() [2/2]

template<typename A , typename B , typename T >

constexpr bool pw::CheckedMul ( A  a, B  b, T &  result  )

constexpr

Multiplies two numbers, checking for overflow.

Template Parameters

A	The type of the first addend, a.
B	The type of the second addend, b.
T	The type of the result, which is checked for overflow.

Parameters

[in]	a	The first addend.
[in]	b	The second addend.
[out]	result	Reference to the result.

Returns

true if the multiplication was successful, false if it would overflow.

Note

The template argument must be provided, e.g. pw::CheckedMul<uint32_t>(...).

CheckedSub() [1/2]

template<typename T , typename A , typename B >

constexpr std::optional< T > pw::CheckedSub ( A  a, B  b  )

constexpr

Subtracts two numbers, checking for overflow.

Template Parameters

T	The type of the result, which is checked for overflow.
A	The type of the minuend, a.
B	The type of the subtrahend, b.

Parameters

[in]	a	The minuend (the number from which b is subtracted).
[in]	b	The subtrahend (the number subtracted from a).

Returns

The difference (a - b) if subtraction was successful, or nullopt if the subtraction would overflow.

Note

The template argument must be provided, e.g. pw::CheckedSub<uint32_t>(...).

CheckedSub() [2/2]

template<typename A , typename B , typename T >

constexpr bool pw::CheckedSub ( A  a, B  b, T &  result  )

constexpr

Subtracts two numbers, checking for overflow.

Template Parameters

A	The type of the first addend, a.
B	The type of the second addend, b.
T	The type of the result, which is checked for overflow.

Parameters

[in]	a	The first addend.
[in]	b	The second addend.
[out]	result	Reference to the result.

Returns

true if the subtraction was successful, false if it would overflow and result is unmodified.

Note

The template argument must be provided, e.g. pw::CheckedSub<uint32_t>(...).

IntegerDivisionRoundNearest()

template<typename T >

constexpr T pw::IntegerDivisionRoundNearest ( T  dividend, T  divisor  )

constexpr

Performs integer division and rounds to the nearest integer. Gives the same result as std::round(static_cast<double>(dividend) / static_cast<double>(divisor)), but requires no floating point operations and is constexpr.

embed:rst:leading-asterisk
 
*  .. warning::
* 
*     ``signed`` or ``unsigned`` ``int``, ``long``, or ``long long`` operands
*     overflow if:
* 
*     - the quotient is positive and ``dividend + divisor/2`` overflows, or
*     - the quotient is negative and ``dividend - divisor/2`` overflows.
* 
*     To avoid overflow, do not use this function with very large
*     operands, or cast ``int`` or ``long`` to a larger type first. Overflow
*     cannot occur with types smaller than ``int`` because C++ implicitly
*     converts them to ``int``.
*  

mul_sat()

template<typename T >

constexpr T pw::mul_sat ( T  lhs, T  rhs  )

constexprnoexcept

Polyfill of C++26's std::mul_sat. Returns the product of two integers, giving the integer's maximum or minimum value if the product would otherwise have overflowed.

For example, for 100 * 10 = 1000, mul_sat<uint8_t>(100, 10) returns 255 instead of the overflowed value (232).