Strings

Immutable string

struct UString

An immutable string.

UString const ustring_null

String with a NULL buffer.

UString const ustring_empty

Empty string.

ulib_uint ustring_size(UString string)

Returns the size of the string.

Parameters:

• string – String.

Returns:

String size.

ulib_uint ustring_length(UString string)

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

Parameters:

• string – String.

Returns:

String length.

char const *ustring_data(UString string)

Returns the buffer backing the string.

Parameters:

• string – String.

Returns:

String buffer.

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 returned object must be destroyed by calling ustring_deinit().

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 returned object must be destroyed by calling ustring_deinit().

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 object must be destroyed by calling ustring_deinit().

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_assign_buf(char const *buf)

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

Note

The returned object must be destroyed by calling ustring_deinit().

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.

UString ustring_copy_buf(char const *buf)

Initializes a new string by copying the specified buffer.

Note

The returned object must be destroyed by calling ustring_deinit().

Note

The buffer must be null-terminated.

Parameters:

• buf – String buffer.

Returns:

New string.

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.

UString ustring_dup(UString string)

Duplicates the specified string.

Note

The returned object must be destroyed by calling ustring_deinit().

Parameters:

• string – String to duplicate.

Returns:

Duplicated string.

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

Initializes a new string with the specified format.

Note

The returned object must be destroyed by calling ustring_deinit().

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.

Note

The returned object must be destroyed by calling ustring_deinit().

Parameters:

• format – Format string.

• args – Format arguments.

Returns:

New string.

UString ustring_concat(UString const *strings, ulib_uint count)

Concatenates the specified strings.

Note

The returned object must be destroyed by calling ustring_deinit().

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.

Note

The returned object must be destroyed by calling ustring_deinit().

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.

Note

The returned object must be destroyed by calling ustring_deinit().

Parameters:

• string – String to repeat.

• times – Number of repetitions.

Returns:

New string.

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.

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.

UString ustring_to_upper(UString string)

Converts the given string to uppercase.

Note

The returned object must be destroyed by calling ustring_deinit().

Parameters:

• string – String to convert.

Returns:

Uppercase string.

UString ustring_to_lower(UString string)

Converts the given string to lowercase.

Note

The returned object must be destroyed by calling ustring_deinit().

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

The returned object must be destroyed by calling ulib_free().

Parameters:

• string – String to deinitialize.

Returns:

Buffer.

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.

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_copy_literal(literal)

Initializes a new string by copying the specified string literal.

Note

The returned object must be destroyed by calling ustring_deinit().

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.

Mutable string buffer

typedef struct UVec_char UStrBuf

A mutable string buffer.

Note

A string buffer is a UVec(T) of char elements, so you can use any UVec(T) API on a UStrBuf object.

UStrBuf ustrbuf(void)

Initializes a new string buffer.

Note

The returned object must be destroyed by calling ustrbuf_deinit().

Returns:

Initialized string buffer.

void ustrbuf_deinit(UStrBuf *buf)

Deinitializes a string buffer previously initialized with ustrbuf().

Parameters:

• buf – String buffer.

ulib_uint ustrbuf_size(UStrBuf const *buf)

Returns the size of the string buffer.

Parameters:

• buf – String buffer.

Returns:

Size.

ulib_uint ustrbuf_length(UStrBuf const *buf)

Returns the number of characters in the string buffer.

Parameters:

• buf – String buffer.

Returns:

Number of characters.

char const *ustrbuf_data(UStrBuf const *buf)

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

Parameters:

• buf – String buffer.

Returns:

Pointer to the first character.

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

The returned object must be destroyed by calling ustring_deinit().

Note

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

Parameters:

• buf – String buffer.

Returns:

String.

uvec_ret ustrbuf_append_string(UStrBuf *buf, char const *string, ulib_uint length)

Appends the specified string to the string buffer.

Parameters:

• buf – String buffer.

• string – String to append.

• length – Length of the string.

Returns:

UVEC_OK on success, otherwise UVEC_ERR.

uvec_ret ustrbuf_append_ustring(UStrBuf *buf, UString string)

Appends the specified uString to the string buffer.

Parameters:

• buf – String buffer.

• string – String to append.

Returns:

UVEC_OK on success, otherwise UVEC_ERR.

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.

Raw C strings

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.

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.

char ulib_char_to_upper(char c)

Converts the given character to uppercase.

Parameters:

• c – Character to convert.

Returns:

Uppercase character.

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

The returned object must be destroyed by calling 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.

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.

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.

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.

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

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

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

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

Converts the given string into a float.

Note

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

Parameters:

• src – Source string.

• end – [out] End pointer.

Returns:

Float.

void *ulib_mem_chr_last(void const *haystack, int c, size_t h_len)

Finds the last occurrence of a character.

Parameters:

• haystack – Memory area.

• c – Character to find.

• h_len – Length of the memory area.

Returns:

Pointer to the first occurrence of the character, or NULL.

void *ulib_mem_mem(void const *haystack, size_t h_len, void const *needle, size_t n_len)

Finds the first occurrence of the specified substring.

Parameters:

• haystack – Memory area.

• h_len – Length of the memory area.

• needle – Substring.

• n_len – Length of the substring.

Returns:

Pointer to the first occurrence of the substring, or NULL.

void *ulib_mem_mem_last(void const *haystack, size_t h_len, void const *needle, size_t n_len)

Finds the last occurrence of the specified substring.

Parameters:

• haystack – Memory area.

• h_len – Length of the memory area.

• needle – Substring.

• n_len – Length of the substring.

Returns:

Pointer to the last occurrence of the substring, or NULL.