# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1739134817 -3600
# Node ID 1a6aa030122654f1ca1b8fbe17efb02b1782f7c6
# Parent  155bc3b0dcb37924717d279ee49a1b03e63be2f6
basic structure for printf documentation

relates to #451

diff -r 155bc3b0dcb3 -r 1a6aa0301226 docs/Writerside/topics/printf.h.md
--- a/docs/Writerside/topics/printf.h.md	Sat Feb 08 20:38:05 2025 +0100
+++ b/docs/Writerside/topics/printf.h.md	Sun Feb 09 22:00:17 2025 +0100
@@ -1,22 +1,87 @@
 # Formatting
 
-<warning>
-Outdated - Rewrite!
-</warning>
+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, ...);
+```
 
-In this utility header you can find `printf()`-like functions that can write the formatted output to an arbitrary
-stream (or UCX buffer, resp.), or to memory allocated by an allocator within a single function call.
-With the help of these convenience functions, you do not need to `snprintf` 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.
+> 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);
+```
 
-## Undocumented Symbols (TODO)
-### cx_asprintf_a
-### cx_fprintf
-### cx_printf_sbo_size
-### cx_sprintf_a
-### cx_sprintf_sa
-### cx_vasprintf_a
-### cx_vfprintf
-### cx_vsprintf_a
-### cx_vsprintf_sa
+> 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>
+