Numeric types

Integer numbers

typedef int32_t ulib_int

Integer type.

The size of this type can be controlled through the ULIB_TINY and ULIB_HUGE preprocessor definitions:

No definitions (default): 4 bytes int32_t
ULIB_TINY: 2 bytes int16_t
ULIB_HUGE: 8 bytes int64_t

typedef uint32_t ulib_uint

Unsigned integer type.

The size of this type can be controlled through the ULIB_TINY and ULIB_HUGE preprocessor definitions:

No definitions (default): 4 bytes uint32_t
ULIB_TINY: 2 bytes uint16_t
ULIB_HUGE: 8 bytes uint64_t

uint16_t ulib_uint16_floor2(uint16_t x)

Rounds x to the nearest power of 2 that is equal to or smaller than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or smaller than x.

uint32_t ulib_uint32_floor2(uint32_t x)

Rounds x to the nearest power of 2 that is equal to or smaller than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or smaller than x.

uint64_t ulib_uint64_floor2(uint64_t x)

Rounds x to the nearest power of 2 that is equal to or smaller than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or smaller than x.

uint16_t ulib_uint16_ceil2(uint16_t x)

Rounds x to the nearest power of 2 that is equal to or greater than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or greater than x.

uint32_t ulib_uint32_ceil2(uint32_t x)

Rounds x to the nearest power of 2 that is equal to or greater than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or greater than x.

uint64_t ulib_uint64_ceil2(uint64_t x)

Rounds x to the nearest power of 2 that is equal to or greater than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or greater than x.

unsigned ulib_uint16_log2(uint16_t x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the floor of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

unsigned ulib_uint32_log2(uint32_t x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the floor of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

unsigned ulib_uint64_log2(uint64_t x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the floor of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

unsigned ulib_uint16_ceil_log2(uint16_t x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the ceiling of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

unsigned ulib_uint32_ceil_log2(uint32_t x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the ceiling of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

unsigned ulib_uint64_ceil_log2(uint64_t x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the ceiling of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

ulib_uint ulib_uint_floor2(ulib_uint x)

Rounds x to the nearest power of 2 that is equal to or smaller than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or smaller than x.

ulib_uint ulib_uint_ceil2(ulib_uint x)

Rounds x to the nearest power of 2 that is equal to or greater than x.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Nearest power of 2 equal to or greater than x.

unsigned ulib_uint_log2(ulib_uint x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the floor of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

unsigned ulib_uint_ceil_log2(ulib_uint x)

Returns the integer base 2 logarithm of x.

Note

For non-power of 2 values, the result is the ceiling of the logarithm.

Warning

Undefined for zero.

Parameters:

x – Positive unsigned integer.

Returns:

Integer base 2 logarithm.

ulib_uint ulib_uint_pow2(ulib_byte x)

Returns two to the power of x.

Parameters:

x – Exponent.

Returns:

Two to the power of x.

bool ulib_uint_is_pow2(ulib_uint x)

Checks whether x is a power of two.

Parameters:

x – Unsigned integer.

Returns:

True if x is a power of two, false otherwise.

bool ulib_uint_is_pow2_or_zero(ulib_uint x)

Checks whether x is a power of two or zero.

Parameters:

x – Unsigned integer.

Returns:

True if x is a power of two or zero, false otherwise.

ULIB_INT_MIN: Minimum value of a ulib_int variable.

ULIB_INT_MAX: Maximum value of a ulib_int variable.

ULIB_INT_FMT: Format string for ulib_int variables.

ULIB_UINT_MIN: Minimum value of a ulib_uint variable.

ULIB_UINT_MAX: Maximum value of a ulib_uint variable.

ULIB_UINT_FMT: Format string for ulib_uint variables.

Floating point numbers

typedef double ulib_float

Float type.

The size of this type can be controlled through the ULIB_TINY and ULIB_HUGE preprocessor definitions:

No definitions or ULIB_HUGE (default): double
ULIB_TINY: float

ulib_float ulib_float_prev(ulib_float x)

Returns the previous representable float value.

Parameters:

x – Float number.

Returns:

Previous representable float value.

ulib_float ulib_float_next(ulib_float x)

Returns the next representable float value.

Parameters:

x – Float number.

Returns:

Next representable float value.

ULIB_FLOAT_MIN: Minimum positive value of a ulib_float variable.

ULIB_FLOAT_MAX: Maximum value of a ulib_float variable.

ULIB_FLOAT_FMT: Format string for ulib_float variables.

ULIB_FLOAT_EPSILON: Difference between 1 and the least value greater than 1 that is representable by a ulib_float variable.

Utilities for numeric types

bool ulib_eq(T a, T b)

Checks if two numbers are equal.

Parameters:

a – First number.
b – Second number.

Returns:

a == b.

bool ulib_equals(T a, T b)

Checks if two numbers are equal.

Deprecated:: Use ulib_eq instead.

Parameters:

a – First number.
b – Second number.

Returns:

a == b.

bool ulib_neq(T a, T b)

Checks if two numbers are different.

Parameters:

a – First number.
b – Second number.

Returns:

a != b.

bool ulib_lt(T a, T b)

Checks if a is less than b.

Parameters:

a – First number.
b – Second number.

Returns:

a < b.

bool ulib_gt(T a, T b)

Checks if a is greater than b.

Parameters:

a – First number.
b – Second number.

Returns:

a > b.

bool ulib_leq(T a, T b)

Checks if a is less than or equal to b.

Parameters:

a – First number.
b – Second number.

Returns:

a <= b.

bool ulib_geq(T a, T b)

Checks if a is greater than or equal to b.

Parameters:

a – First number.
b – Second number.

Returns:

a >= b.

T ulib_min(T a, T b)

Returns the minimum between two numbers.

Parameters:

a – First number.
b – Second number.

Returns:

Minimum between the two numbers.

T ulib_max(T a, T b)

Returns the maximum between two numbers.

Parameters:

a – First number.
b – Second number.

Returns:

Maximum between the two numbers.

T ulib_abs(T x)

Returns the absolute value of a number.

Parameters:

x – The number.

Returns:

Absolute value of the number.

T ulib_clamp(T x, T xmin, T xmax)

Clamps a number between two values.

Parameters:

x – The number.
xmin – Minumum value.
xmax – Maximum value.

Returns:

Clamped value.

T ulib_diff(T a, T b)

Returns the absolute difference between two numbers.

Parameters:

a – First number.
b – Second number.

Returns:

Absolute difference.

Bitmasks

typedef uintN_t UBit_N: Generic bitmask type.

Note

This is a placeholder for documentation purposes. You should use the UBit(N) macro to reference a specific bitmask type.

UBit(N)

References a specific bitmask type.

Parameters:

N – Bitmask size in bits. Allowed values: 8, 16, 32 and 64.

typedef uint8_t UBit_8: 8 bit bitmask type.

typedef uint16_t UBit_16: 16 bit bitmask type.

typedef uint32_t UBit_32: 32 bit bitmask type.

typedef uint64_t UBit_64: 64 bit bitmask type.

UBit_N ubit(bitsize N, unsigned mask)

Returns a bitmask given its integer representation.

Parameters:

N – Bitmask size in bits.
mask – Integer representation of the bitmask.

Returns:

Bitmask with the specified integer representation.

UBit_N ubit_none(bitsize N)

Bitmask with all bits set to zero.

Parameters:

N – Bitmask size in bits.

Returns:

Bitmask with all bits set to zero.

UBit_N ubit_all(bitsize N)

Bitmask with all bits set to one.

Parameters:

N – Bitmask size in bits.

Returns:

Bitmask with all bits set to one.

UBit_N ubit_lshift(bitsize N, unsigned mask, unsigned shift)

Performs a left-shift operation on the specified bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask to shift.
shift – Number of places to shift.

Returns:

Result of the shift operation.

UBit_N ubit_rshift(bitsize N, unsigned mask, unsigned shift)

Performs a right-shift operation on the specified bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask to shift.
shift – Number of places to shift.

Returns:

Result of the shift operation.

UBit_N ubit_bit(bitsize N, unsigned bit)

Returns a bitmask with the specified bit set.

Parameters:

N – Bitmask size in bits.
bit – Bit to set.

Returns:

Bitmask with the specified bit set.

UBit_N ubit_range(bitsize N, unsigned start, unsigned len)

Returns a bitmask that has len bits set starting from start.

Parameters:

N – Bitmask size in bits.
start – Range start.
len – Range length.

Returns:

Bitmask with len bits set starting from start.

bool ubit_is_set(bitsize N, unsigned mask, unsigned bits)

Checks whether a bitmask has specific bits set.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
bits – Bit(s) to check.

Returns:

True if the bits are set, false otherwise.

bool ubit_is_any_set(bitsize N, unsigned mask, unsigned bits)

Checks whether a bitmask has any of the specified bits set.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
bits – Bit(s) to check.

Returns:

True if at least one of the specified bits is set, false otherwise.

UBit_N ubit_set(bitsize N, unsigned mask, unsigned bits)

Sets bits in a bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
bits – Bit(s) to set.

Returns:

Bitmask with the specified bits set.

UBit_N ubit_unset(bitsize N, unsigned mask, unsigned bits)

Unsets bits in a bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
bits – Bit(s) to unset.

Returns:

Bitmask with the specified bits unset.

UBit_N ubit_set_bool(bitsize N, unsigned mask, unsigned bits, bool exp)

Sets or unsets bits in a bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
bits – Bit(s) to set or unset.
exp – True to set, false to unset.

Returns:

Bitmask with the specified bits set or unset.

UBit_N ubit_toggle(bitsize N, unsigned mask, unsigned bits)

Toggles bits in a bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
bits – Bit(s) to toggle.

Returns:

Bitmask with the specified bits toggled.

UBit_N ubit_overwrite(bitsize N, unsigned mask, unsigned n_mask, unsigned bits)

Overwrites the bits in the bitmask with those from another bitmask.

Example: if mask = 0101 0101, n_mask = 1010 1010 and mask = 0111 0000, the output is 0010 0101.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.
n_mask – Other bitmask.
bits – Bitmask indicating the bits that should be overwritten.

Returns:

Bitmask with the specified bits overwritten.

UBit_N ubit_two_compl(bitsize N, unsigned mask)

Returns the two’s complement of the given bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.

Returns:

Two’s complement of the bitmask.

unsigned ubit_count_set(bitsize N, unsigned mask)

Returns the number of bits that are set in a bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.

Returns:

Number of set bits.

unsigned ubit_count_unset(bitsize N, unsigned mask)

Returns the number of bits that are not set in a bitmask.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.

Returns:

Number of unset bits.

unsigned ubit_first_set(bitsize N, unsigned mask)

Returns the index of the first set bit.

Parameters:

N – Bitmask size in bits.
mask – Bitmask.

Returns:

Index of the first set bit, or a value >= N if no bits are set.

Return codes

enum ulib_ret

Return codes.

Values:

enumerator ULIB_OK: The operation succeeded.

enumerator ULIB_ERR_MEM: The operation failed due to a memory error.

enumerator ULIB_ERR: The operation failed due to an unspecified error.

Other types

typedef uint8_t ulib_byte: Byte type.

typedef void *ulib_ptr: Pointer type.

ULIB_MALLOC_ALIGN

Alignment of pointers returned by memory allocation functions.

On most platforms this is equal to the strictest alignment of any scalar type (e.g. long double).