Proposal: Bounds-tracked String Builder API (xc_str_builder_t)

[NKS01X]

Proposal: Bounds-tracked String Builder API (xc_str_builder_t)

Is your feature request related to a problem?

While lib0xc provides fantastic bounds-tracked I/O and memory cursors (cursor_t), string manipulation still largely relies on standard libc functions. Standard C string functions are inherently prone to buffer overflows, and even "safer" alternatives like snprintf can be counter-intuitive—silently truncating data and returning lengths that can easily lead to out-of-bounds writes if the developer isn't extremely careful with the math.

Describe the solution you'd like

I propose adding a static, bounds-tracked String Builder API. It perfectly aligns with lib0xc's philosophy of strict bounds checking and zero dynamic allocation.

The API would wrap a pre-allocated user buffer (e.g., a stack-allocated array) and enforce hard boundaries, making buffer overflows mathematically impossible and treating truncation as a hard, explicit error rather than a silent failure.

Proposed Structure and API

typedef struct {
    char *buffer;      // Pointer to the start of the pre-allocated memory
    size_t capacity;   // The hard limit of the buffer (including \0)
    size_t length;     // The current length of the string
} xc_str_builder_t;

// Initializes the builder, wrapping an existing buffer safely
bool xc_str_builder_init(xc_str_builder_t *sb, char *buffer, size_t capacity);

// Appends a string. Returns false if it exceeds capacity. 
// Uses O(1) appending rather than O(N) strcat traversal.
bool xc_str_builder_append(xc_str_builder_t *sb, const char *suffix);

// Safely formats and appends data, replacing dangerous snprintf math.
bool xc_str_builder_appendf(xc_str_builder_t *sb, const char *format, ...);

Why this fits lib0xc

1. No malloc needed: It works purely on buffers provided by the user.
2. Explicit Failure: Unlike snprintf, if the text does not fit, the functions simply return false (or trigger a panic/error state depending on project preference), ensuring the developer handles the error immediately.
3. Performance & Safety: Eliminates the need for constant strlen checking and completely mitigates off-by-one errors during string concatenation.

Next Steps

I am currently actively working on the implementation for this and will be opening a Pull Request shortly. Please assign this issue to me if possible!