Strings
Immutable string
-
struct UString
An immutable string.
-
ulib_uint ustring_hash_func(ulib_uint init, void const *buf, size_t size)
Low-level hash function used by
ustring_hash()
.Can be customized by setting the
ustring_hash_func
macro.- Parameters:
init – Hash initialization constant.
buf – Pointer to the start of the buffer.
size – Size of the buffer.
- Returns:
Hash value.
-
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()
.- 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_range(UString str, ulib_uint start, ulib_uint len)
Returns a new string containing the characters in a range of the specified string.
Note
The returned object must be destroyed by calling
ustring_deinit()
.- Parameters:
str – String.
start – Range start.
len – Range length.
- 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.
-
UString ustring_replacing_char(UString string, char needle, char replacement)
Returns a new string obtained by replacing all occurrences of a character with another.
Note
The returned object must be destroyed by calling
ustring_deinit()
.- Parameters:
string – String.
needle – Character to replace.
replacement – Replacement character.
- 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
precedesrhs
, 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 beforerhs
, 0 if they are equal, 1 iflhs
comes afterrhs
.
-
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
-
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.
-
uvec_ret ustrbuf_append_format_list(UStrBuf *buf, char const *format, va_list args)
Appends the specified formatted string to the string buffer.
-
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.
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.
-
bool ulib_str_equals(char const *lhs, char const *rhs)
Checks whether two strings are equal.
- Parameters:
lhs – First string.
rhs – Second string.
- Returns:
True if the two strings are equal, false otherwise.
-
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
andsrc
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
andsrc
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()
andstrtoll()
. 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()
andstrtoull()
. 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()
andstrtod()
. 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.