Base Types

Integers

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)

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.

ulib_uint_next_power_2(x)

Changes the specified unsigned integer into the next power of two.

Parameters
  • x – [ulib_uint] Unsigned integer.

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)

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.

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_MIN

Minimum positive value of a ulib_float variable.

ULIB_FLOAT_MAX

Maximum value of a ulib_float variable.

ULIB_FLOAT_EPSILON

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

ULIB_FLOAT_FMT

Format string for ulib_float variables.

ulib_float_prev(x)

Returns the previous representable float value.

Parameters
  • x – [ulib_float] Float number.

Returns

Previous representable float value.

ulib_float_next(x)

Returns the next representable float value.

Parameters
  • x – [ulib_float] Float number.

Returns

Next representable float value.

Bitmasks

UBit(N)

Bitmask type.

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

ubit(N, 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_none(N)

Bitmask with all bits set to zero.

Parameters
  • N – Bitmask size in bits.

Returns

Bitmask with all bits set to zero.

ubit_all(N)

Bitmask with all bits set to one.

Parameters
  • N – Bitmask size in bits.

Returns

Bitmask with all bits set to one.

ubit_lshift(N, mask, 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_rshift(N, mask, 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_bit(N, 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_range(N, start, 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.

ubit_is_set(N, mask, 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.

ubit_is_any_set(N, mask, 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_set(N, mask, 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_unset(N, mask, 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_set_bool(N, mask, bits, 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_toggle(N, mask, 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_overwrite(N, mask, n_mask, 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_count_set(N, 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.

ubit_count_unset(N, mask)

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

Parameters
  • N – Bitmask size in bits.

  • mask – Bitmask.

Returns

Number of unset bits.

Strings

struct UString

A counted string.

Public Functions

UString ustring_assign(char const *buf, size_t length)

Initializes a new string by taking ownership of the specified buffer, which must have been dynamically allocated.

Note

The buffer must be null-terminated.

Note

Due to the internals of UString, you must not attempt to access the buffer after calling this function as it may have been deallocated.

Parameters
  • buf – String buffer.

  • length – Length of the string (excluding the null terminator).

Returns

New string.

UString ustring_copy(char const *buf, size_t length)

Initializes a new string by copying the specified buffer.

Note

The buffer must be null-terminated.

Parameters
  • buf – String buffer.

  • length – Length of the string (excluding the null terminator).

Returns

New string.

UString ustring_wrap(char const *buf, size_t length)

Initializes a new string by wrapping the specified buffer.

Note

The buffer must be null-terminated.

Note

If the buffer has been dynamically allocated, you are responsible for its deallocation.

Note

You must not call ustring_deinit on a string initialized with this function.

Parameters
  • buf – String buffer.

  • length – Length of the string (excluding the null terminator).

Returns

New string.

char *ustring(UString *string, size_t length)

Initializes a new string of the specified length and returns its underlying buffer.

This allows direct initialization of the buffer, avoiding unnecessary allocations or copies.

Note

The returned buffer is null-terminated but otherwise uninitialized.

Parameters
  • string – String to initialize.

  • length – Length of the string (excluding the null terminator).

Returns

Underlying buffer.

UString ustring_dup(UString string)

Duplicates the specified string.

Parameters

string – String to duplicate.

Returns

Duplicated string.

UString ustring_with_format(char const *format, ...)

Initializes a new string with the specified format.

Parameters
  • format – Format string.

  • ... – Format arguments.

Returns

New string.

UString ustring_with_format_list(char const *format, va_list args)

Initializes a new string with the specified format.

Parameters
  • format – Format string.

  • args – Format arguments.

Returns

New string.

UString ustring_concat(UString const *strings, ulib_uint count)

Concatenates the specified strings.

Parameters
  • strings – Strings to concatenate.

  • count – Number of strings.

Returns

Concatenation of the specified strings.

UString ustring_join(UString const *strings, ulib_uint count, UString sep)

Joins the specified strings with a separator.

Parameters
  • strings – Strings to join.

  • count – Number of strings.

  • sep – Separator.

Returns

Strings joined with the specified separator.

UString ustring_repeating(UString string, ulib_uint times)

Returns a new string obtained by repeating the specified string.

Parameters
  • string – String to repeat.

  • times – Number of repetitions.

Returns

New string.

UString ustring_to_upper(UString string)

Converts the given string to uppercase.

Parameters

string – String to convert.

Returns

Uppercase string.

UString ustring_to_lower(UString string)

Converts the given string to lowercase.

Parameters

string – String to convert.

Returns

Lowercase string.

ulib_uint ustring_index_of(UString string, char needle)

Returns the index of the first occurrence of the specified character.

Parameters
  • string – String to search into.

  • needle – Character to find.

Returns

Index of the first occurrence of the specified character. If it cannot be found, returns an index greater than or equal to the string’s length.

ulib_uint ustring_index_of_last(UString string, char needle)

Returns the index of the last occurrence of the specified character.

Parameters
  • string – String to search into.

  • needle – Character to find.

Returns

Index of the last occurrence of the specified character. If it cannot be found, returns an index greater than or equal to the string’s length.

ulib_uint ustring_find(UString string, UString needle)

Returns the index of the first occurrence of the specified string.

Parameters
  • string – String to search into.

  • needle – String to find.

Returns

Index of the first occurrence of the specified string. If it cannot be found, returns an index greater than or equal to the string’s length.

ulib_uint ustring_find_last(UString string, UString needle)

Returns the index of the last occurrence of the specified string.

Parameters
  • string – String to search into.

  • needle – String to find.

Returns

Index of the last occurrence of the specified string. If it cannot be found, returns an index greater than or equal to the string’s length.

bool ustring_starts_with(UString string, UString prefix)

Checks whether the string starts with the specified prefix.

Parameters
  • string – String.

  • prefix – Prefix.

Returns

True if the string starts with the specified prefix, false otherwise.

bool ustring_ends_with(UString string, UString suffix)

Checks whether the string ends with the specified suffix.

Parameters
  • string – String.

  • suffix – Suffix.

Returns

True if the string ends with the specified suffix, false otherwise.

bool ustring_equals(UString lhs, UString rhs)

Checks whether two strings are equal.

Parameters
  • lhs – First string.

  • rhs – Second string.

Returns

True if the two strings are equal, false otherwise.

bool ustring_precedes(UString lhs, UString rhs)

Checks whether lhs precedes rhs in lexicographic order.

Parameters
  • lhs – First string.

  • rhs – Second string.

Returns

True if lhs precedes rhs, False otherwise.

int ustring_compare(UString lhs, UString rhs)

Compares lhs and rhs in lexicographic order.

Parameters
  • lhs – First string.

  • rhs – Second string.

Returns

-1 if lhs comes before rhs, 0 if they are equal, 1 if lhs comes after rhs.

ulib_uint ustring_hash(UString string)

Returns the hash of the specified string.

Parameters

string – String.

Returns

Hash.

ulib_ret ustring_to_int(UString string, ulib_int *out, unsigned base)

Converts the string into an integer.

Parameters
  • string – String.

  • out[out] Converted value.

  • base – Numeric base.

Returns

Return code.

ulib_ret ustring_to_uint(UString string, ulib_uint *out, unsigned base)

Converts the string into an unsigned integer.

Parameters
  • string – String.

  • out[out] Converted value.

  • base – Numeric base.

Returns

Return code.

ulib_ret ustring_to_float(UString string, ulib_float *out)

Converts the string into a float.

Parameters
  • string – String.

  • out[out] Converted value.

Returns

Return code.

void ustring_deinit(UString *string)

Deinitializes the specified string.

Parameters

string – String to deinitialize.

char *ustring_deinit_return_data(UString *string)

Deinitializes the specified string, returning its underlying buffer.

Note

You are responsible for deallocating the returned buffer.

Parameters

string – String to deinitialize.

Returns

Buffer.

Public Static Functions

static inline ulib_uint ustring_size(UString string)

Returns the size of the string.

Parameters

string – String.

Returns

String size.

static inline ulib_uint ustring_length(UString string)

Returns the length of the string, excluding the null terminator.

Parameters

string – String.

Returns

String length.

static inline UString ustring_assign_buf(char const *buf)

Initializes a new string by taking ownership of the specified buffer, which must have been dynamically allocated.

Note

The buffer must be null-terminated.

Note

Due to the internals of UString, you must not attempt to access the buffer after calling this function as it may have been deallocated.

Parameters

buf – String buffer.

Returns

New string.

static inline UString ustring_copy_buf(char const *buf)

Initializes a new string by copying the specified buffer.

Note

The buffer must be null-terminated.

Parameters

buf – String buffer.

Returns

New string.

static inline UString ustring_wrap_buf(char const *buf)

Initializes a new string by wrapping the specified buffer.

Note

The buffer must be null-terminated.

Note

If the buffer has been dynamically allocated, you are responsible for its deallocation.

Note

You must not call ustring_deinit on a string initialized with this function.

Parameters

buf – String buffer.

Returns

New string.

static inline bool ustring_is_upper(UString string)

Checks if the string does not contain lowercase characters.

Parameters

string – String.

Returns

True if the string does not contain lowercase characters, false otherwise.

static inline bool ustring_is_lower(UString string)

Checks if the string does not contain uppercase characters.

Parameters

string – String.

Returns

True if the string does not contain uppercase characters, false otherwise.

static inline bool ustring_is_null(UString string)

Checks whether the string has a NULL buffer.

Parameters

string – String instance.

Returns

True if the string has a NULL buffer, false otherwise.

static inline bool ustring_is_empty(UString string)

Checks whether the string is empty.

Note

The null string is considered empty.

Parameters

string – String instance.

Returns

True if the string is empty, false otherwise.

UString const ustring_null

String with a NULL buffer.

UString const ustring_empty

Empty string.

ustring_data(string)

Returns the buffer backing the string.

Parameters
Returns

[char const *] String buffer.

ustring_copy_literal(literal)

Initializes a new string by copying the specified string literal.

Parameters
  • literal – [char const []] String literal.

Returns

[UString] Initialized string.

ustring_literal(literal)

Wraps the specified literal in a string.

Note

You must not call ustring_deinit on a string initialized with this function.

Parameters
  • literal – [char const []] String literal.

Returns

[UString] String.

static inline bool ulib_char_is_upper(char c)

Checks if the specified character is an uppercase letter.

Parameters

c – Character.

Returns

True if the character is an uppercase letter, false otherwise.

static inline bool ulib_char_is_lower(char c)

Checks if the specified character is a lowercase letter.

Parameters

c – Character.

Returns

True if the character is a lowercase letter, false otherwise.

static inline char ulib_char_to_upper(char c)

Converts the given character to uppercase.

Parameters

c – Character to convert.

Returns

Uppercase character.

static inline char ulib_char_to_lower(char c)

Converts the given character to lowercase.

Parameters

c – Character to convert.

Returns

Lowercase character.

char *ulib_str_dup(char const *string, size_t length)

Duplicates the specified string.

Note

You are responsible for deallocating the returned string via ulib_free.

Parameters
  • string – String to duplicate.

  • length – Length of the string to duplicate.

Returns

Duplicated string.

size_t ulib_str_flength(char const *format, ...)

Returns the length of the specified formatted string.

Parameters
  • format – Format string.

  • ... – Format arguments.

Returns

Length of the formatted string.

size_t ulib_str_flength_list(char const *format, va_list args)

Returns the length of the specified formatted string.

Parameters
  • format – Format string.

  • args – Format arguments.

Returns

Length of the formatted string.

static inline bool ulib_str_is_upper(char const *string, size_t length)

Checks if the string does not contain lowercase characters.

Parameters
  • string – String.

  • length – String length.

Returns

True if the string does not contain lowercase characters, false otherwise.

static inline bool ulib_str_is_lower(char const *string, size_t length)

Checks if the string does not contain uppercase characters.

Parameters
  • string – String.

  • length – String length.

Returns

True if the string does not contain uppercase characters, false otherwise.

static inline void ulib_str_to_upper(char *dst, char const *src, size_t length)

Converts the given string to uppercase.

Note

dst and src can be equal.

Parameters
  • dst – Destination string.

  • src – Source string.

  • length – Length of the source string.

static inline void ulib_str_to_lower(char *dst, char const *src, size_t length)

Converts the given string to lowercase.

Note

dst and src can be equal.

Parameters
  • dst – Destination string.

  • src – Source string.

  • length – Length of the source string

static inline ulib_int ulib_str_to_int(char const *src, char **end, unsigned base)

Converts the given string into an integer.

Note

Size-appropriate wrapper for strtol/strtoll. Refer to their documentation for extended information (e.g. error handling).

Parameters
  • src – Source string.

  • end[out] End pointer.

  • base – Numeric base.

Returns

Integer.

static inline ulib_uint ulib_str_to_uint(char const *src, char **end, unsigned base)

Converts the given string into an unsigned integer.

Note

Size-appropriate wrapper for strtoul/strtoull. Refer to their documentation for extended information (e.g. error handling).

Parameters
  • src – Source string.

  • end[out] End pointer.

  • base – Numeric base.

Returns

Unsigned integer.

static inline ulib_float ulib_str_to_float(char const *src, char **end)

Converts the given string into a float.

Note

Size-appropriate wrapper for strtof/strtod. Refer to their documentation for extended information (e.g. error handling).

Parameters
  • src – Source string.

  • end[out] End pointer.

Returns

Float.

struct UStrBuf : public UVec

A mutable string buffer.

Public Functions

uvec_ret ustrbuf_append_format(UStrBuf *buf, char const *format, ...)

Appends the specified formatted string to the string buffer.

Parameters
  • buf – String buffer.

  • format – Format string.

  • ... – Format arguments.

Returns

UVEC_OK on success, otherwise UVEC_ERR.

uvec_ret ustrbuf_append_format_list(UStrBuf *buf, char const *format, va_list args)

Appends the specified formatted string to the string buffer.

Parameters
  • buf – String buffer.

  • format – Format string.

  • args – Format arguments.

Returns

UVEC_OK on success, otherwise UVEC_ERR.

UString ustrbuf_to_ustring(UStrBuf *buf)

Converts the string buffer into a UString and deinitializes the buffer.

Note

After calling this function, the string buffer must not be used anymore.

Parameters

buf – String buffer.

Returns

String.

ustrbuf()

Initializes a new string buffer.

Returns

Initialized string buffer.

ustrbuf_deinit(buf)

Deinitializes a string buffer previously initialized with ustrbuf().

Parameters
  • buf – [UStrBuf *] String buffer.

ustrbuf_size(buf)

Returns the size of the string buffer.

Parameters
  • buf – [UStrBuf *] String buffer.

Returns

Size.

ustrbuf_length(buf)

Returns the number of characters in the string buffer.

Parameters
  • buf – [UStrBuf *] String buffer.

Returns

Number of characters.

ustrbuf_data(buf)

Returns a pointer to the first character of the string buffer.

Parameters
  • buf – [UStrBuf *] String buffer.

Returns

Pointer to the first character.

ustrbuf_append_literal(buf, literal)

Appends the specified string literal to the string buffer.

Parameters
  • buf – [UStrBuf *] String buffer.

  • literal – [char const []] String literal to append.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

ustrbuf_append_string(buf, string, length)

Appends the specified string to the string buffer.

Parameters
  • buf – [UStrBuf *] String buffer.

  • string – [char const *] String to append.

  • length – [ulib_uint] Length of the string.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

ustrbuf_append_ustring(buf, string)

Appends the specified uString to the string buffer.

Parameters
  • buf – [UStrBuf *] String buffer.

  • string – [UString] String to append.

Returns

[uvec_ret] UVEC_OK on success, otherwise UVEC_ERR.

Return values

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.