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.

.. code-block:: c

   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:

.. code-block:: c

   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
-------------

.. doxygenfile:: axl-string.h