Manipulation

Macros
#define	strNConcat(o, ...)   _strNConcat(o, count_macro_args(__VA_ARGS__), (strref[]) { __VA_ARGS__ })
#define	strNConcatC(o, ...)    _strNConcatC(o, count_macro_args(__VA_ARGS__), (string*[]) { __VA_ARGS__ })

Functions
bool	strAppend (strhandle io, strref s)
bool	strPrepend (strref s, strhandle io)
bool	strConcat (strhandle o, strref s1, strref s2)
bool	strConcatC (strhandle o, strhandle sc1, strhandle sc2)
bool	strSubStr (strhandle o, strref s, int32 b, int32 e)
bool	strSubStrC (strhandle o, strhandle sc, int32 b, int32 e)
bool	strSubStrI (strhandle io, int32 b, int32 e)
void	strUpper (strhandle io)
void	strLower (strhandle io)
int32	strSplit (sa_string *out, strref s, strref sep, bool empty)
bool	strJoin (strhandle out, sa_string arr, strref sep)
uint8	strGetChar (strref str, int32 i)
void	strSetChar (strhandle str, int32 i, uint8 ch)

Detailed Description

String manipulation operations for modifying, combining, and extracting portions of strings. Many operations have multiple variants optimized for different use cases.

Naming convention for function parameters

• o - Output string; existing content is destroyed and replaced
• io - Input+output string; modified in-place when possible
• s* - Input string; read-only, not modified
• sc* - Input string that is consumed; destroyed/reused efficiently, handle set to NULL

Consuming variants (functions with 'C' suffix)

Functions ending in 'C' (like strConcatC, strSubStrC) take ownership of their input strings and destroy them after use. This allows for more efficient memory reuse when you no longer need the source strings:

string s1 = _S"hello";
string s2 = _S" world";
string result = 0;
strConcatC(&result, &s1, &s2);  // s1 and s2 are now NULL

In-place variants (functions with 'I' suffix)

Functions ending in 'I' modify the string in-place, efficiently reusing the existing buffer when possible:

string s = _S"hello world";
strSubStrI(&s, 0, 5);  // s is now "hello"

Negative indices

Most functions accept negative indices to count from the end of the string: -1 refers to the last byte, -2 to second-to-last, etc.

Rope optimization

For large string operations, the library may use rope data structures internally to avoid copying. This is transparent to the caller but affects performance characteristics - very large concatenations and substrings are much faster.

Macro Definition Documentation

strNConcat

#define strNConcat	(		o,
			...
	)		_strNConcat(o, count_macro_args(__VA_ARGS__), (strref[]) { __VA_ARGS__ })

bool strNConcat(string *o, ...)

Concatenates multiple strings into an output string

Combines any number of strings into a single result. This is more efficient than calling strConcat() repeatedly. For very large results, may create a rope structure.

The macro accepts a variable number of string arguments and automatically counts them.

Parameters

o	Output string (existing content destroyed)
...	Variable number of string arguments to concatenate

Returns

true on success, false on error

Example:

string result = 0;
strNConcat(&result, _S"Hello", _S" ", _S"World", _S"!");
// result is "Hello World!"
strDestroy(&result);

Definition at line 161 of file strmanip.h.

strNConcatC

#define strNConcatC	(		o,
			...
	)		_strNConcatC(o, count_macro_args(__VA_ARGS__), (string*[]) { __VA_ARGS__ })

bool strNConcatC(string *o, string *s1, string *s2, ...)

Concatenates multiple strings, consuming all inputs

Like strNConcat(), but takes ownership of all input strings and destroys them after use. All input string handles will be NULL after this call. This is the most efficient way to combine many temporary strings.

The macro accepts a variable number of string handle pointers.

Parameters

o	Output string (existing content destroyed)
...	Variable number of string handle pointers (destroyed after use)

Returns

true on success, false on error

Example:

string s1 = 0, s2 = 0, s3 = 0, result = 0;
strDup(&s1, _S"Hello");
strDup(&s2, _S" ");
strDup(&s3, _S"World");
strNConcatC(&result, &s1, &s2, &s3);
// result is "Hello World", s1/s2/s3 are now NULL
strDestroy(&result);

Definition at line 188 of file strmanip.h.

Function Documentation

strAppend()

bool strAppend	(	strhandle	io,
		strref	s
	)

Appends a string to another string in-place

Adds the content of string s to the end of string io. The operation is performed in-place when possible for efficiency. For large strings, may create a rope structure instead of copying.

If io is NULL or empty, this is equivalent to strDup().

Parameters

io	String to append to (modified in-place)
s	String to append (not modified)

Returns

true on success, false on error

Example:

string s = 0;
strDup(&s, _S"Hello");
strAppend(&s, _S" World");  // s is now "Hello World"
strDestroy(&s);

strConcat()

bool strConcat	(	strhandle	o,
		strref	s1,
		strref	s2
	)

Concatenates two strings into an output string

Combines s1 and s2 into a new string stored in o. Any existing content in o is destroyed. For large strings, may create a rope structure for efficiency.

If o points to the same string as s1, this is optimized to behave like strAppend().

Parameters

o	Output string (existing content destroyed)
s1	First string (not modified)
s2	Second string (not modified)

Returns

true on success, false on error

Example:

string result = 0;
strConcat(&result, _S"Hello", _S" World");
// result is "Hello World"
strDestroy(&result);

strConcatC()

bool strConcatC	(	strhandle	o,
		strhandle	sc1,
		strhandle	sc2
	)

Concatenates two strings, consuming the inputs

Like strConcat(), but takes ownership of sc1 and sc2, destroying them after use. This allows for more efficient memory reuse when the source strings are no longer needed. Both sc1 and sc2 will be NULL after this call.

Parameters

o	Output string (existing content destroyed)
sc1	First string (destroyed after use)
sc2	Second string (destroyed after use)

Returns

true on success, false on error

Example:

string s1 = 0, s2 = 0, result = 0;
strDup(&s1, _S"Hello");
strDup(&s2, _S" World");
strConcatC(&result, &s1, &s2);
// result is "Hello World", s1 and s2 are now NULL
strDestroy(&result);

strGetChar()

uint8 strGetChar	(	strref	str,
		int32	i
	)

Retrieves a single byte from a string

Gets the byte at position i in the string. Negative indices count from the end. Returns 0 if the index is out of bounds.

Note: This operates on bytes, not UTF-8 characters. For multi-byte encodings, use a string iterator instead.

Parameters

str	String to read from
i	Index of byte to retrieve (negative = from end)

Returns

The byte at position i, or 0 if out of bounds

Example:

uint8 ch = strGetChar(_S"Hello", 0);    // 'H'
ch = strGetChar(_S"Hello", -1);         // 'o' (last char)

strJoin()

bool strJoin	(	strhandle	out,
		sa_string	arr,
		strref	sep
	)

Joins an array of strings into a single string with a separator

Combines all strings in the array into one string, inserting the separator between each element. The separator is not added before the first element or after the last element.

Parameters

out	Output string (existing content destroyed)
arr	Array of strings to join
sep	Separator to insert between elements

Returns

true on success, false if array is empty

Example:

sa_string parts = {0};
saPush(&parts, string, _S"Hello");
saPush(&parts, string, _S"World");
string result = 0;
strJoin(&result, parts, _S" ");
// result is "Hello World"
strDestroy(&result);
saDestroy(&parts);

strLower()

void strLower

(

strhandle

io

)

Converts a string to lowercase (ASCII only)

Modifies the string in-place, converting all uppercase ASCII letters (A-Z) to lowercase (a-z). This is ASCII-only and does not properly handle multi-byte UTF-8 characters or locale-specific case rules.

The string is flattened and made unique before modification.

Parameters

io	String to convert in-place

Example:

string s = 0;
strDup(&s, _S"HELLO WORLD");
strLower(&s);  // s is now "hello world"
strDestroy(&s);

strPrepend()

bool strPrepend	(	strref	s,
		strhandle	io
	)

Prepends a string to another string in-place

Adds the content of string s to the beginning of string io. This is less efficient than strAppend() because the entire string must be reconstructed.

Parameters

s	String to prepend (not modified)
io	String to prepend to (modified in-place)

Returns

true on success, false on error

Example:

string s = 0;
strDup(&s, _S"World");
strPrepend(_S"Hello ", &s);  // s is now "Hello World"
strDestroy(&s);

strSetChar()

void strSetChar	(	strhandle	str,
		int32	i,
		uint8	ch
	)

Sets a single byte in a string

Modifies the byte at position i in the string. Negative indices count from the end. Use strEnd for i to append a byte to the end of the string.

If the index is beyond the current length, the string is grown and zero-padded. The string is flattened and made unique before modification.

Note: This operates on bytes, not UTF-8 characters. Be careful when modifying multi-byte UTF-8 sequences as you can create invalid encodings.

Parameters

str	String to modify
i	Index of byte to set (negative = from end, strEnd = append)
ch	Byte value to set

Example:

string s = 0;
strDup(&s, _S"Hello");
strSetChar(&s, 0, 'h');      // s is now "hello"
strSetChar(&s, strEnd, '!'); // s is now "hello!"
strDestroy(&s);

strSplit()

int32 strSplit	(	sa_string *	out,
		strref	s,
		strref	sep,
		bool	empty
	)

Splits a string into pieces separated by a delimiter

Divides the string s into segments at each occurrence of the separator string, storing the results in a dynamic array. The output array is cleared first.

Parameters

out	Pointer to string array to store results (cleared first)
s	String to split
sep	Separator string to split on
empty	If true, empty segments are preserved; if false, they are skipped

Returns

Number of segments created

Example:

sa_string parts = {0};
strSplit(&parts, _S"a,b,c", _S",", false);
// parts contains ["a", "b", "c"]
for (int i = 0; i < saSize(parts); i++)
    strDestroy(&parts.a[i]);
saDestroy(&parts);
 
strSplit(&parts, _S"a,,b", _S",", true);
// parts contains ["a", "", "b"] (empty segment preserved)
saDestroy(&parts);

strSubStr()

bool strSubStr	(	strhandle	o,
		strref	s,
		int32	b,
		int32	e
	)

Extracts a substring from a string

Creates a new string containing bytes from position b (inclusive) to position e (exclusive). Negative indices count from the end. Use strEnd for e to extract to the end of the string.

For large substrings, may create a rope reference instead of copying the data.

Parameters

o	Output string (existing content destroyed)
s	Source string (not modified)
b	Starting position (negative = from end)
e	Ending position (negative = from end, strEnd = end of string)

Returns

true on success, false on error

Example:

string sub = 0;
strSubStr(&sub, _S"Hello World", 0, 5);    // "Hello"
strSubStr(&sub, _S"Hello World", 6, strEnd); // "World"
strSubStr(&sub, _S"Hello World", -5, strEnd); // "World" (last 5 chars)
strDestroy(&sub);

strSubStrC()

bool strSubStrC	(	strhandle	o,
		strhandle	sc,
		int32	b,
		int32	e
	)

Extracts a substring, consuming the source string

Like strSubStr(), but takes ownership of sc and destroys it after use. The sc handle will be NULL after this call. More efficient when the source is no longer needed.

Parameters

o	Output string (existing content destroyed)
sc	Source string (destroyed after use)
b	Starting position (negative = from end)
e	Ending position (negative = from end, strEnd = end of string)

Returns

true on success, false on error

Example:

string s = 0, sub = 0;
strDup(&s, _S"Hello World");
strSubStrC(&sub, &s, 0, 5);  // sub is "Hello", s is now NULL
strDestroy(&sub);

strSubStrI()

bool strSubStrI	(	strhandle	io,
		int32	b,
		int32	e
	)

Extracts a substring in-place

Modifies the string to contain only the specified range. This is the most efficient way to truncate or extract from a string when you don't need the original.

Parameters

io	String to modify in-place
b	Starting position (negative = from end)
e	Ending position (negative = from end, strEnd = end of string)

Returns

true on success, false on error

Example:

string s = 0;
strDup(&s, _S"Hello World");
strSubStrI(&s, 0, 5);  // s is now "Hello"
strDestroy(&s);

strUpper()

void strUpper

(

strhandle

io

)

Converts a string to uppercase (ASCII only)

Modifies the string in-place, converting all lowercase ASCII letters (a-z) to uppercase (A-Z). This is ASCII-only and does not properly handle multi-byte UTF-8 characters or locale-specific case rules.

The string is flattened and made unique before modification.

Parameters

io	String to convert in-place

Example:

string s = 0;
strDup(&s, _S"hello world");
strUpper(&s);  // s is now "HELLO WORLD"
strDestroy(&s);