#include <stdint.h>
#include <avr-fast-shift.h>
#include <avr-fast-div.h>
#include "unit_testing.h"

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

Macros
#define	DIV_ROUND_DOWN -1
	Rounding behavior: always round down.

#define	DIV_ROUND_UP 1
	Rounding behavior: always round up.

#define	DIV_ROUND_NEAREST 0
	Rounding behavior: round to nearest.

#define	DIV_ROUND_BEHAVIOR DIV_ROUND_NEAREST
	Integer division rounding behavior.

#define	DIV_ROUND_CORRECT(d, t) ((t)(((d)>>1U)+(t)DIV_ROUND_BEHAVIOR))
	Computes the denominator correction for rounding division based on our rounding behavior.

#define	DIV_ROUND_CLOSEST(n, d, t)
	Rounded integer division.

#define	UDIV_ROUND_CLOSEST(n, d, t) ((t)((n) + DIV_ROUND_CORRECT(d, t))/(t)(d))
	Rounded unsigned integer division.

#define	UDIV_ROUND_UP(n, d, t) ((t)((n) + (t)((d)+1U))/(t)(d))
	Rounding up unsigned integer division.

#define	IS_INTEGER(d) ((d) == (int32_t)(d))
	Test whether the parameter is an integer or not.

#define	TEST_AND_APPLY(precision)

Functions
uint8_t	random1to100 (void) noexcept

uint16_t	pwmFreqToTicks (uint16_t frequency)
	Convert a frequency in Hz to the equivalent number of PWM timer ticks.

template<uint16_t divisor>
TESTABLE_STATIC_CONSTEXPR uint16_t	div_round_closest_u16 (uint16_t n)
	Rounded unsigned integer division optimized for compile time constants.

static uint32_t	div360 (uint32_t n)
	Optimised integer division by 360.

template<uint8_t b>
static uint32_t	rshift_round (uint32_t a)
	Rounded arithmetic right shift.

static uint32_t	percentageApprox (uint16_t percent, uint32_t value)
	Integer based percentage calculation: faster, but less accurate, than percentage()

static uint32_t	percentageApprox (uint8_t percent, uint32_t value) noexcept
	Slightly faster version of percentageApprox(uint16_t, uint32_t), since we know percent<256.

static uint32_t	percentage (uint16_t percent, uint32_t value)
	Integer based percentage calculation.

static uint16_t	halfPercentage (uint8_t percent, uint16_t value)
	Integer based half-percentage calculation.

static int16_t	nudge (int16_t min, int16_t max, int16_t value, int16_t nudgeAmount)
	Make one pass at correcting the value into the range [min, max)

template<typename TDividend , typename TDivisor >
TESTABLE_STATIC_CONSTEXPR TDividend	fast_div_closest (TDividend dividend, TDivisor divisor)
	Same as fast_div(), except this will round to nearest integer instead of truncating.

template<class T >
TESTABLE_STATIC_CONSTEXPR const T &	clamp (const T &v, const T &lo, const T &hi)
	clamps a given value between the minimum and maximum thresholds.

static uint16_t	LOW_PASS_FILTER (uint16_t input, uint8_t alpha, uint16_t prior)
	Simple low pass IIR filter 16-bit values.

static int16_t	LOW_PASS_FILTER (int16_t input, uint8_t alpha, int16_t prior)
	Simple low pass IIR filter for S16 values.

static uint8_t	scale (const uint8_t from, const uint8_t fromRange, const uint8_t toRange)
	Scale a value from one range to another.

static uint8_t	fast_map (const uint8_t from, const uint8_t fromLow, const uint8_t fromHigh, const uint8_t toLow, const uint8_t toHigh)
	Specialist version of map(long, long, long, long, long) for performance.


static uint16_t	div100 (uint16_t n)
	Performance optimised integer division by 100. I.e. same as n/100.

static int16_t	div100 (int16_t n)
	Performance optimised integer division by 100. I.e. same as n/100.

static uint32_t	div100 (uint32_t n)
	Performance optimised integer division by 100. I.e. same as n/100.

static int32_t	div100 (int32_t n)
	Performance optimised integer division by 100. I.e. same as n/100.

Variables
static constexpr uint32_t	MICROS_PER_SEC = UINT32_C(1000000)
	Self-explanatory.

static constexpr uint32_t	MICROS_PER_MIN = MICROS_PER_SEC*60U
	Self-explanatory.

static constexpr uint32_t	MICROS_PER_HOUR = MICROS_PER_MIN*60U
	Self-explanatory.

static constexpr uint32_t	MILLI_PER_SEC = MICROS_PER_SEC/1000
	Self-explanatory.

static constexpr uint8_t	ONE_HUNDRED_PCT = 100U
	This is only here to eliminate magic numbers.

Macro Definition Documentation

◆ IS_INTEGER

#define IS_INTEGER ( d ) ((d) == (int32_t)(d))

Test whether the parameter is an integer or not.

◆ TEST_AND_APPLY

#define TEST_AND_APPLY ( precision )

Value:

        if (percent<(UINT16_C(1)<<(UINT16_C(16)-(precision)))) { \
            return _percentageApprox<(precision)>(percent, value); \
        }

Function Documentation

◆ clamp()

template<class T >

TESTABLE_STATIC_CONSTEXPR const T & clamp	(	const T &	v,
		const T &	lo,
		const T &	hi
	)

clamps a given value between the minimum and maximum thresholds.

Uses operator< to compare the values.

Template Parameters

T	Any type that supports operator<

Parameters

v	The value to clamp
lo	The minimum threshold
hi	The maximum threshold

Returns: if v compares less than lo, returns lo; otherwise if hi compares less than v, returns hi; otherwise returns v.

Here is the caller graph for this function:

◆ div100() [1/4]

static int16_t div100 ( int16_t n )

inlinestatic

Performance optimised integer division by 100. I.e. same as n/100.

Uses the rounding behaviour controlled by DIV_ROUND_BEHAVIOR

Parameters

n	Dividend to divide by 100

Returns: n/100, with rounding behavior applied

Here is the call graph for this function:

◆ div100() [2/4]

static int32_t div100 ( int32_t n )

inlinestatic

Performance optimised integer division by 100. I.e. same as n/100.

Uses the rounding behaviour controlled by DIV_ROUND_BEHAVIOR

Parameters

n	Dividend to divide by 100

Returns: n/100, with rounding behavior applied

Here is the call graph for this function:

◆ div100() [3/4]

static uint16_t div100 ( uint16_t n )

inlinestatic

Performance optimised integer division by 100. I.e. same as n/100.

Uses the rounding behaviour controlled by DIV_ROUND_BEHAVIOR

Parameters

n	Dividend to divide by 100

Returns: n/100, with rounding behavior applied

Here is the call graph for this function:

Here is the caller graph for this function:

◆ div100() [4/4]

static uint32_t div100 ( uint32_t n )

inlinestatic

Performance optimised integer division by 100. I.e. same as n/100.

Uses the rounding behaviour controlled by DIV_ROUND_BEHAVIOR

Parameters

n	Dividend to divide by 100

Returns: n/100, with rounding behavior applied

Here is the call graph for this function:

◆ div360()

static uint32_t div360 ( uint32_t n )

inlinestatic

Optimised integer division by 360.

Parameters

n	The numerator (dividee) (an integer)

Returns: uint32_t

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fast_div_closest()

template<typename TDividend , typename TDivisor >

TESTABLE_STATIC_CONSTEXPR TDividend fast_div_closest	(	TDividend	dividend,
		TDivisor	divisor
	)

Same as fast_div(), except this will round to nearest integer instead of truncating.

Minor performance drop compared to non-rounding version.

Here is the caller graph for this function:

◆ fast_map()

static uint8_t fast_map	(	const uint8_t	from,
		const uint8_t	fromLow,
		const uint8_t	fromHigh,
		const uint8_t	toLow,
		const uint8_t	toHigh
	)

inlinestatic

Specialist version of map(long, long, long, long, long) for performance.

Maps a value from one range to another.

Warning: from must be within the range [fromLow, fromHigh].

Parameters

from	Value to map [fromLow, fromHigh]
fromLow	Lower bound of the from range
fromHigh	Upper bound of the from range
toLow	Lower bound of the to range
toHigh	Upper bound of the to range

Returns: uint8_t Mapped value in the new range [toLow, toHigh]

Here is the call graph for this function:

◆ halfPercentage()

static uint16_t halfPercentage	(	uint8_t	percent,
		uint16_t	value
	)

inlinestatic

Integer based half-percentage calculation.

Parameters

percent	The percent to calculate ([0, 100])
value	The value to operate on

Returns: uint16_t

Here is the call graph for this function:

Here is the caller graph for this function:

◆ LOW_PASS_FILTER() [1/2]

static int16_t LOW_PASS_FILTER	(	int16_t	input,
		uint8_t	alpha,
		int16_t	prior
	)

inlinestatic

Simple low pass IIR filter for S16 values.

◆ LOW_PASS_FILTER() [2/2]

static uint16_t LOW_PASS_FILTER	(	uint16_t	input,
		uint8_t	alpha,
		uint16_t	prior
	)

inlinestatic

Simple low pass IIR filter 16-bit values.

This is effectively implementing the smooth filter from playground.arduino.cc/Main/Smooth But removes the use of floats and uses 8 bits of fixed precision.

Parameters

input	incoming unfiltered value
alpha	filter factor. 0=off, 255=full smoothing (0.00 to 0.99 in float, 0-99%)
prior	previous filtered value.

Returns: uint16_t The filtered input

Here is the caller graph for this function:

◆ nudge()

static int16_t nudge	(	int16_t	min,
		int16_t	max,
		int16_t	value,
		int16_t	nudgeAmount
	)

inlinestatic

Make one pass at correcting the value into the range [min, max)

Parameters

min	Minimum value (inclusive)
max	Maximum value (exclusive)
value	Value to nudge
nudgeAmount	Amount to change value by

Returns: int16_t

Here is the caller graph for this function:

◆ percentage()

static uint32_t percentage	(	uint16_t	percent,
		uint32_t	value
	)

inlinestatic

Integer based percentage calculation.

Parameters

percent	The percent to apply to value
value	The value to operate on

Here is the call graph for this function:

Here is the caller graph for this function:

◆ percentageApprox() [1/2]

static uint32_t percentageApprox	(	uint16_t	percent,
		uint32_t	value
	)

inlinestatic

Integer based percentage calculation: faster, but less accurate, than percentage()

Recommended use case is when dealing with percentages >50%.

Parameters

percent	The percent to apply to value
value	The value to operate on

Note

Performance unit test shows a 33% speed improvement over percentage(). However, accuracy decreases as the percentage decreases, compared to percentage():

Percent	Maximum Error	Example
1%-6%	9%	`percentage(4, 563)` -> 23
1%-6%	9%	`percentageApprox(4, 563)` -> 21
7%-40%	1%	`percentage(10, 1806)` -> 181
7%-40%	1%	`percentageApprox(10, 1806)` -> 179
41%+	<0.3%	`percentage(79, 2371)` -> 1873
41%+	<0.3%	`percentageApprox(79, 2371)` -> 1870

Here is the caller graph for this function:

◆ percentageApprox() [2/2]

static uint32_t percentageApprox	(	uint8_t	percent,
		uint32_t	value
	)

inlinestaticnoexcept

Slightly faster version of percentageApprox(uint16_t, uint32_t), since we know percent<256.

◆ pwmFreqToTicks()

uint16_t pwmFreqToTicks ( uint16_t frequency )

Convert a frequency in Hz to the equivalent number of PWM timer ticks.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ random1to100()

uint8_t random1to100 ( void )

noexcept

◆ rshift_round()

template<uint8_t b>

static uint32_t rshift_round ( uint32_t a )

inlinestatic

Rounded arithmetic right shift.

Right shifting throws away bits. When use for fixed point division, this effectively rounds down (towards zero). To round-to-the-nearest-integer when right-shifting by S, just add in 2 power b−1 (which is the fixed-point equivalent of 0.5) first

Template Parameters

b	number of bits to shift by

Parameters

a	value to shift

Returns: uint32_t

◆ scale()

static uint8_t scale	(	const uint8_t	from,
		const uint8_t	fromRange,
		const uint8_t	toRange
	)

inlinestatic

Scale a value from one range to another.

Takes a value from a range of [0, fromRange] and scales it to a range of [0, toRange].

Warning: from must be within the range [0, fromRange].

Parameters

from	Value to scale [0, fromRange]
fromRange	Zero based range of the from value
toRange	Zero based range of the to value

Returns: uint8_t from scaled to toRange

Here is the caller graph for this function:

Variable Documentation

◆ MICROS_PER_HOUR

constexpr uint32_t MICROS_PER_HOUR = MICROS_PER_MIN*60U

staticconstexpr

Self-explanatory.

◆ MICROS_PER_MIN

constexpr uint32_t MICROS_PER_MIN = MICROS_PER_SEC*60U

staticconstexpr

Self-explanatory.

◆ MICROS_PER_SEC

constexpr uint32_t MICROS_PER_SEC = UINT32_C(1000000)

staticconstexpr

Self-explanatory.

◆ MILLI_PER_SEC

constexpr uint32_t MILLI_PER_SEC = MICROS_PER_SEC/1000

staticconstexpr

Self-explanatory.

◆ ONE_HUNDRED_PCT

constexpr uint8_t ONE_HUNDRED_PCT = 100U

staticconstexpr

This is only here to eliminate magic numbers.

DO NOT USE UNLESS YOU REALLY ARE WORKING IN PERCENTAGES - it will be very confusing for maintainers (which is what we are trying to avoid!)

Macros

Functions

Variables

Macro Definition Documentation

◆ IS_INTEGER

◆ TEST_AND_APPLY

Function Documentation

◆ clamp()

◆ div100() [1/4]

◆ div100() [2/4]

◆ div100() [3/4]

◆ div100() [4/4]

◆ div360()

◆ fast_div_closest()

◆ fast_map()

◆ halfPercentage()

◆ LOW_PASS_FILTER() [1/2]

◆ LOW_PASS_FILTER() [2/2]

◆ nudge()

◆ percentage()

◆ percentageApprox() [1/2]

◆ percentageApprox() [2/2]

◆ pwmFreqToTicks()

◆ random1to100()

◆ rshift_round()

◆ scale()

Variable Documentation

◆ MICROS_PER_HOUR

◆ MICROS_PER_MIN

◆ MICROS_PER_SEC

◆ MILLI_PER_SEC

◆ ONE_HUNDRED_PCT