comparison: docs/Writerside/topics/printf.h.md
docs/Writerside/topics/printf.h.md
- changeset 1188
- b0300de92b72
- parent 1172
- 1a6aa0301226
equal
deleted
inserted
replaced
| 1187:0f70bb04f7ba | 1188:b0300de92b72 |
|---|---|
| 1 # Formatting | |
| 2 | |
| 3 In the `printf.h` header you can find various useful `printf()`-like functions that can write the formatted output | |
| 4 directly to an arbitrary stream or [buffer](buffer.h.md), or to memory allocated by an [allocator](allocator.h.md). | |
| 5 | |
| 6 With the help of these convenience functions, you do not need the libc `snprintf` to print your string to a temporary buffer anymore, | |
| 7 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. | |
| 8 | |
| 9 ## Print to Streams and Buffers | |
| 10 | |
| 11 ```C | |
| 12 #include <cx/printf.h> | |
| 13 | |
| 14 int cx_fprintf(void *stream, cx_write_func wfc, | |
| 15 const char *fmt, ...); | |
| 16 | |
| 17 int cx_vfprintf(void *stream, cx_write_func wfc, | |
| 18 const char *fmt, va_list ap); | |
| 19 | |
| 20 int cx_bprintf(CxBuffer *buf, const char *fmt, ...); | |
| 21 ``` | |
| 22 | |
| 23 > TODO: document | |
| 24 {style="warning"} | |
| 25 | |
| 26 The `cx_vfprintf()` function is equivalent to `cx_fprintf()`, | |
| 27 except that instead of being called with a variable number of arguments, | |
| 28 they are called with an argument list as defined by `<stdarg.h>`. | |
| 29 | |
| 30 ## Print to Freshly Allocated Memory | |
| 31 | |
| 32 ```C | |
| 33 #include <cx/printf.h> | |
| 34 | |
| 35 cxmutstr cx_asprintf(const char *fmt, ...); | |
| 36 | |
| 37 cxmutstr cx_asprintf_a(const CxAllocator *allocator, | |
| 38 const char *fmt, ...); | |
| 39 | |
| 40 cxmutstr cx_vasprintf(const char *fmt, va_list ap); | |
| 41 | |
| 42 cxmutstr cx_vasprintf_a(const CxAllocator *allocator, | |
| 43 const char *fmt, va_list ap); | |
| 44 ``` | |
| 45 | |
| 46 > TODO: document | |
| 47 {style="warning"} | |
| 48 | |
| 49 The `cx_vasprintf()` and `cx_vasprintf_a()` functions are equivalent to `cx_asprintf()` and `cx_asprintf_a()`, | |
| 50 except that instead of being called with a variable number of arguments, | |
| 51 they are called with an argument list as defined by `<stdarg.h>`. | |
| 52 | |
| 53 ## Print to Existing Memory | |
| 54 | |
| 55 ```C | |
| 56 #include <cx/printf.h> | |
| 57 | |
| 58 cx_sprintf | |
| 59 cx_sprintf_a | |
| 60 cx_sprintf_s | |
| 61 cx_sprintf_sa | |
| 62 cx_vsprintf | |
| 63 cx_vsprintf_a | |
| 64 cx_vsprintf_s | |
| 65 cx_vsprintf_sa | |
| 66 ``` | |
| 67 | |
| 68 > TODO: document | |
| 69 {style="warning"} | |
| 70 | |
| 71 The `cx_vsprintf()`, `cx_vsprintf_a()`, `cx_vsprintf_s()`, and `cx_vsprintf_sa()` functions are equivalent | |
| 72 to `cx_sprintf()`, `cx_sprintf_a()`, `cx_sprintf_s()`, and `cx_sprintf_sa()`, | |
| 73 except that instead of being called with a variable number of arguments, | |
| 74 they are called with an argument list as defined by `<stdarg.h>`. | |
| 75 | |
| 76 ## Small Buffer Optimization | |
| 77 | |
| 78 All functions that allocate internal temporary memory use small buffer optimization to avoid a heap allocation | |
| 79 if the expected string length is smaller than `cx_printf_sbo_size`. | |
| 80 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. | |
| 81 | |
| 82 <seealso> | |
| 83 <category ref="apidoc"> | |
| 84 <a href="https://ucx.sourceforge.io/api/printf_8h.html">printf.h</a> | |
| 85 </category> | |
| 86 </seealso> | |
| 87 |
