Mutable strings

Heap-allocated mutable string-builder type, complement to the immutable rchar * helpers in rlib/rstr.h. More...

Files
file	rstring.h
	Mutable string-builder type.

Typedefs
typedef struct RString	RString
	Opaque heap-allocated mutable string.

Lifecycle
R_ATTR_WARN_UNUSED_RESULT RString *	r_string_new (const rchar *cstr)
	Allocate an RString seeded from the NUL-terminated cstr.
R_ATTR_WARN_UNUSED_RESULT RString *	r_string_new_sized (rsize size)
	Allocate an empty RString with size bytes of buffer reserved up front.
void	r_string_free (RString *str)
	Free the RString and its backing buffer.
R_ATTR_WARN_UNUSED_RESULT rchar *	r_string_free_keep (RString *str)
	Free the RString struct but return its inner rchar *.

Queries
rsize	r_string_length (RString *str)
	Current length in bytes (excluding the terminating NUL).
rsize	r_string_alloc_size (RString *str)
	Capacity of the underlying buffer in bytes.
int	r_string_cmp (RString *str1, RString *str2)
	Byte-compare two RString contents. Behaves like r_strcmp.
int	r_string_cmp_cstr (RString *str, const rchar *cstr)
	Byte-compare an RString against a NUL-terminated C string.

Mutations
Each returns the number of bytes added or removed by the operation, not the resulting total length (the exceptions are r_string_reset and r_string_erase, which return the resulting length). Family layout: reset → append* → prepend* → insert* → overwrite* → truncate / erase. The _len variants take an explicit byte count, useful for non-NUL-terminated source spans; the _printf / _vprintf variants format their arguments via the C runtime's printf into the build buffer in one step.
rsize	r_string_reset (RString *str, const rchar *cstr)
	Discard the current contents and seed str from a fresh NUL-terminated C string.
rsize	r_string_append_c (RString *str, rchar c)
	Append a single byte to str.
rsize	r_string_append (RString *str, const rchar *cstr)
	Append a NUL-terminated C string to str.
rsize	r_string_append_len (RString *str, const rchar *cstr, rsize len)
	Append len bytes from cstr to str.
rsize	r_string_append_printf (RString *str, const rchar *fmt,...)
	printf-format and append the result to str.
rsize	r_string_append_vprintf (RString *str, const rchar *fmt, va_list ap)
	va_list flavour of r_string_append_printf.
rsize	r_string_prepend (RString *str, const rchar *cstr)
	Prepend a NUL-terminated C string to the front of str.
rsize	r_string_prepend_len (RString *str, const rchar *cstr, rsize len)
	Prepend len bytes from cstr to the front of str.
rsize	r_string_prepend_printf (RString *str, const rchar *fmt,...)
	printf-format and prepend the result to the front of str.
rsize	r_string_prepend_vprintf (RString *str, const rchar *fmt, va_list ap)
	va_list flavour of r_string_prepend_printf.
rsize	r_string_insert (RString *str, rsize pos, const rchar *cstr)
	Insert cstr at byte offset pos, sliding the existing tail to the right.
rsize	r_string_insert_len (RString *str, rsize pos, const rchar *cstr, rsize len)
	Length-bounded variant of r_string_insert.
rsize	r_string_overwrite (RString *str, rsize pos, const rchar *cstr)
	Overwrite bytes starting at pos with cstr.
rsize	r_string_overwrite_len (RString *str, rsize pos, const rchar *cstr, rsize len)
	Length-bounded variant of r_string_overwrite.
rsize	r_string_truncate (RString *str, rsize len)
	Trim str to len bytes (no-op, returning 0, if already shorter).
rsize	r_string_erase (RString *str, rsize pos, rsize len)
	Remove len bytes starting at byte offset pos (clamped to the end of the string).

Detailed Description

Heap-allocated mutable string-builder type, complement to the immutable rchar * helpers in rlib/rstr.h.

Function Documentation

r_string_append_printf()

rsize r_string_append_printf	(	RString *	str,
		const rchar *	fmt,
			...
	)

printf-format and append the result to str.

Returns

Number of bytes appended.

r_string_erase()

rsize r_string_erase	(	RString *	str,
		rsize	pos,
		rsize	len
	)

Remove len bytes starting at byte offset pos (clamped to the end of the string).

Returns

The resulting length (0 if pos is past the end).

r_string_free_keep()

R_ATTR_WARN_UNUSED_RESULT rchar * r_string_free_keep

(

RString *

str

)

Free the RString struct but return its inner rchar *.

Ownership of the returned buffer transfers to the caller, who is responsible for r_free'ing it. Useful when the build-up phase is over and the string proper is what gets handed downstream.

r_string_insert()

rsize r_string_insert	(	RString *	str,
		rsize	pos,
		const rchar *	cstr
	)

Insert cstr at byte offset pos, sliding the existing tail to the right.

Returns

Number of bytes inserted.

r_string_new()

R_ATTR_WARN_UNUSED_RESULT RString * r_string_new

(

const rchar *

cstr

)

Allocate an RString seeded from the NUL-terminated cstr.

Parameters

cstr	Initial contents; pass NULL for an empty string.

Returns

The allocated RString, or NULL on allocation failure. Caller r_string_free's.

r_string_new_sized()

R_ATTR_WARN_UNUSED_RESULT RString * r_string_new_sized

(

rsize

size

)

Allocate an empty RString with size bytes of buffer reserved up front.

Useful when the caller knows roughly how much they're going to append, to skip a few of the growth-doubling steps.

Parameters

size	Initial buffer capacity in bytes (not including the terminating NUL).

r_string_overwrite()

rsize r_string_overwrite	(	RString *	str,
		rsize	pos,
		const rchar *	cstr
	)

Overwrite bytes starting at pos with cstr.

Unlike insert, no existing bytes shift; the string grows only if the write extends past the current length.

r_string_reset()

rsize r_string_reset	(	RString *	str,
		const rchar *	cstr
	)

Discard the current contents and seed str from a fresh NUL-terminated C string.

Parameters

str	Target string.
cstr	Replacement contents; pass NULL or "" to clear.

Returns

New length after the reset.

r_string_truncate()

rsize r_string_truncate	(	RString *	str,
		rsize	len
	)

Trim str to len bytes (no-op, returning 0, if already shorter).

Returns

Number of bytes removed.