AxlString – String Builder
Mutable auto-growing string builder, like GLib’s GString. All strings
are UTF-8. Supports append, prepend, insert, printf-style formatting, and
truncation.
Header: <axl/axl-string.h>
Overview
Use AxlString when you need to build a string incrementally (in a
loop, with formatting, from multiple sources). For simple one-shot
formatting, use axl_asprintf instead.
AXL_AUTOPTR(AxlString) s = axl_string_new("Hello");
axl_string_append(s, " ");
axl_string_printf(s, "world #%d", 42);
axl_string_append_c(s, '!');
axl_printf("%s\n", axl_string_str(s)); // "Hello world #42!"
axl_printf("length: %zu\n", axl_string_len(s));
Stealing the Buffer
Transfer ownership of the internal buffer to avoid a copy:
AXL_AUTOPTR(AxlString) b = axl_string_new(NULL);
axl_string_printf(b, "key=%s", value);
char *result = axl_string_steal(b); // b is now empty
// caller owns 'result', must free with axl_free()
The builder can be reused after stealing – it starts empty with its allocated buffer released.
Error Handling
All mutation functions (append, printf, etc.) return int:
0 on success, -1 if the internal realloc fails. This matches the
convention used by axl_array_append, axl_hash_table_set, etc.
API Reference
Functions
-
AxlString *axl_string_new(const char *init)
Create a new string builder.
If init is non-NULL, the string is initialized with that content. Pass NULL for an empty string builder.
- Parameters:
init – initial content (NULL for empty)
- Returns:
a new AxlString, or NULL on allocation failure. Free with axl_string_free().
-
AxlString *axl_string_new_size(size_t reserve)
Create a new string builder with pre-reserved capacity.
- Parameters:
reserve – initial capacity in bytes
- Returns:
a new AxlString, or NULL on allocation failure.
-
int axl_string_append(AxlString *b, const char *s)
Append a string. NULL is treated as empty.
- Parameters:
b – string builder
s – NUL-terminated string to append
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_append_len(AxlString *b, const char *data, size_t len)
Append exactly len bytes from data.
- Parameters:
b – string builder
data – bytes to append (not necessarily NUL-terminated)
len – number of bytes
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_printf(AxlString *b, const char *fmt, ...)
Append formatted text. Auto-grows the buffer as needed.
- Parameters:
b – string builder
fmt – printf-style format string
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_append_c(AxlString *b, char c)
Append a single character.
- Parameters:
b – string builder
c – character to append
- Returns:
0 on success, -1 on allocation failure.
-
const char *axl_string_str(AxlString *b)
Get the current string content.
The returned pointer is owned by the builder and becomes invalid after modification or free.
- Parameters:
b – string builder
- Returns:
NUL-terminated string, or “” if builder is NULL.
-
size_t axl_string_len(AxlString *b)
Get current string length.
- Parameters:
b – string builder
- Returns:
current string length (not counting NUL terminator).
-
char *axl_string_steal(AxlString *b)
Transfer ownership of the internal string to the caller.
The builder is left empty (len=0). Caller frees with axl_free().
- Parameters:
b – string builder
- Returns:
the string, or NULL if empty/allocation failed.
-
void axl_string_clear(AxlString *b)
Reset to empty string. Keeps the allocated buffer for reuse.
- Parameters:
b – string builder
-
void axl_string_free(AxlString *b)
Free the builder and its internal buffer. NULL-safe.
- Parameters:
b – string builder, or NULL
-
char *axl_asprintf(const char *fmt, ...)
Format a string into a newly allocated buffer.
Like GLib’s g_strdup_printf(). Caller frees with axl_free().
- Parameters:
fmt – printf-style format string
- Returns:
formatted string, or NULL on failure.