AxlString – String Builder
See AxlData – Data Structures for an overview of all data modules including the string builder.
Header: <axl/axl-string.h>
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_append_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.
-
int axl_string_prepend(AxlString *b, const char *s)
Prepend a NUL-terminated string.
- Parameters:
b – string builder
s – NUL-terminated string to prepend
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_prepend_len(AxlString *b, const char *s, size_t len)
Prepend exactly len bytes from s.
- Parameters:
b – string builder
s – bytes to prepend
len – number of bytes
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_prepend_c(AxlString *b, char c)
Prepend a single character.
- Parameters:
b – string builder
c – character to prepend
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_insert(AxlString *b, size_t pos, const char *s)
Insert a NUL-terminated string at pos.
If pos >= current length, equivalent to append.
- Parameters:
b – string builder
pos – byte offset to insert at
s – NUL-terminated string to insert
- Returns:
0 on success, -1 on allocation failure.
-
int axl_string_erase(AxlString *b, size_t pos, size_t len)
Remove len bytes starting at pos.
If pos >= current length, no-op. If pos + len exceeds the length, erases to end.
- Parameters:
b – string builder
pos – byte offset to start erasing
len – number of bytes to erase
- Returns:
0 on success, -1 if b is NULL.
-
int axl_string_truncate(AxlString *b, size_t len)
Truncate the string to len bytes.
If len >= current length, no-op (does not grow).
- Parameters:
b – string builder
len – new length
- Returns:
0 on success, -1 if b is NULL.
-
int axl_string_overwrite(AxlString *b, size_t pos, const char *s)
Overwrite content at pos with s.
If pos + strlen(s) exceeds the current length, the string is grown to accommodate.
- Parameters:
b – string builder
pos – byte offset to start overwriting
s – NUL-terminated replacement string
- 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.