Detailed Description

Miscellaneous mathematical utility functions.

Trivial functions are defined inline for performance optimization. All others are defined in "utils.cc".

Definition in file utils.h.

#include <cstring>
#include <satcat5/types.h>

Include dependency graph for utils.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	satcat5::util::optional< T >
	An optional field that may be filled or empty. More...

class	satcat5::util::Prng
	Simple cross-platform psuedorandom number generator (PRNG). More...

class	satcat5::util::RunningMax
	Running maximum with label tracking. More...

Functions
template<typename T >
void	satcat5::util::set_mask_if (T &val, T mask, bool b)
	Call `set_mask` or `clr_mask` depending on the third argument.

template<typename T >
constexpr T	satcat5::util::mask_lower (unsigned n)
	Return a bit-mask where the N LSBs are set.

template<typename T >
T	satcat5::util::poll_counter (T &ct, bool reset=true)
	Poll a cumulative counter, optionally resetting it to zero.

template<typename T >
bool	satcat5::util::countdown (T &timer, const T &decr)
	Decrement a countdown timer, returning true if it reaches zero.

u32	satcat5::util::max_u32 (u32 a, u32 b, u32 c)
	Three-way max function.

template<typename T >
constexpr T	satcat5::util::clamp (T x, T y)
	Template "clamp" function. More...

template<typename T >
constexpr T	satcat5::util::sign (T x)
	Sign function (-x/0/+x -> -1/0/+1)

template<typename T >
unsigned	satcat5::util::log2_ceil (T x)
	Calculate log2(x), rounding up.

template<typename T >
unsigned	satcat5::util::log2_floor (T x)
	Calculate log2(x), rounding down.

template<typename T >
constexpr T	satcat5::util::saturate_add (T a, T b, T c=T(-1))
	Unsigned add with saturation: min(A + B, C). More...

constexpr double	satcat5::util::pow2d (unsigned n)
	Calculate 2^N for very large N, returning a double.

bool	satcat5::util::is_multiple_u32 (u32 a, u32 b)
	Check if A is a multiple of B:

unsigned	satcat5::util::popcount (u32 x)
	Count the number of '1' bits in an integer.

unsigned	satcat5::util::min_2n (u32 x, u32 y)
	Given X and Y, find the minimum N such that X * 2^N >= Y.

template<typename T >
void	satcat5::util::sort (T begin, T end)
	Templated in-place stable sort for small arrays. More...

template<typename T1 , typename T2 >
T2	satcat5::util::reinterpret (T1 x)
	In-place byte-for-byte format conversion, aka "type-punning".


void	satcat5::util::set_mask_u8 (volatile u8 &val, u8 mask)
	Set or clear bit masks.

void	satcat5::util::clr_mask_u8 (volatile u8 &val, u8 mask)
	Set or clear bit masks.

void	satcat5::util::set_mask_u8 (u8 &val, u8 mask)
	Set or clear bit masks.

void	satcat5::util::clr_mask_u8 (u8 &val, u8 mask)
	Set or clear bit masks.

void	satcat5::util::set_mask_u16 (u16 &val, u16 mask)
	Set or clear bit masks.

void	satcat5::util::clr_mask_u16 (u16 &val, u16 mask)
	Set or clear bit masks.

void	satcat5::util::set_mask_u32 (u32 &val, u32 mask)
	Set or clear bit masks.

void	satcat5::util::clr_mask_u32 (u32 &val, u32 mask)
	Set or clear bit masks.

template<typename T >
void	satcat5::util::clr_mask (T &val, T mask)
	Set or clear bit masks.

template<typename T >
void	satcat5::util::set_mask (T &val, T mask)
	Set or clear bit masks.


constexpr u8	satcat5::util::min_u8 (u8 a, u8 b)
	Min and max functions.

constexpr u16	satcat5::util::min_u16 (u16 a, u16 b)
	Min and max functions.

constexpr u32	satcat5::util::min_u32 (u32 a, u32 b)
	Min and max functions.

constexpr u64	satcat5::util::min_u64 (u64 a, u64 b)
	Min and max functions.

constexpr u32	satcat5::util::min_s32 (s32 a, s32 b)
	Min and max functions.

constexpr u64	satcat5::util::min_s64 (s64 a, s64 b)
	Min and max functions.

constexpr unsigned	satcat5::util::min_unsigned (unsigned a, unsigned b)
	Min and max functions.

constexpr u8	satcat5::util::max_u8 (u8 a, u8 b)
	Min and max functions.

constexpr u16	satcat5::util::max_u16 (u16 a, u16 b)
	Min and max functions.

constexpr u32	satcat5::util::max_u32 (u32 a, u32 b)
	Min and max functions.

constexpr u64	satcat5::util::max_u64 (u64 a, u64 b)
	Min and max functions.

constexpr u32	satcat5::util::max_s32 (s32 a, s32 b)
	Min and max functions.

constexpr u64	satcat5::util::max_s64 (s64 a, s64 b)
	Min and max functions.

constexpr unsigned	satcat5::util::max_unsigned (unsigned a, unsigned b)
	Min and max functions.


constexpr u8	satcat5::util::abs_s8 (s8 a)
	Absolute value.

constexpr u16	satcat5::util::abs_s16 (s16 a)
	Absolute value.

constexpr u32	satcat5::util::abs_s32 (s32 a)
	Absolute value.

constexpr u64	satcat5::util::abs_s64 (s64 a)
	Absolute value.


u32	satcat5::util::square_u16 (u16 x)
	Square an input (and double output width)

u32	satcat5::util::square_s16 (s16 x)
	Square an input (and double output width)


constexpr u16	satcat5::util::modulo_add_u16 (u16 sum, u16 m)
	Modulo addition function. More...

constexpr u32	satcat5::util::modulo_add_u32 (u32 sum, u32 m)
	Modulo addition function. More...

constexpr u32	satcat5::util::modulo_add_u64 (u64 sum, u64 m)
	Modulo addition function. More...

constexpr unsigned	satcat5::util::modulo_add_uns (unsigned sum, unsigned m)
	Modulo addition function. More...


template<typename T >
constexpr T	satcat5::util::divide (T a, T b)
	Portability wrapper for platforms with signed division and modulo: More...

template<typename T >
constexpr T	satcat5::util::modulo (T a, T b)
	Portability wrapper for platforms with signed division and modulo: More...


template<typename T >
constexpr s64	satcat5::util::round_s64 (T x)
	Round a floating-point value to the nearest integer. More...

template<typename T >
constexpr u64	satcat5::util::round_u64 (T x)
	Round a floating-point value to the nearest integer. More...


template<typename T >
constexpr u64	satcat5::util::round_s64z (T x)
	Variant of "round_u64" that returns zero if input is out of range.

template<typename T >
constexpr u64	satcat5::util::round_u64z (T x)
	Variant of "round_u64" that returns zero if input is out of range.


template<typename T >
constexpr T	satcat5::util::div_floor (T a, T b)
	Integer division functions with various rounding options:

template<typename T >
constexpr T	satcat5::util::div_round (T a, T b)
	Integer division functions with various rounding options:

template<typename T >
constexpr T	satcat5::util::div_ceil (T a, T b)
	Integer division functions with various rounding options:

constexpr u32	satcat5::util::div_floor_u32 (u32 a, u32 b)
	Integer division functions with various rounding options:

constexpr s32	satcat5::util::div_floor_s32 (s32 a, s32 b)
	Integer division functions with various rounding options:

constexpr u32	satcat5::util::div_round_u32 (u32 a, u32 b)
	Integer division functions with various rounding options:

constexpr s32	satcat5::util::div_round_s32 (s32 a, s32 b)
	Integer division functions with various rounding options:

constexpr u32	satcat5::util::div_ceil_u32 (u32 a, u32 b)
	Integer division functions with various rounding options:

constexpr s32	satcat5::util::div_ceil_s32 (s32 a, s32 b)
	Integer division functions with various rounding options:


constexpr u64	satcat5::util::reverse_bytes_u64 (u64 num)
	Reverse the order of bytes in an integer.

constexpr u32	satcat5::util::reverse_bytes_u32 (u32 num)
	Reverse the order of bytes in an integer.

constexpr u16	satcat5::util::reverse_bytes_u16 (u16 num)
	Reverse the order of bytes in an integer.


bool	satcat5::util::xor_reduce_u8 (u8 x)
	XOR-reduction of all bits in a word:

bool	satcat5::util::xor_reduce_u16 (u16 x)
	XOR-reduction of all bits in a word:

bool	satcat5::util::xor_reduce_u32 (u32 x)
	XOR-reduction of all bits in a word:

bool	satcat5::util::xor_reduce_u64 (u64 x)
	XOR-reduction of all bits in a word:


u32	satcat5::util::sqrt_u64 (u64 x)
	Find integer square root y = floor(sqrt(x))

u16	satcat5::util::sqrt_u32 (u32 x)
	Find integer square root y = floor(sqrt(x))

u8	satcat5::util::sqrt_u16 (u16 x)
	Find integer square root y = floor(sqrt(x))


u16	satcat5::util::extract_be_u16 (const u8 *src)
	Extract fields from a big-endian byte array.

u32	satcat5::util::extract_be_u32 (const u8 *src)
	Extract fields from a big-endian byte array.

u64	satcat5::util::extract_be_u64 (const u8 *src)
	Extract fields from a big-endian byte array.


void	satcat5::util::write_be_u16 (u8 *dst, u16 val)
	Store fields into a big-endian byte array.

void	satcat5::util::write_be_u32 (u8 *dst, u32 val)
	Store fields into a big-endian byte array.

void	satcat5::util::write_be_u64 (u8 *dst, u64 val)
	Store fields into a big-endian byte array.


template<typename T >
void	satcat5::util::swap_ptr (T x, T y)
	Swap two values using a temporary variable.

template<typename T >
void	satcat5::util::swap_ref (T &x, T &y)
	Swap two values using a temporary variable.

Variables
satcat5::util::Prng	satcat5::util::prng
	Global instance of the Prng class.

enum	{ SATCAT5_LITTLE_ENDIAN = 0x03020100ul , SATCAT5_BIG_ENDIAN = 0x00010203ul }
	Cross-platform determination of native byte-order. More...

union {
u8 bytes [4]

u32 value

}	satcat5::util::HOST_ORDER_CANARY = {{0,1,2,3}}
	Cross-platform determination of native byte-order. More...

constexpr u32	satcat5::util::HOST_BYTE_ORDER ()
	Cross-platform determination of native byte-order. More...

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Cross-platform determination of native byte-order.

https://stackoverflow.com/questions/2100331/ Usage: if (HOST_BYTE_ORDER() == SATCAT5_LITTLE_ENDIAN) {...}

Definition at line 408 of file utils.h.

Function Documentation

◆ clamp()

template<typename T >

constexpr T satcat5::util::clamp	(	T	x,
		T	y
	)

inlineconstexpr

Template "clamp" function.

For an input x, the "clamp" function limits the output range to +/- y. i.e., if abs(x) <= y then clamp(x) => x, else clamp(x) => sign(x)*y

Definition at line 136 of file utils.h.

◆ divide()

template<typename T >

constexpr T satcat5::util::divide	(	T	a,
		T	b
	)

inlineconstexpr

Portability wrapper for platforms with signed division and modulo:

Modulo always returns the positive equivalent: modulo(-7, 4) = +1 modulo(-6, 4) = +2 modulo(-5, 4) = +3 modulo(-4, 4) = 0
Divide always rounds toward -infinity: divide(-7, 4) = -2 divide(-6, 4) = -2 divide(-5, 4) = -2 divide(-4, 4) = -1 https://stackoverflow.com/questions/10023440/signed-division-in-c

Definition at line 200 of file utils.h.

◆ HOST_BYTE_ORDER()

constexpr u32 satcat5::util::HOST_BYTE_ORDER ( )

inlineconstexpr

Cross-platform determination of native byte-order.

https://stackoverflow.com/questions/2100331/ Usage: if (HOST_BYTE_ORDER() == SATCAT5_LITTLE_ENDIAN) {...}

Definition at line 410 of file utils.h.

◆ modulo()

template<typename T >

constexpr T satcat5::util::modulo	(	T	a,
		T	b
	)

inlineconstexpr

Portability wrapper for platforms with signed division and modulo:

Modulo always returns the positive equivalent: modulo(-7, 4) = +1 modulo(-6, 4) = +2 modulo(-5, 4) = +3 modulo(-4, 4) = 0
Divide always rounds toward -infinity: divide(-7, 4) = -2 divide(-6, 4) = -2 divide(-5, 4) = -2 divide(-4, 4) = -1 https://stackoverflow.com/questions/10023440/signed-division-in-c

Definition at line 203 of file utils.h.

◆ modulo_add_u16()

constexpr u16 satcat5::util::modulo_add_u16	(	u16	sum,
		u16	m
	)

inlineconstexpr

Modulo addition function.

Modulo addition: If A and B in range [0..M), return (A+B) % M (Note: Assumes M <= UINT_MAX/2 for respective word size.)

Definition at line 173 of file utils.h.

◆ modulo_add_u32()

constexpr u32 satcat5::util::modulo_add_u32	(	u32	sum,
		u32	m
	)

inlineconstexpr

Modulo addition function.

Modulo addition: If A and B in range [0..M), return (A+B) % M (Note: Assumes M <= UINT_MAX/2 for respective word size.)

Definition at line 176 of file utils.h.

◆ modulo_add_u64()

constexpr u32 satcat5::util::modulo_add_u64	(	u64	sum,
		u64	m
	)

inlineconstexpr

Modulo addition function.

Modulo addition: If A and B in range [0..M), return (A+B) % M (Note: Assumes M <= UINT_MAX/2 for respective word size.)

Definition at line 179 of file utils.h.

◆ modulo_add_uns()

constexpr unsigned satcat5::util::modulo_add_uns	(	unsigned	sum,
		unsigned	m
	)

inlineconstexpr

Modulo addition function.

Modulo addition: If A and B in range [0..M), return (A+B) % M (Note: Assumes M <= UINT_MAX/2 for respective word size.)

Definition at line 182 of file utils.h.

◆ round_s64()

template<typename T >

constexpr s64 satcat5::util::round_s64 ( T x )

inlineconstexpr

Round a floating-point value to the nearest integer.

Behavior at the boundary is indeterminate (e.g., 1.5 -> 1 or 2). Note: round() in cmath library isn't always marked as constexpr.

Definition at line 226 of file utils.h.

◆ round_u64()

template<typename T >

constexpr u64 satcat5::util::round_u64 ( T x )

inlineconstexpr

Round a floating-point value to the nearest integer.

Behavior at the boundary is indeterminate (e.g., 1.5 -> 1 or 2). Note: round() in cmath library isn't always marked as constexpr.

Definition at line 229 of file utils.h.

◆ saturate_add()

template<typename T >

constexpr T satcat5::util::saturate_add	(	T	a,
		T	b,
		T	c = `T(-1)`
	)

inlineconstexpr

Unsigned add with saturation: min(A + B, C).

If "C" is not specified, default to maximum representable value. (i.e., UINT32_MAX, UINT64_MAX, etc., equal to 2^N - 1.) This operation is nontrivial due to handling of integer overflow. This function is NOT suitable for use with signed integers.

Definition at line 250 of file utils.h.

◆ sort()

template<typename T >

void satcat5::util::sort	(	T *	begin,
		T *	end
	)

Templated in-place stable sort for small arrays.

Slower than std::sort(...) but does not require heap allocation.

Definition at line 357 of file utils.h.

Variable Documentation

◆

constexpr { ... } satcat5::util::HOST_ORDER_CANARY

Cross-platform determination of native byte-order.

https://stackoverflow.com/questions/2100331/ Usage: if (HOST_BYTE_ORDER() == SATCAT5_LITTLE_ENDIAN) {...}

Detailed Description

Classes

Functions

Variables

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ clamp()

◆ divide()

◆ HOST_BYTE_ORDER()

◆ modulo()

◆ modulo_add_u16()

◆ modulo_add_u32()

◆ modulo_add_u64()

◆ modulo_add_uns()

◆ round_s64()

◆ round_u64()

◆ saturate_add()

◆ sort()

Variable Documentation

◆