base_string.h File Reference

#include <stddef.h>

Include dependency graph for base_string.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	string
	Structure representing a dynamic string with capacity tracking. More...

Functions
string *	string_create (const char *initial)
	Creates and initializes a new string instance.
void	string_destroy (string *str)
	Destroys a string instance and frees its allocated memory.
size_t	string_length (const string *str)
	Retrieves the current length of the string.
size_t	string_capacity (const string *str)
	Retrieves the current capacity of the string buffer.
void	string_concat (string *str, const char *suffix)
	Appends a C-string to the end of the existing string.
int	string_compare (const string *str_1, const string *str_2)
	Lexicographically compares two string instances.
void	string_clear (string *str)
	Clears the contents of the string, resetting its size to 0 without reallocating memory.
char *	string_to_c (const string *str)
	Returns a pointer to the internal C-style null-terminated string.
void	string_reserve (string *str, size_t new_capacity)
	Ensures that the string buffer has at least the specified capacity.
void	string_set (string *str, const char *new_value)
	Overwrites the current content of the string with a new value.
int	string_contains (const string *str, const char *substring)
	Checks if the string contains a specific substring.
string **	string_split (const string *str, const char *delimiter, size_t *num_tokens)
	Splits the string into an array of tokens using a specified delimiter.
void	string_replace (string *str, const char *old_substring, const char *new_substring)
	Replaces all occurrences of a target substring with a new substring.

Function Documentation

string_capacity()

size_t string_capacity

(

const string *

str

)

Retrieves the current capacity of the string buffer.

Parameters

str	Pointer to the string.

Returns

The total buffer capacity in bytes.

string_clear()

void string_clear

(

string *

str

)

Clears the contents of the string, resetting its size to 0 without reallocating memory.

Parameters

str	Pointer to the string to clear.

string_compare()

int string_compare	(	const string *	str_1,
		const string *	str_2
	)

Lexicographically compares two string instances.

Parameters

str_1	Pointer to the first string.
str_2	Pointer to the second string.

Returns

An integer less than, equal to, or greater than zero if str_1 is found, respectively, to be less than, to match, or be greater than str_2.

string_concat()

void string_concat	(	string *	str,
		const char *	suffix
	)

Appends a C-string to the end of the existing string.

Parameters

str	Pointer to the destination string.
suffix	Null-terminated C-string to append.

string_contains()

int string_contains	(	const string *	str,
		const char *	substring
	)

Checks if the string contains a specific substring.

Parameters

str	Pointer to the string to search in.
substring	Null-terminated C-string to search for.

Returns

1 if the substring is found, 0 otherwise.

string_create()

string * string_create

(

const char *

initial

)

Creates and initializes a new string instance.

Parameters

initial

Null-terminated initial C-string. If NULL, an empty string is created.

Returns

Pointer to the newly allocated string, or NULL on allocation failure.

Note

The returned pointer must be freed using string_destroy().

string_destroy()

void string_destroy

(

string *

str

)

Destroys a string instance and frees its allocated memory.

Parameters

str	Pointer to the string to destroy. If NULL, no action is taken.

string_length()

size_t string_length

(

const string *

str

)

Retrieves the current length of the string.

Parameters

str	Pointer to the string.

Returns

The number of characters in the string (excluding the null terminator).

string_replace()

void string_replace	(	string *	str,
		const char *	old_substring,
		const char *	new_substring
	)

Replaces all occurrences of a target substring with a new substring.

Parameters

str	Pointer to the string to modify.
old_substring	Substring to be replaced.
new_substring	Substring to insert in place of old_substring.

string_reserve()

void string_reserve	(	string *	str,
		size_t	new_capacity
	)

Ensures that the string buffer has at least the specified capacity.

Parameters

str	Pointer to the string.
new_capacity	Minimum required capacity in bytes.

string_set()

void string_set	(	string *	str,
		const char *	new_value
	)

Overwrites the current content of the string with a new value.

Parameters

str	Pointer to the string to modify.
new_value	Null-terminated C-string to set as the new content.

string_split()

string ** string_split	(	const string *	str,
		const char *	delimiter,
		size_t *	num_tokens
	)

Splits the string into an array of tokens using a specified delimiter.

Parameters

str	Pointer to the string to split.
delimiter	Null-terminated C-string used as the delimiter.
num_tokens	Pointer to a size_t where the count of created tokens will be stored.

Returns

Pointer to an array of dynamic string* tokens, or NULL on failure.

Note

Each element in the array must be destroyed individually using string_destroy(), and the returned array pointer itself must be released using free().

string_to_c()

char * string_to_c

(

const string *

str

)

Returns a pointer to the internal C-style null-terminated string.

Parameters

str	Pointer to the string.

Returns

Pointer to the underlying character array.

Warning

The returned pointer points directly to the structure's internal buffer. Do not attempt to free or directly modify this memory.