Utilities relating around number string representation and protected arithmatic helper functions. More...

#include <stdint.h>

Macros
#define	GBAL_UNUSED __attribute__((unused))
	A friendly wrapper around the not so friendly looking attribute syntax for ((unused))

#define	UNDEFINED -1

#define	MAX_BASE36 0x81BF0FFF
	Hex value of "ZZZZZZ" in base 36.

#define	SIGN(x) ((x > 0) - (x < 0))
	Get the sign (signum) of an integer.

#define	NUM_ELEM_IN_ARR(arr) (sizeof(arr) / sizeof((arr)[0]))
	Get the number of elements in an array.

#define	INT_MAX_DIGITS 11

#define	UINT_MAX_DIGITS 10

#define	UINT8_MAX_DIGITS 3

#define	BASE36_MAX_DIGITS 6

#define	ONE_K 1000

#define	ONE_M 1000000

#define	ONE_B 1000000000

#define	ONE_K_ZEROS 3

#define	ONE_M_ZEROS 6

#define	ONE_B_ZEROS 9

#define	SUFFIXED_NUM_MIN_REQ_CHARS 4

#define	LOG_ERROR(...) ((void)(0))

#define	GBAL_RETURN_IF_NULL_VOID(param)
	Checks if `param` is NULL and prints error message and returns in case it is. Useful for checking arguments to a function or errors during control flow.

#define	GBAL_RETURN_IF_NULL_RET(param, ret_val)
	Checks if `param` is equal to NULL and prints error message and returns in case it is. Useful for checking arguments to a function or errors during control flow.

Functions
uint32_t	u32_protected_add (uint32_t a, uint32_t b)
	Avoid overflow when adding two u32 integers.

uint16_t	u16_protected_add (uint16_t a, uint16_t b)
	Avoid overflow when adding two u16 integers.

uint32_t	u32_protected_mult (uint32_t a, uint32_t b)
	Avoid overflow when multiplying two u32 integers.

uint16_t	u16_protected_mult (uint16_t a, uint16_t b)
	Avoid overflow when multiplying two u16 integers.

void	truncate_uint_to_suffixed_str (uint32_t num, int num_req_chars, char out_str_buff[UINT_MAX_DIGITS+1])
	Truncate an unsigned number into a suffixed string representation e.g. 12000 -> "12K" The least significant digits are rounded down e.g. 12345 -> "12K", 12987 -> "12K".

static int	u32_get_digits (uint32_t n)
	Get the number of digits in a 32-bit unsigned number https://stackoverflow.com/questions/1068849/how-do-i-determine-the-number-of-digits-of-an-integer-in-c.

uint32_t	base36_to_u32 (const char b36_str[])
	Convert a base-36 string representation to a 32-bit unsigned integer. Since we are dealing with base-36 instead of decimal, the 32-bit decimal value of a base-36 string representation `b36` is equal to:

void	u32_to_base36 (uint32_t n, char b36_str[])
	Convert a 32-bit unsigned integer to its base-36 string representation. This will perform 6 divisions, so it will be significantly more expensive than its `base36_to_u32` counterpart.

Detailed Description

Utilities relating around number string representation and protected arithmatic helper functions.

Definition in file util.h.

Macro Definition Documentation

◆ BASE36_MAX_DIGITS

#define BASE36_MAX_DIGITS 6

Definition at line 48 of file util.h.

◆ GBAL_RETURN_IF_NULL_RET

#define GBAL_RETURN_IF_NULL_RET	(	param,
		ret_val
	)

Value:

    do                                                         \
    {                                                          \
        if ((param) == NULL)                                   \
        {                                                      \
            LOG_ERROR("Unexpected value: %s == NULL", #param); \
            return (ret_val);                                  \
        }                                                      \
    } while (0)

Checks if param is equal to NULL and prints error message and returns in case it is. Useful for checking arguments to a function or errors during control flow.

Parameters

ret_val The value to return in case param is equal to NULL.

This version is for a function that returns a value while GBAL_RETURN_ON_ERROR_VAL_VOID is for a void function.

Definition at line 95 of file util.h.

◆ GBAL_RETURN_IF_NULL_VOID

#define GBAL_RETURN_IF_NULL_VOID ( param )

Value:

    do                                                         \
    {                                                          \
        if ((param) == NULL)                                   \
        {                                                      \
            LOG_ERROR("Unexpected value: %s == NULL", #param); \
            return;                                            \
        }                                                      \
    } while (0)

Checks if param is NULL and prints error message and returns in case it is. Useful for checking arguments to a function or errors during control flow.

This version is for a void function, while GBAL_RETURN_ON_ERROR_VAL_RET is for one with a return value.

Definition at line 76 of file util.h.

◆ GBAL_UNUSED

#define GBAL_UNUSED __attribute__((unused))

A friendly wrapper around the not so friendly looking attribute syntax for ((unused))

Definition at line 19 of file util.h.

◆ INT_MAX_DIGITS

#define INT_MAX_DIGITS 11

Definition at line 45 of file util.h.

◆ LOG_ERROR

#define LOG_ERROR ( ... ) ((void)(0))

Definition at line 66 of file util.h.

◆ MAX_BASE36

#define MAX_BASE36 0x81BF0FFF

Hex value of "ZZZZZZ" in base 36.

Definition at line 27 of file util.h.

◆ NUM_ELEM_IN_ARR

#define NUM_ELEM_IN_ARR ( arr ) (sizeof(arr) / sizeof((arr)[0]))

Get the number of elements in an array.

Parameters

arr	input array

Definition at line 43 of file util.h.

◆ ONE_B

#define ONE_B 1000000000

Definition at line 52 of file util.h.

◆ ONE_B_ZEROS

#define ONE_B_ZEROS 9

Definition at line 56 of file util.h.

◆ ONE_K

#define ONE_K 1000

Definition at line 50 of file util.h.

◆ ONE_K_ZEROS

#define ONE_K_ZEROS 3

Definition at line 54 of file util.h.

◆ ONE_M

#define ONE_M 1000000

Definition at line 51 of file util.h.

◆ ONE_M_ZEROS

#define ONE_M_ZEROS 6

Definition at line 55 of file util.h.

◆ SIGN

#define SIGN ( x ) ((x > 0) - (x < 0))

Get the sign (signum) of an integer.

Returns: 1,-1,0 if the number is positive,negative, or 0, respectively.

Definition at line 35 of file util.h.

◆ SUFFIXED_NUM_MIN_REQ_CHARS

#define SUFFIXED_NUM_MIN_REQ_CHARS 4

Definition at line 60 of file util.h.

◆ UINT8_MAX_DIGITS

#define UINT8_MAX_DIGITS 3

Definition at line 47 of file util.h.

◆ UINT_MAX_DIGITS

#define UINT_MAX_DIGITS 10

Definition at line 46 of file util.h.

◆ UNDEFINED

#define UNDEFINED -1

Definition at line 21 of file util.h.

Function Documentation

◆ base36_to_u32()

uint32_t base36_to_u32 ( const char b36_str[] )

Convert a base-36 string representation to a 32-bit unsigned integer. Since we are dealing with base-36 instead of decimal, the 32-bit decimal value of a base-36 string representation b36 is equal to:

b36[0] * 36^0 + b36[1] * 36^1 + b36[2] * 36^2 ...

Parameters

b36_str input char[] to convert to decimal, must be of size BASE36_MAX_DIGITS+1

Returns: the 32-bit unsigned value of b36_str

Definition at line 260 of file util.c.

◆ truncate_uint_to_suffixed_str()

void truncate_uint_to_suffixed_str	(	uint32_t	num,
		int	num_req_chars,
		char	out_str_buff[UINT_MAX_DIGITS+1]
	)

Truncate an unsigned number into a suffixed string representation e.g. 12000 -> "12K" The least significant digits are rounded down e.g. 12345 -> "12K", 12987 -> "12K".

Parameters

num	The number to truncate, can be anything from 0 to UINT32_MAX.
num_req_chars	The number of characters to constrain the string to. The function will use up as much characters as it can in order to maintain as much accuracy as possible. So numbers are not fully truncated if not necessary, e.g. 123123000 -> "123123K" for example value 7, and if num_req_chars > u32_get_digits(num) the number will not be truncated at all. Passing less than SUFFIXED_NUM_MIN_REQ_CHARS may result in an output string longer than num_req_chars but can be done to truncate 1000s -> "1K", 2000 -> "2K" etc. which wouldn't be otherwise.
out_str	An output buffer to write the resulting string to. Must be of size UINT_MAX_DIGITS + 1. + 1 for null-terminator. At that size the suffix character will always be accounted for since a number with more digits than UINT_MAX_DIGITS will not be handled nor truncated.

Definition at line 116 of file util.c.

◆ u16_protected_add()

uint16_t u16_protected_add	(	uint16_t	a,
		uint16_t	b
	)

Avoid overflow when adding two u16 integers.

Parameters

a	left operator a + b
b	left operator a + b

Returns: the result of a + b or UINT16_MAX in case of overflow

Definition at line 180 of file util.c.

◆ u16_protected_mult()

uint16_t u16_protected_mult	(	uint16_t	a,
		uint16_t	b
	)

Avoid overflow when multiplying two u16 integers.

Parameters

a	left operator *a b**
b	left operator *a b**

Returns: the result of a * b or UINT16_MAX in case of overflow

Definition at line 190 of file util.c.

◆ u32_get_digits()

static int u32_get_digits ( uint32_t n )

inlinestatic

Get the number of digits in a 32-bit unsigned number https://stackoverflow.com/questions/1068849/how-do-i-determine-the-number-of-digits-of-an-integer-in-c.

Parameters

n	32-bit unsigned value to find the number of decimal digits of

Returns: the number of digits in a number

Definition at line 183 of file util.h.

◆ u32_protected_add()

uint32_t u32_protected_add	(	uint32_t	a,
		uint32_t	b
	)

Avoid overflow when adding two u32 integers.

Parameters

a	left operator a + b
b	left operator a + b

Returns: the result of a + b or UINT32_MAX in case of overflow

Definition at line 175 of file util.c.

◆ u32_protected_mult()

uint32_t u32_protected_mult	(	uint32_t	a,
		uint32_t	b
	)

Avoid overflow when multiplying two u32 integers.

Parameters

a	left operator *a b**
b	left operator *a b**

Returns: the result of a * b or UINT32_MAX in case of overflow

Definition at line 185 of file util.c.

◆ u32_to_base36()

void u32_to_base36	(	uint32_t	n,
		char	b36_str[]
	)

Convert a 32-bit unsigned integer to its base-36 string representation. This will perform 6 divisions, so it will be significantly more expensive than its base36_to_u32 counterpart.

We will iterate over all digits from BASE36_MAX_DIGITS-1 to 0 and determine their values in base-36, to then construct the string representation b36_str in base-36 or the integer n

Initially set to n, the variable acc will contain any given stage i:

b32[i] * 36^i + b32[i-1] * 36^(i-1) + ... + b32[0]

And we can thus extract the two following values:

b32[i] = acc / 36^i

acc = acc mod 36^i = b32[i-1] * 36^(i-1) + ... + b32[0]

So that acc can now be used for the following step, until i hits 0

Parameters

n	integer value to convert to a base-36 representation
b36_str	output char[], representation of `n` in base-36

See also: base36_to_u32

Definition at line 272 of file util.c.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ BASE36_MAX_DIGITS

◆ GBAL_RETURN_IF_NULL_RET

◆ GBAL_RETURN_IF_NULL_VOID

◆ GBAL_UNUSED

◆ INT_MAX_DIGITS

◆ LOG_ERROR

◆ MAX_BASE36

◆ NUM_ELEM_IN_ARR

◆ ONE_B

◆ ONE_B_ZEROS

◆ ONE_K

◆ ONE_K_ZEROS

◆ ONE_M

◆ ONE_M_ZEROS

◆ SIGN

◆ SUFFIXED_NUM_MIN_REQ_CHARS

◆ UINT8_MAX_DIGITS

◆ UINT_MAX_DIGITS

◆ UNDEFINED

Function Documentation

◆ base36_to_u32()

◆ truncate_uint_to_suffixed_str()

◆ u16_protected_add()

◆ u16_protected_mult()

◆ u32_get_digits()

◆ u32_protected_add()

◆ u32_protected_mult()

◆ u32_to_base36()