utils Namespace Reference

Contains all generic utility methods. More...

Classes
class	range
	Iterable class that can embed arrays or initializer lists through implicit conversion. More...

Enumerations
enum class	UnitPrefix : int8_t {   GIGA = 9 ,   MEGA = 6 ,   KILO = 3 ,   HECTO = 2 ,   DECA = 1 ,   NONE = 0 ,   DECI = -1 ,   CENTI = -2 ,   MILLI = -3 ,   MICRO = -6 ,   NANO = -9 }
	Common prefixes for measurement units. More...

Functions
template<typename T >
constexpr T	constrain (T value, T min, T max)
	Constrain value to be greater than or equal to min and lower than or equal to max.
template<typename TI , typename TO >
constexpr TO	map (TI value, TI input_min, TI input_max, TO output_min, TO output_max)
	Linearly transform value from range [input_min ; input_max] to range [output_min ; output_max].
template<typename T >
constexpr T	min (T a, T b)
	Compute the min of 2 integral values.
template<typename T >
constexpr T	max (T a, T b)
	Compute the max of 2 integral values.
constexpr uint32_t	power_of_10 (int8_t n)
	Calculate a power of 10 at compile-time, provided that n is a constant at call time.
constexpr int16_t	map_raw_to_physical (int16_t value, UnitPrefix prefix, int16_t range, uint8_t precision_bits)
	Convert the raw value, obtained from an electronics device, using precision_bit number of bits (that defines the input range) into a physical measure for which range defines the complete output range for such value, adjusted according to the unit prefix that we want in the resulting measure.
constexpr int16_t	map_physical_to_raw (int16_t value, UnitPrefix prefix, int16_t range, uint8_t precision_bits)
	Convert an absolute physical value, expressed in some given measurement unit, scaled with prefix, into a raw measurement as if obtained from a electronics device, using precision_bit number of bits (that defines the device raw measure range); for this device, physical measures are within range.
constexpr uint8_t	low_byte (uint16_t word)
	Extract the low order byte of a 16-bits word.
constexpr uint8_t	high_byte (uint16_t word)
	Extract the high order byte of a 16-bits word.
constexpr uint16_t	as_uint16_t (uint8_t high, uint8_t low)
	Convert 2 bytes into an unsigned int.
template<typename T >
constexpr T	is_zero (T value, T default_value)
	Replace value by default_value if not "true" (also known as "Elvis operator").
template<typename T >
void	set_mask (volatile T &reg, T mask, T value)
	Common utility to force a part of the value of a register, designated by a bit mask.
template<typename T >
constexpr bool	is_mask_equal (T actual, T mask, T expected)
	Common utility to check if 2 values are equal according to a mask.
uint8_t	bcd_to_binary (uint8_t bcd)
	Convert Binary-coded decimal byte (each nibble is a digit from 0 to 9) into a natural byte.
uint8_t	binary_to_bcd (uint8_t binary)
	Convert a natural integers to a BCD byte (2 digits).
void	swap_bytes (uint16_t &value)
	Swap 2 bytes of a 2-bytes integer.
void	swap_bytes (int16_t &value)
	Swap 2 bytes of a 2-bytes integer.
void	swap_bytes (uint32_t &value)
	Reverse 4 bytes of a 4-bytes integer.
void	swap_bytes (int32_t &value)
	Reverse 4 bytes of a 4-bytes integer.
void	swap_bytes (uint64_t &value)
	Reverse 8 bytes of a 8-bytes integer.
void	swap_bytes (int64_t &value)
	Reverse 8 bytes of a 8-bytes integer.
template<typename T >
void	swap (T &a, T &b)
	Swap the values of 2 variables passed by reference.
template<typename T >
constexpr uint8_t	as_uint8_t (T input)
	Cast a one byte long bit-fields struct into a byte.
template<typename T , typename U = uint8_t[sizeof(T)]>
constexpr void	as_array (const T &input, U output)
	Cast an instance of type T to an array of uint8_t of the size of T.
constexpr uint8_t	calculate_delay1_count (float time_us)
	Calculate the count to pass to delay1() in order to reach time_us microseconds delay.
constexpr uint8_t	num_bits (uint8_t mask, uint8_t num=0)
	Calculate the number of 1 bits in a byte.
template<typename T >
T	change_endianness (const T &value)
	Change endianness of any integral type (from big to small or small to big).

Detailed Description

Contains all generic utility methods.

Enumeration Type Documentation

UnitPrefix

enum class utils::UnitPrefix : int8_t

strong

Common prefixes for measurement units.

Used by map_raw_to_physical() and map_physical_to_raw() for units conversion. To avoid large arithmetic calculation, we limit these prefixes to power of 10 that can hold within 32 bits; this is why TERA or PICO are absent.

Definition at line 101 of file utilities.h.

Function Documentation

constrain()

template<typename T >

constexpr T utils::constrain ( T  value, T  min, T  max  )

constexpr

Constrain value to be greater than or equal to min and lower than or equal to max.

Template Parameters

T	the type of value (must be comparable: int, float...)

Parameters

value	the value to constrain
min	the minimum allowed value
max	the maximum allowed value

Returns

the value constrained to be between min and max

Definition at line 62 of file utilities.h.

map()

template<typename TI , typename TO >

constexpr TO utils::map ( TI  value, TI  input_min, TI  input_max, TO  output_min, TO  output_max  )

constexpr

Linearly transform value from range [input_min ; input_max] to range [output_min ; output_max].

Note that the transformed value is not explicitly constrained to range [output_min ; output_max], hence if you want it to be with that range, you should also use constrain() on the returned value.

Template Parameters

T0	the type of the target range and value
T1	the type of the source range and value

Parameters

value	the value to transform
input_min	the minimum value of the input range
input_max	the maximum value of the input range
output_min	the minimum value of the output range
output_max	the maximum value of the output range

Returns

transformed value

Definition at line 89 of file utilities.h.

min()

template<typename T >

constexpr T utils::min ( T  a, T  b  )

constexpr

Compute the min of 2 integral values.

Computations done by this method will be performed at compile-time as long as all provided arguments are constants; this is important as this will help optimize code size and execution time.

Template Parameters

T	the type of values to be compared

Parameters

a	first value
b	second value

Returns

constexpr T the minimum of a and b

Definition at line 127 of file utilities.h.

max()

template<typename T >

constexpr T utils::max ( T  a, T  b  )

constexpr

Compute the max of 2 integral values.

Computations done by this method will be performed at compile-time as long as all provided arguments are constants; this is important as this will help optimize code size and execution time.

Template Parameters

T	the type of values to be compared

Parameters

a	first value
b	second value

Returns

constexpr T the maximum of a and b

Definition at line 143 of file utilities.h.

power_of_10()

constexpr uint32_t utils::power_of_10 ( int8_t  n )

constexpr

Calculate a power of 10 at compile-time, provided that n is a constant at call time.

This is to avoid dragging huge mathematics libraries if this can be avoided.

Parameters

n	the power of exponent to apply to 10; if negative, then its absolute value is used instead.

Returns

10 ^ |n|

Definition at line 156 of file utilities.h.

map_raw_to_physical()

constexpr int16_t utils::map_raw_to_physical ( int16_t  value, UnitPrefix  prefix, int16_t  range, uint8_t  precision_bits  )

constexpr

Convert the raw value, obtained from an electronics device, using precision_bit number of bits (that defines the input range) into a physical measure for which range defines the complete output range for such value, adjusted according to the unit prefix that we want in the resulting measure.

This is useful when you need to display real measurement from raw values provided by a sensor. Note however, that in most cases, this method will be evaluated at runtime only, and thus will drag all arithmetic computation libraries. If you need to know the physical measure from a raw value, only to compare it against some constant physical value, then it is preferable to convert the latter, with map_raw_to_physical() which will be evaluated at compile time, and only compare raw values in your program: that will help decrease code size and improve code speed (no runtime conversions needed).

// This sample code use MPU6050 (accelerometer-gyroscope) support
using namespace devices::magneto;
using namespace utils;
// These are the accel and gyro ranges used in this code
static constexpr const GyroRange GYRO_RANGE = GyroRange::RANGE_250;
static constexpr const AccelRange ACCEL_RANGE = AccelRange::RANGE_2G;
 
// This function converts a raw gyro axis measure into centi-degrees per second
// so that it can be displayed to an LCD.
inline int16_t gyro(int16_t value)
{
    // GYRO_RANGE_DPS calculates the gyro maximum range (in degrees per second)
    // 15 is the number of bits of precision (on positive range only).
    return map_raw_to_physical(value, UnitPrefix::CENTI, GYRO_RANGE_DPS(GYRO_RANGE), 15);
}
 
// This function converts a raw accelerometer axis measure into milli-g
// so that it can be displayed to an LCD.
inline int16_t accel(int16_t value)
{
    // ACCEL_RANGE_G calculates the accel maximum range (in g)
    // 15 is the number of bits of precision (on positive range only).
    return map_raw_to_physical(value, UnitPrefix::MILLI, ACCEL_RANGE_G(ACCEL_RANGE), 15);
}

Parameters

value	the raw value to convert
prefix	the unit scale prefix to use to compute the physical value
range	the physical measure matching the maximum raw value
precision_bits	the number of significant bits of the raw value; only positive values are accounted, hence if a raw measure can be any value in [-32768;+32767], then precision_bits is 15.

Returns

the physical value calculated from value, scaled according to prefix

See also

map_physical_to_raw()

Definition at line 219 of file utilities.h.

map_physical_to_raw()

constexpr int16_t utils::map_physical_to_raw ( int16_t  value, UnitPrefix  prefix, int16_t  range, uint8_t  precision_bits  )

constexpr

Convert an absolute physical value, expressed in some given measurement unit, scaled with prefix, into a raw measurement as if obtained from a electronics device, using precision_bit number of bits (that defines the device raw measure range); for this device, physical measures are within range.

Computations done by this method will be performed at compile-time as long as all provided arguments are constants; this is important as this will help optimize code size and execution time. This is useful when you want to compare physical values against meaningful limits, and perform actions based on these comparisons; instead of always converting measured raw values into physical ones and then compare with a physical limit, you do the opposite, compare the measured raw values against the raw limits (converted, at compile-time, from physical limits constants).

// This sample code use MPU6050 (accelerometer-gyroscope) support
using namespace devices::magneto;
using namespace utils;
// These is the accelerometer range used in this code
static constexpr const AccelRange ACCEL_RANGE = AccelRange::RANGE_2G;
static constexpr const uint16_t ACCEL_RANGE_IN_G = ACCEL_RANGE_G(ACCEL_RANGE);
// These are specific threshold values for acceleration
static constexpr const int16_t ACCEL_1 = map_physical_to_raw(500, UnitPrefix::MILLI, ACCEL_RANGE_IN_G, 15);
static constexpr const int16_t ACCEL_2 = map_physical_to_raw(1000, UnitPrefix::MILLI, ACCEL_RANGE_IN_G, 15);
 
// This function performs an action based on current accelerometer value.
void check_accel(int16_t raw)
{
    // We consider accelerations the same whatever the sign
    if (raw < 0) raw = -raw;
    if (raw < ACCEL_1)
        act_when_low_accel();
    else if (raw < ACCEL_2)
        act_when_mid_accel();
    else if (raw < ACCEL_2)
        act_when_high_accel();
}

Parameters

value	the physical value to convert
prefix	the unit scale prefix in which value is expressed
range	the physical measure matching the maximum raw value
precision_bits	the number of significant bits of the raw value; only positive values are accounted, hence if a raw measure can be any value in [-32768;+32767], then precision_bits is 15.

Returns

the raw value calculated from value, as if directly returned by the device sensor

See also

map_raw_to_physical()

Definition at line 292 of file utilities.h.

low_byte()

constexpr uint8_t utils::low_byte ( uint16_t  word )

constexpr

Extract the low order byte of a 16-bits word.

Definition at line 308 of file utilities.h.

high_byte()

constexpr uint8_t utils::high_byte ( uint16_t  word )

constexpr

Extract the high order byte of a 16-bits word.

Definition at line 316 of file utilities.h.

as_uint16_t()

constexpr uint16_t utils::as_uint16_t ( uint8_t  high, uint8_t  low  )

constexpr

Convert 2 bytes into an unsigned int.

Parameters

high	the high byte
low	the low byte

Returns

the unsigned integer computed from high and low

Definition at line 327 of file utilities.h.

is_zero()

template<typename T >

constexpr T utils::is_zero ( T  value, T  default_value  )

constexpr

Replace value by default_value if not "true" (also known as "Elvis operator").

Parameters

value	the value to check
default_value	the value to replace 0

Returns

value if value is not false (or 0) otherwise default_value

Definition at line 339 of file utilities.h.

set_mask()

template<typename T >

void utils::set_mask	(	volatile T &	reg,
		T	mask,
		T	value
	)

Common utility to force a part of the value of a register, designated by a bit mask.

Template Parameters

T	the type of values to handle

Parameters

reg	the value to change part of
mask	the bit mask indicating which bits shall change
value	the new value for reg

Definition at line 352 of file utilities.h.

is_mask_equal()

template<typename T >

constexpr bool utils::is_mask_equal ( T  actual, T  mask, T  expected  )

constexpr

Common utility to check if 2 values are equal according to a mask.

Template Parameters

T	the type of values to compare

Parameters

actual	the actual value to compare
mask	the bit mask indicating which bits shall change
expected	the expected value

Definition at line 364 of file utilities.h.

bcd_to_binary()

uint8_t utils::bcd_to_binary ( uint8_t  bcd )

inline

Convert Binary-coded decimal byte (each nibble is a digit from 0 to 9) into a natural byte.

Parameters

bcd	the input using BCD format

Returns

bcd converted to natural integer

Definition at line 375 of file utilities.h.

binary_to_bcd()

uint8_t utils::binary_to_bcd ( uint8_t  binary )

inline

Convert a natural integers to a BCD byte (2 digits).

Behavior is undefined if binary >99.

Parameters

binary

the natural integer value to convert to BCD; must be in range [0..99]

Returns

binary converted to BCD

Definition at line 389 of file utilities.h.

swap_bytes() [1/6]

void utils::swap_bytes ( uint16_t &  value )

inline

Swap 2 bytes of a 2-bytes integer.

Useful to convert from big-endian to little-endian (AVR).

Parameters

value

value to convert in place (reference)

Definition at line 405 of file utilities.h.

swap_bytes() [2/6]

void utils::swap_bytes ( int16_t &  value )

inline

Swap 2 bytes of a 2-bytes integer.

Useful to convert from big-endian to little-endian (AVR).

Parameters

value

value to convert in place (reference)

Definition at line 415 of file utilities.h.

swap_bytes() [3/6]

void utils::swap_bytes ( uint32_t &  value )

inline

Reverse 4 bytes of a 4-bytes integer.

Useful to convert from big-endian to little-endian (AVR).

Parameters

value

value to convert in place (reference)

Definition at line 425 of file utilities.h.

swap_bytes() [4/6]

void utils::swap_bytes ( int32_t &  value )

inline

Reverse 4 bytes of a 4-bytes integer.

Useful to convert from big-endian to little-endian (AVR).

Parameters

value

value to convert in place (reference)

Definition at line 439 of file utilities.h.

swap_bytes() [5/6]

void utils::swap_bytes ( uint64_t &  value )

inline

Reverse 8 bytes of a 8-bytes integer.

Useful to convert from big-endian to little-endian (AVR).

Parameters

value

value to convert in place (reference)

Definition at line 449 of file utilities.h.

swap_bytes() [6/6]

void utils::swap_bytes ( int64_t &  value )

inline

Reverse 8 bytes of a 8-bytes integer.

Useful to convert from big-endian to little-endian (AVR).

Parameters

value

value to convert in place (reference)

Definition at line 463 of file utilities.h.

swap()

template<typename T >

void utils::swap	(	T &	a,
		T &	b
	)

Swap the values of 2 variables passed by reference.

Template Parameters

T	the type of variables to swap

Parameters

a	reference to the first variable
b	reference to the second variable

Definition at line 475 of file utilities.h.

as_uint8_t()

template<typename T >

constexpr uint8_t utils::as_uint8_t ( T  input )

constexpr

Cast a one byte long bit-fields struct into a byte.

Useful when dealing with devices registers (bytes) where each bit has a specific meaning which you want to clarify through a bitfield struct.

Parameters

input

the bit field struct value to convert

Returns

input casted as a byte

Definition at line 506 of file utilities.h.

as_array()

template<typename T , typename U = uint8_t[sizeof(T)]>

constexpr void utils::as_array ( const T &  input, U  output  )

constexpr

Cast an instance of type T to an array of uint8_t of the size of T.

Template Parameters

T	the type of input

Parameters

input	a constant reference to the instance to cast to an array
output	a pointer to an array of the size of T

Definition at line 518 of file utilities.h.

calculate_delay1_count()

constexpr uint8_t utils::calculate_delay1_count ( float  time_us )

constexpr

Calculate the count to pass to delay1() in order to reach time_us microseconds delay.

Calculation is performed at compile-time, provided that time_us is a constant when the method is called. This is to avoid dragging huge mathematics libraries if it can be avoided.

Parameters

time_us

the time to reach through delay1() AVR function

Returns

the count to pass to delay1() AVR function

Definition at line 531 of file utilities.h.

num_bits()

constexpr uint8_t utils::num_bits ( uint8_t  mask, uint8_t  num = 0  )

constexpr

Calculate the number of 1 bits in a byte.

Calculation is performed at compile-time, provided that mask is a constant when the method is called.

Parameters

mask	the byte which you want to count the number of 1 bits
num	used internally, always use default value for this argument!

Definition at line 542 of file utilities.h.

change_endianness()

template<typename T >

T utils::change_endianness ( const T &  value )

inline

Change endianness of any integral type (from big to small or small to big).

Template Parameters

T	the type fo value; if not an integral type, the function will do nothing; only 16 bits and 32 bits integral types are currently supported.

Parameters

value

the value which endianness shall be reverted

Returns

value with reverted endianness if an integer; otherwise, value is returned unchanged.

Definition at line 560 of file utilities.h.