Sun, 09 Feb 2025 22:00:17 +0100
basic structure for printf documentation
relates to #451
docs/Writerside/topics/printf.h.md | file | annotate | diff | comparison | revisions |
--- 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> +