docs/Writerside/topics/printf.h.md

# Formatting

In the `printf.h` header you can find various useful `printf()`-like functions that can write the formatted output
directly to an arbitrary stream or [buffer](buffer.h.md), or to memory allocated by an [allocator](allocator.h.md).

With the help of these convenience functions, you do not need the libc `snprintf` to print your string to a temporary buffer anymore,
plus you do not need to worry about too small buffer sizes, because the functions will automatically allocate enough memory to contain the entire formatted string.

## Print to Streams and Buffers

```C
#include <cx/printf.h>

int cx_fprintf(void *stream, cx_write_func wfc,
               const char *fmt, ...);

int cx_vfprintf(void *stream, cx_write_func wfc,
                const char *fmt, va_list ap);

int cx_bprintf(CxBuffer *buf, const char *fmt, ...);
```

> TODO: document
{style="warning"}

The `cx_vfprintf()` function is equivalent to `cx_fprintf()`,
except that instead of being called with a variable number of arguments,
they are called with an argument list as defined by `<stdarg.h>`.

## Print to Freshly Allocated Memory

```C
#include <cx/printf.h>

cxmutstr cx_asprintf(const char *fmt, ...);

cxmutstr cx_asprintf_a(const CxAllocator *allocator,
                       const char *fmt, ...);

cxmutstr cx_vasprintf(const char *fmt, va_list ap);

cxmutstr cx_vasprintf_a(const CxAllocator *allocator,
                        const char *fmt, va_list ap);
```

> TODO: document
{style="warning"}

The `cx_vasprintf()` and `cx_vasprintf_a()` functions are equivalent to `cx_asprintf()` and `cx_asprintf_a()`,
except that instead of being called with a variable number of arguments,
they are called with an argument list as defined by `<stdarg.h>`.

## Print to Existing Memory

```C
#include <cx/printf.h>

cx_sprintf
cx_sprintf_a
cx_sprintf_s
cx_sprintf_sa
cx_vsprintf
cx_vsprintf_a
cx_vsprintf_s
cx_vsprintf_sa
```

> TODO: document
{style="warning"}

The `cx_vsprintf()`, `cx_vsprintf_a()`, `cx_vsprintf_s()`, and `cx_vsprintf_sa()` functions are equivalent
to `cx_sprintf()`, `cx_sprintf_a()`, `cx_sprintf_s()`, and `cx_sprintf_sa()`,
except that instead of being called with a variable number of arguments,
they are called with an argument list as defined by `<stdarg.h>`.

## Small Buffer Optimization

All functions that allocate internal temporary memory use small buffer optimization to avoid a heap allocation
if the expected string length is smaller than `cx_printf_sbo_size`.
This size cannot be changed at runtime, but modified by defining the `CX_PRINTF_SBO_SIZE` macro when [building](install.md#small-buffer-optimizations) the library.

<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/printf_8h.html">printf.h</a>
</category>
</seealso>