Dynamic String API

NUL-terminated dynamic string utilities. More...

Functions
bool	string_adjust (t_string *string)
	Shrinks string capacity to match its current length plus NUL byte.
bool	string_append (t_string *dst, const t_string *src)
	Appends the content of a source string to the end of a string.
bool	string_append_format (t_string *string, const char *fstring,...)
	Appends formatted text to string using variadic arguments.
bool	string_append_n (t_string *s, const char *str, long n)
	Appends n first bytes of a string to the end of a dynamic string.
bool	string_append_vformat (t_string *string, const char *fstring, va_list args)
	Appends formatted text to string using va_list.
bool	string_cmp (const t_string *a, const t_string *b)
	Compares two strings byte by byte.
bool	string_dup (t_string *dst, const t_string *src)
	Copies the content of a source string into an existing string.
bool	string_dup_n (t_string *dst, const t_string *src, size_t n)
	Copies up to n bytes from a source string into an existing string.
void	string_free (t_string *string)
	Frees the string's internal data.
void	string_free_void (void *string)
	Frees a t_string item through a generic void* callback signature.
ssize_t	string_get_index_c (const t_string *string, char c)
	Finds the index of the first occurrence of a character in the string.
ssize_t	string_get_index_s (const t_string *string, const char *s, ssize_t slen)
	Finds the first occurrence of a substring in the string.
bool	string_init (t_string *s, size_t initial_cap, const char *str, long n)
	Initializes a string with the specified initial capacity.
bool	string_insert (t_string *dst, size_t index, const t_string *src)
	Inserts a source string in a string at the specified index.
bool	string_insert_n (t_string *s, size_t index, const char *str, long n)
	Inserts n first bytes of a string at the specified index.
bool	string_prepend (t_string *dst, const t_string *src)
	Prepends a source string to the beginning of a string.
bool	string_prepend_n (t_string *s, const char *str, long n)
	Prepends n first bytes of a string to the beginning of a string.
bool	string_read_all (t_string *string, int fd)
	Reads all available data from a file descriptor into string.
bool	string_read_until_c (t_string *string, int fd, char c)
	Reads from a file descriptor until a specific character is found.
bool	string_read_until_n (t_string *string, int fd, size_t n)
	Reads up to n bytes from a file descriptor into string.
bool	string_read_until_s (t_string *string, int fd, const char *s, ssize_t slen)
	Reads from a file descriptor until a specific substring is found.
void	string_rm_part (t_string *string, size_t i_start, ssize_t len)
	Removes a portion of the string starting at i_start.
bool	string_split_at (const t_string *src, size_t index, t_string *out_before, t_string *out_after)
	Splits a string into two initialized strings at a byte index.
bool	string_split_on_char (const t_string *src, char c, bool keep_empty_entries, t_vector *out)
	Splits a string on a delimiter character into a t_vector.
bool	string_split_on_string (const t_string *src, const char *sep, bool keep_empty_entries, t_vector *out)
	Splits a string on a delimiter C-string into a t_vector.
void	string_take (t_string *dst, char *src, size_t cap, ssize_t len)
	Installs an existing buffer in a string without copying it.
void	string_take_string (t_string *dst, t_string *src)
	Move the internal storage of one string into another string.
void	string_trim_leading (t_string *string, char c)
	Removes leading copies of a character from a string.

Detailed Description

NUL-terminated dynamic string utilities.

Functions to initialize, grow, shrink, read, format and manipulate dynamic strings whose allocated data is kept NUL-terminated.

Function Documentation

string_adjust()

bool string_adjust

(

t_string *

string

)

Shrinks string capacity to match its current length plus NUL byte.

Warning

string must be initialized before calling this function.

Parameters

string

Pointer to an initialized string (borrowed).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_append()

bool string_append	(	t_string *	dst,
		const t_string *	src
	)

Appends the content of a source string to the end of a string.

Destination storage is automatically grown if necessary.

Warning

dst and src must be initialized before calling this function.

Parameters

dst	Destination string to append to (borrowed).
src	Source string to append (borrowed, read-only).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

string_append_format()

bool string_append_format	(	t_string *	string,
		const char *	fstring,
			...
	)

Appends formatted text to string using variadic arguments.

‍Supports the same format subset as buff_append_format().

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
fstring	Format string (borrowed, read-only).
...	Variadic arguments for format specifiers.

Returns

true on success, false on failure.

Here is the call graph for this function:

string_append_n()

bool string_append_n	(	t_string *	s,
		const char *	str,
		long	n
	)

Appends n first bytes of a string to the end of a dynamic string.

Destination storage is automatically grown if necessary.

Warning

s must be initialized before calling this function.

UB if n > 0 and str is shorter than n bytes.

Parameters

s	Destination string to append to (borrowed).
str	String to append (borrowed, read-only).
n	Number of bytes to append, or -1 to use str_len(str).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_append_vformat()

bool string_append_vformat	(	t_string *	string,
		const char *	fstring,
		va_list	args
	)

Appends formatted text to string using va_list.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
fstring	Format string (borrowed, read-only).
args	Variable argument list.

Returns

true on success, false on failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_cmp()

bool string_cmp	(	const t_string *	a,
		const t_string *	b
	)

Compares two strings byte by byte.

Warning

a and b must be initialized before calling this function.

Parameters

a	First string to compare (borrowed, read-only).
b	Second string to compare (borrowed, read-only).

Returns

true if the strings have the same length and content, false otherwise.

string_dup()

bool string_dup	(	t_string *	dst,
		const t_string *	src
	)

Copies the content of a source string into an existing string.

Warning

dst and src must be initialized before calling this function.

The previous logical content of dst is replaced, whether the function succeeds or fails.

Parameters

dst	Destination string to overwrite (borrowed, initialized by the function).
src	Source string to duplicate (borrowed, initialized).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_dup_n()

bool string_dup_n	(	t_string *	dst,
		const t_string *	src,
		size_t	n
	)

Copies up to n bytes from a source string into an existing string.

Warning

dst and src must be initialized before calling this function.

The previous logical content of dst is replaced, whether the function succeeds or fails.

Parameters

dst	Destination string to overwrite (borrowed, initialized by the function).
src	Source string to duplicate (borrowed, initialized).
n	Maximum number of bytes to copy.

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_free()

void string_free

(

t_string *

string

)

Frees the string's internal data.

Frees string->data only when string owns its storage, that is when string->cap is greater than 0. Then sets string->data to NULL and string->len and string->cap to 0.

Warning

Does not free the t_string struct itself, only its internal data.

Parameters

string

Pointer to the string (borrowed).

Here is the caller graph for this function:

string_free_void()

void string_free_void

(

void *

string

)

Frees a t_string item through a generic void* callback signature.

Wrapper around string_free() intended for APIs that expect void (*)(void *), such as vector_free().

Warning

string must point to an initialized t_string.

Does not free the t_string struct itself, only its internal data.

Parameters

string

Pointer to a t_string item passed as void* (borrowed).

Here is the call graph for this function:

Here is the caller graph for this function:

string_get_index_c()

ssize_t string_get_index_c	(	const t_string *	string,
		char	c
	)

Finds the index of the first occurrence of a character in the string.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed, read-only).
c	Character to find.

Returns

Index of the character, or -1 if not found.

string_get_index_s()

ssize_t string_get_index_s	(	const t_string *	string,
		const char *	s,
		ssize_t	slen
	)

Finds the first occurrence of a substring in the string.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed, read-only).
s	Substring to find (borrowed, read-only).
slen	Number of bytes in s, or -1 to use str_len(s).

Returns

Index of the substring, or -1 if not found.

Here is the call graph for this function:

string_init()

bool string_init	(	t_string *	s,
		size_t	initial_cap,
		const char *	str,
		long	n
	)

Initializes a string with the specified initial capacity.

If str is not NULL, it is appended after initialization. If str is NULL, n is ignored.

Note

Cannot fail only when initial_cap == 0 and str == NULL.

Warning

When initial_cap == 0 and str == NULL, no allocation is performed: data is NULL and cannot be used as a valid C string until a function that allocates storage has been called.

Parameters

s	Pointer to the string structure to initialize (borrowed, uninitialized).
initial_cap	Initial capacity of the string.
str	Optional string to append after initialization (borrowed, read-only).
n	Number of bytes to append, or -1 to use str_len(str).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_insert()

bool string_insert	(	t_string *	dst,
		size_t	index,
		const t_string *	src
	)

Inserts a source string in a string at the specified index.

Destination storage is automatically grown if necessary.

Warning

dst and src must be initialized before calling this function.

index must be in range [0, dst->len].

Parameters

dst	Destination string to insert into (borrowed).
index	Insertion index.
src	Source string to insert (borrowed, read-only).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

string_insert_n()

bool string_insert_n	(	t_string *	s,
		size_t	index,
		const char *	str,
		long	n
	)

Inserts n first bytes of a string at the specified index.

Destination storage is automatically grown if necessary.

Warning

s must be initialized before calling this function.

index must be in range [0, s->len].

UB if n > 0 and str is shorter than n bytes.

Parameters

s	Destination string to insert into (borrowed).
index	Insertion index.
str	String to insert (borrowed, read-only).
n	Number of bytes to insert, or -1 to use str_len(str).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_prepend()

bool string_prepend	(	t_string *	dst,
		const t_string *	src
	)

Prepends a source string to the beginning of a string.

Destination storage is automatically grown if necessary.

Warning

dst and src must be initialized before calling this function.

Parameters

dst	Destination string to prepend to (borrowed).
src	Source string to prepend (borrowed, read-only).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

string_prepend_n()

bool string_prepend_n	(	t_string *	s,
		const char *	str,
		long	n
	)

Prepends n first bytes of a string to the beginning of a string.

Destination storage is automatically grown if necessary.

Warning

s must be initialized before calling this function.

UB if n > 0 and str is shorter than n bytes.

Parameters

s	Destination string to prepend to (borrowed).
str	String to prepend (borrowed, read-only).
n	Number of bytes to prepend, or -1 to use str_len(str).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

Here is the caller graph for this function:

string_read_all()

bool string_read_all	(	t_string *	string,
		int	fd
	)

Reads all available data from a file descriptor into string.

Note

Interrupted reads (EINTR) are retried.

On failure, string->data is NOT automatically freed.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
fd	File descriptor to read from.

Returns

true on success, false if read failed.

Here is the call graph for this function:

string_read_until_c()

bool string_read_until_c	(	t_string *	string,
		int	fd,
		char	c
	)

Reads from a file descriptor until a specific character is found.

Note

Interrupted reads (EINTR) are retried.

On failure, string->data is NOT automatically freed.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
fd	File descriptor to read from.
c	Character to search for.

Returns

true if c or EOF was encountered, false on memory or read error.

Here is the call graph for this function:

string_read_until_n()

bool string_read_until_n	(	t_string *	string,
		int	fd,
		size_t	n
	)

Reads up to n bytes from a file descriptor into string.

Note

Interrupted reads (EINTR) are retried.

On failure, string->data is NOT automatically freed.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
fd	File descriptor to read from.
n	Number of bytes to read.

Returns

true on success or EOF, false on memory or read error.

Here is the call graph for this function:

string_read_until_s()

bool string_read_until_s	(	t_string *	string,
		int	fd,
		const char *	s,
		ssize_t	slen
	)

Reads from a file descriptor until a specific substring is found.

Note

Interrupted reads (EINTR) are retried.

On failure, string->data is NOT automatically freed.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
fd	File descriptor to read from.
s	Target substring to search for (borrowed, read-only).
slen	Length of s, or -1 to use str_len(s).

Returns

true if s or EOF was encountered, false on memory or read error.

Here is the call graph for this function:

string_rm_part()

void string_rm_part	(	t_string *	string,
		size_t	i_start,
		ssize_t	len
	)

Removes a portion of the string starting at i_start.

Note

If len < 0, deletes all string content from i_start to end.

Warning

string must be initialized before calling this function.

Parameters

string	Pointer to an initialized string (borrowed).
i_start	Starting index for removal.
len	Number of bytes to remove, or negative to remove until end.

Here is the call graph for this function:

Here is the caller graph for this function:

string_split_at()

bool string_split_at	(	const t_string *	src,
		size_t	index,
		t_string *	out_before,
		t_string *	out_after
	)

Splits a string into two initialized strings at a byte index.

Note

out_before and out_after are initialized by the function.

When index is greater than or equal to src->len, out_before receives a full copy of src and out_after is initialized empty.

Warning

src must be initialized before calling this function.

out_before and out_after must not already own allocated data.

Parameters

src	Source string to split (borrowed, read-only).
index	Split index.
out_before	Destination receiving the bytes before index (borrowed, initialized by the function).
out_after	Destination receiving the bytes starting at index (borrowed, initialized by the function).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

string_split_on_char()

bool string_split_on_char	(	const t_string *	src,
		char	c,
		bool	keep_empty_entries,
		t_vector *	out
	)

Splits a string on a delimiter character into a t_vector.

Empty fields are kept when keep_empty_entries is true and skipped when it is false.

Note

out is initialized by the function with sizeof(t_string) items.

When keep_empty_entries is true and src is empty, out receives one empty t_string.

On failure, the function frees every initialized item and resets out.

Warning

src must be initialized before calling this function.

out must not already own allocated data.

Parameters

src	Source string to split (borrowed, read-only).
c	Delimiter character.
keep_empty_entries	True to keep empty fields, false to drop them.
out	Destination vector receiving initialized t_string items (borrowed, initialized by the function).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

string_split_on_string()

bool string_split_on_string	(	const t_string *	src,
		const char *	sep,
		bool	keep_empty_entries,
		t_vector *	out
	)

Splits a string on a delimiter C-string into a t_vector.

Empty fields are kept when keep_empty_entries is true and skipped when it is false.

Note

out is initialized by the function with sizeof(t_string) items.

When sep is empty and keep_empty_entries is true, out receives one item containing a full copy of src.

When sep is empty and keep_empty_entries is false, out receives one item only if src is not empty.

On failure, the function frees every initialized item and resets out.

Warning

src must be initialized before calling this function.

sep must point to a valid NUL-terminated C-string.

out must not already own allocated data.

Parameters

src	Source string to split (borrowed, read-only).
sep	Delimiter C-string (borrowed, read-only).
keep_empty_entries	True to keep empty fields, false to drop them.
out	Destination vector receiving initialized t_string items (borrowed, initialized by the function).

Returns

true on success, false on memory allocation failure.

Here is the call graph for this function:

string_take()

void string_take	(	t_string *	dst,
		char *	src,
		size_t	cap,
		ssize_t	len
	)

Installs an existing buffer in a string without copying it.

The buffer is not copied. The string structure is updated to reference the provided storage directly. When cap is 0, dst borrows src. When cap is greater than 0, dst owns src.

Warning

dst must point to an initialized t_string.

Parameters

dst	Destination string to update (borrowed).
src	Buffer installed in dst (borrowed, read-only).
cap	Capacity of src, in bytes.
len	Logical length of the string stored in src or -1 to use str_len().

Here is the call graph for this function:

string_take_string()

void string_take_string	(	t_string *	dst,
		t_string *	src
	)

Move the internal storage of one string into another string.

The internal data is not copied. After the move, src keeps the same data and len values but its cap is set to 0.

Note

Calling string_free() on src after a successful move is unnecessary but safe.

If the caller later modifies src through an API that grows or reallocates storage, new storage is allocated for src instead of reusing the moved storage.

Warning

The previous content of dst is overwritten without being freed.

Parameters

dst	Destination string receiving the moved storage (borrowed).
src	Source string whose storage is moved to dst (borrowed).

string_trim_leading()

void string_trim_leading	(	t_string *	string,
		char	c
	)

Removes leading copies of a character from a string.

Note

The string is modified in place and no allocation is performed.

Warning

string must be initialized before calling this function.

Parameters

string	String to trim (borrowed).
c	Character to remove.

Here is the call graph for this function: