comparison: docs/Writerside/topics/printf.h.md
docs/Writerside/topics/printf.h.md
- branch
- docs/3.1
- changeset 1172
- 1a6aa0301226
- parent 1146
- 151c057faf7c
equal
deleted
inserted
replaced
| 1171:155bc3b0dcb3 | 1172:1a6aa0301226 |
|---|---|
| 1 # Formatting | 1 # Formatting |
| 2 | 2 |
| 3 <warning> | 3 In the `printf.h` header you can find various useful `printf()`-like functions that can write the formatted output |
| 4 Outdated - Rewrite! | 4 directly to an arbitrary stream or [buffer](buffer.h.md), or to memory allocated by an [allocator](allocator.h.md). |
| 5 </warning> | |
| 6 | 5 |
| 7 In this utility header you can find `printf()`-like functions that can write the formatted output to an arbitrary | 6 With the help of these convenience functions, you do not need the libc `snprintf` to print your string to a temporary buffer anymore, |
| 8 stream (or UCX buffer, resp.), or to memory allocated by an allocator within a single function call. | 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. |
| 9 With the help of these convenience functions, you do not need to `snprintf` your string to a temporary buffer anymore, | |
| 10 plus you do not need to worry about too small buffer sizes, because the functions will automatically allocate enough | |
| 11 memory to contain the entire formatted string. | |
| 12 | 8 |
| 13 ## Undocumented Symbols (TODO) | 9 ## Print to Streams and Buffers |
| 14 ### cx_asprintf_a | 10 |
| 15 ### cx_fprintf | 11 ```C |
| 16 ### cx_printf_sbo_size | 12 #include <cx/printf.h> |
| 17 ### cx_sprintf_a | 13 |
| 18 ### cx_sprintf_sa | 14 int cx_fprintf(void *stream, cx_write_func wfc, |
| 19 ### cx_vasprintf_a | 15 const char *fmt, ...); |
| 20 ### cx_vfprintf | 16 |
| 21 ### cx_vsprintf_a | 17 int cx_vfprintf(void *stream, cx_write_func wfc, |
| 22 ### cx_vsprintf_sa | 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 |
