rstring.h File Reference

Mutable string-builder type. More...

#include <rlib/rtypes.h>
#include <stdarg.h>

Go to the source code of this file.

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

Functions
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

Mutable string-builder type.

RString complements the immutable rchar * helpers in rlib/rstr.h. Each instance owns a heap buffer that grows as needed when bytes are appended / inserted / overwritten, so callers don't have to chase capacity by hand. Construct with r_string_new or r_string_new_sized; release with r_string_free or, if you want to keep the inner rchar * after, r_string_free_keep.

Most mutating functions return the number of bytes they added or removed (r_string_reset and r_string_erase instead return the resulting length); a 0 return signals failure or a no-op.