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

typedef int ulib_ret: Return codes.

enum ulib_ret_builtin

Builtin return codes.

Values:

enumerator ULIB_OK: The operation succeeded.

enumerator ULIB_NO: The operation did not succeed.

Note

This code is returned when an operation does not succeed as part of its normal execution. It does not signal an error condition.

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

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

enumerator ULIB_ERR_BOUNDS: Buffer bounds exceeded, or value over/underflowed its type.

enumerator ULIB_ERR_IO: The operation failed due to an IO error.

Note

When this happens, errno is sometimes set to a more meaningful value.

bool ulib_ret_is_err(ulib_ret ret)

Checks if a return code indicates an error.

Parameters:

ret – Return code.

Returns:

True if the return code indicates an error, false otherwise.

bool ulib_ret_is_ok(ulib_ret ret)

Checks if a return code does not indicate an error.

Parameters:

ret – Return code.

Returns:

True if the return code does not indicate an error, false otherwise.

bool ulib_is_err(ulib_ret ret)

Checks if a return code indicates an error.

Note

Hints the compiler that the condition is unlikely to be true.

Parameters:

ret – Return code.

Returns:

True if the return code indicates an error, false otherwise.

bool ulib_is_ok(ulib_ret ret)

Checks if a return code does not indicate an error.

Note

Hints the compiler that the condition is likely to be true.

Parameters:

ret – Return code.

Returns:

True if the return code does not indicate an error, false otherwise.

UString ulib_ret_to_name(ulib_ret ret)

Returns the enumeration name of the given return code.

Note

You must not call ustring_deinit on the returned string.

Parameters:

ret – Return code.

Returns:

Enumeration name of the return code.

UString ulib_ret_to_string(ulib_ret ret)

Returns a human-readable string representation of the given return code.

Note

You must not call ustring_deinit on the returned string.

Parameters:

ret – Return code.

Returns:

String representation of the return code.

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).