cstr.h File Reference

Go to the source code of this file.

Classes
struct	CSTR
	Custom dynamic string type. More...

Functions
static int	__cstr_setFormat (CSTR *_str, const char *_fmt,...)
	Internal helper to format and set the string content.
int	__cstr_updateCap (CSTR *_str)
	Update the capacity automatically IMPORTANT: This function won't do anything if macro CSTR_DYNAMIC_CAPACITY is NOT defined.
int	cstr_add (CSTR *_str, const char *_suffix)
	Append a suffix to the end of a CSTR.
const char *	cstr_bool (const bool _bool)
	Return "true" or "false" based on a boolean value.
int	cstr_clear (CSTR *_str)
	Clear a CSTR to an empty string without freeing memory.
bool	cstr_comp (const CSTR _s1, const CSTR _s2)
	Compare two CSTR instances for equality.
size_t	cstr_count (const CSTR *_str, const char *ch)
	Count occurrences of a substring within a CSTR.
size_t	cstr_countChar (const CSTR *_str, const char ch)
	Count occurrences of a single character within a CSTR.
int	cstr_destroy (CSTR *_str)
	Destroy and clean up a CSTR and its allocated objects.
bool	cstr_empty (const CSTR *_str)
	Get if the string is empty Return true if: .len smaller or equal to 0 .data is empty ("") .initialized is false _str is NULL If none of the requirements are met, means that it's not empty, hence, return false.
bool	cstr_endsWith (const CSTR _str, const char *_suffix)
	Check if a CSTR ends with the given suffix.
int	cstr_erase (CSTR *_str, int _pos, size_t _len)
	Erase a portion of the string.
size_t	cstr_find (const CSTR *_str, const char *_find)
	Find the first occurrence of a substring.
size_t	cstr_findFrom (const CSTR *_str, const char *_find, size_t pos)
	Find a substring starting from a specific index.
int	cstr_fromDouble (CSTR *_str, double _val)
	Create a numeric string from a double.
int	cstr_fromFloat (CSTR *_str, float _val)
	Create a numeric string from a float.
int	cstr_fromHex (CSTR *_str, unsigned int _val)
	Create a hexadecimal string from an unsigned integer.
int	cstr_fromInt (CSTR *_str, int _val)
	Create a numeric string from an integer.
int	cstr_fromLong (CSTR *_str, long _val)
	Create a numeric string from a long.
CSTR	cstr_init (void)
	Initialize a new empty CSTR.
int	cstr_initCopy (CSTR *_dest, const char *_src)
	Initialize a CSTR with a copy of an original C-string.
int	cstr_insert (CSTR *_str, const char *_data, size_t _pos)
	Insert a string at a specific position in a CSTR.
int	cstr_lower (CSTR *_str)
	Convert all characters in a CSTR to lowercase.
int	cstr_replace (CSTR *_str, const char *_old, const char *_new)
	Replace only the first occurrence of a substring.
int	cstr_replaceAll (CSTR *_str, const char *_old, const char *_new)
	Replace all occurrences of a substring.
int	cstr_reverse (CSTR *_str)
	Reverse the content of a CSTR in place.
int	cstr_set (CSTR *_str, const char *_data)
	Set the content of a CSTR to a new C-string in .data.
int	cstr_shrink (CSTR *_str, const size_t _len)
	Clear the content of a CSTR and optionally shrink capacity.
bool	cstr_startsWith (CSTR _str, const char *_prefix)
	Check if a CSTR begins with the given prefix.
int	cstr_substr (CSTR *_str, size_t _start, size_t _len)
	Extract a substring in place from a CSTR.
int	cstr_upper (CSTR *_str)
	Convert all characters in a CSTR to uppercase.

Function Documentation

__cstr_setFormat()

int __cstr_setFormat ( CSTR * _str, const char * _fmt, ... )

static

Internal helper to format and set the string content.

Uses a printf-style format string and variadic arguments to overwrite the content of a CSTR. The function computes the required buffer size, reallocates if needed (unless forceCap is active), formats the string, and updates length/capacity.

Parameters

_str	Pointer to the CSTR to modify.
_fmt	printf-style format string.
...	Variadic arguments corresponding to the format.

Returns

• CSTR_SUCCESS on success
• CSTR_FAIL if parameters are invalid, allocation fails, or vsnprintf reports an error
• CSTR_FORCECAP_LIMIT if forceCap is enabled and the required size exceeds current capacity

Note

Typically used in the other defined functions for CSTR inner API

__cstr_updateCap()

int __cstr_updateCap

(

CSTR *

_str

)

Update the capacity automatically IMPORTANT: This function won't do anything if macro CSTR_DYNAMIC_CAPACITY is NOT defined.

Returns

Return if fail or success

Note

Typically used in the other defined functions for CSTR inner API

cstr_add()

int cstr_add	(	CSTR *	_str,
		const char *	_suffix )

Append a suffix to the end of a CSTR.

Parameters

_str	Pointer to the CSTR to modify
_suffix	NULL terminated string to append

Returns

CSTR_SUCCESS, CSTR_FAIL, or CSTR_FORCECAP_LIMIT

cstr_bool()

const char * cstr_bool

(

const bool

_bool

)

Return "true" or "false" based on a boolean value.

Parameters

_bool

Boolean value

Returns

"true" if _bool is true, otherwise "false".

cstr_clear()

int cstr_clear

(

CSTR *

_str

)

Clear a CSTR to an empty string without freeing memory.

Parameters

_str	Pointer to the CSTR to clear

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_comp()

bool cstr_comp	(	const CSTR	_s1,
		const CSTR	_s2 )

Compare two CSTR instances for equality.

Parameters

_s1	First CSTR (by value)
_s2	Second CSTR (by value)

Returns

true if equal, false otherwise

cstr_count()

size_t cstr_count	(	const CSTR *	_str,
		const char *	ch )

Count occurrences of a substring within a CSTR.

Searches for non-overlapping occurrences of a null-terminated substring inside the CSTR’s .data buffer using strstr. Each found instance advances the scan position by the length of the substring, preventing overlapping matches.

Parameters

_str	Pointer to the CSTR to inspect
ch	Null-terminated substring to count

Returns

Number of non-overlapping occurrences found Returns 0 if parameters are invalid (_str, .data, ch, or *ch)

cstr_countChar()

size_t cstr_countChar	(	const CSTR *	_str,
		const char	ch )

Count occurrences of a single character within a CSTR.

Iterates through the string and counts how many times the specified character appears in the .data buffer.

Parameters

_str	Pointer to the CSTR to inspect
ch	Character to count

Returns

Number of occurrences of ch in the string Returns 0 if _str is NULL or not initialized

Note

This function performs a linear scan across all characters.

cstr_destroy()

int cstr_destroy

(

CSTR *

_str

)

Destroy and clean up a CSTR and its allocated objects.

Parameters

_str	Pointer to the CSTR to destroy

Returns

CSTR_SUCCESS on success, otherwise CSTR_FAIL

cstr_empty()

bool cstr_empty

(

const CSTR *

_str

)

Get if the string is empty Return true if: .len smaller or equal to 0 .data is empty ("") .initialized is false _str is NULL If none of the requirements are met, means that it's not empty, hence, return false.

Returns

Is the string empty? Yes (true), No (false)

cstr_endsWith()

bool cstr_endsWith	(	const CSTR	_str,
		const char *	_suffix )

Check if a CSTR ends with the given suffix.

Parameters

_str	The CSTR to check (by value)
_suffix	The suffix string

Returns

true if it ends with suffix, false otherwise

cstr_erase()

int cstr_erase	(	CSTR *	_str,
		int	_pos,
		size_t	_len )

Erase a portion of the string.

Parameters

_str	Pointer to the CSTR
_pos	Starting position
_len	Number of characters to remove

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_find()

size_t cstr_find	(	const CSTR *	_str,
		const char *	_find )

Find the first occurrence of a substring.

Parameters

_str	Pointer to the CSTR to search
_find	Substring to locate

Returns

Index of first match, or CSTR_NPOS if not found

cstr_findFrom()

size_t cstr_findFrom	(	const CSTR *	_str,
		const char *	_find,
		size_t	pos )

Find a substring starting from a specific index.

Parameters

_str	Pointer to the CSTR to search
_find	Substring to locate
pos	Starting index

Returns

Index of match, or CSTR_NPOS if not found

cstr_fromDouble()

int cstr_fromDouble	(	CSTR *	_str,
		double	_val )

Create a numeric string from a double.

cstr_fromFloat()

int cstr_fromFloat	(	CSTR *	_str,
		float	_val )

Create a numeric string from a float.

cstr_fromHex()

int cstr_fromHex	(	CSTR *	_str,
		unsigned int	_val )

Create a hexadecimal string from an unsigned integer.

cstr_fromInt()

int cstr_fromInt	(	CSTR *	_str,
		int	_val )

Create a numeric string from an integer.

cstr_fromLong()

int cstr_fromLong	(	CSTR *	_str,
		long	_val )

Create a numeric string from a long.

cstr_init()

CSTR cstr_init

(

void

)

Initialize a new empty CSTR.

Returns

A new CSTR instance. Check .initialized or if CSTR is not NULL to confirm success

cstr_initCopy()

int cstr_initCopy	(	CSTR *	_dest,
		const char *	_src )

Initialize a CSTR with a copy of an original C-string.

Parameters

_dest	Pointer to the destination CSTR
_src	NULL terminated string to copy from

Returns

CSTR_SUCCESS on success, otherwise CSTR_FAIL

cstr_insert()

int cstr_insert	(	CSTR *	_str,
		const char *	_data,
		size_t	_pos )

Insert a string at a specific position in a CSTR.

Parameters

_str	Pointer to the CSTR to modify
_data	NULL terminated string to insert
_pos	Position at which to insert, 0-based

Returns

CSTR_SUCCESS, CSTR_FAIL, or CSTR_FORCECAP_LIMIT

cstr_lower()

int cstr_lower

(

CSTR *

_str

)

Convert all characters in a CSTR to lowercase.

Parameters

_str	Pointer to the CSTR to modify

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_replace()

int cstr_replace	(	CSTR *	_str,
		const char *	_old,
		const char *	_new )

Replace only the first occurrence of a substring.

Parameters

_str	Pointer to the CSTR
_old	Substring to locate
_new	Replacement string

Returns

CSTR_SUCCESS or an error code (CSTR_FAIL, ...)

cstr_replaceAll()

int cstr_replaceAll	(	CSTR *	_str,
		const char *	_old,
		const char *	_new )

Replace all occurrences of a substring.

Parameters

_str	Pointer to the CSTR
_old	Substring to locate
_new	Replacement string

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_reverse()

int cstr_reverse

(

CSTR *

_str

)

Reverse the content of a CSTR in place.

Parameters

_str	Pointer to the CSTR to modify

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_set()

int cstr_set	(	CSTR *	_str,
		const char *	_data )

Set the content of a CSTR to a new C-string in .data.

Parameters

_str	Pointer to the CSTR to modify
_data	Null terminated string to set

Returns

CSTR_SUCCESS, CSTR_FAIL, or CSTR_FORCECAP_LIMIT

cstr_shrink()

int cstr_shrink	(	CSTR *	_str,
		const size_t	_len )

Clear the content of a CSTR and optionally shrink capacity.

Parameters

_str	Pointer to the CSTR to shrink
_len	New length (characters to keep)

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_startsWith()

bool cstr_startsWith	(	CSTR	_str,
		const char *	_prefix )

Check if a CSTR begins with the given prefix.

Parameters

_str	The CSTR to check by value
_prefix	The prefix string

Returns

true if it starts with prefix, else return false

cstr_substr()

int cstr_substr	(	CSTR *	_str,
		size_t	_start,
		size_t	_len )

Extract a substring in place from a CSTR.

Parameters

_str	Pointer to the CSTR to modify
_start	Starting index of the substring
_len	Length of the substring

Returns

CSTR_SUCCESS or CSTR_FAIL

cstr_upper()

int cstr_upper

(

CSTR *

_str

)

Convert all characters in a CSTR to uppercase.

Parameters

_str	Pointer to the CSTR to modify

Returns

CSTR_SUCCESS or CSTR_FAIL