Mercurial > hg > dav / file comparison

comparison: ucx/cx/printf.h

ucx/cx/printf.h

branch
dav-2
changeset 889
42cdbf9bbd49
parent 886
da79af4baec8
equal deleted inserted replaced
887:26541c37b619 889:42cdbf9bbd49
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE. 26 * POSSIBILITY OF SUCH DAMAGE.
27 */ 27 */
28 /** 28 /**
29 * @file printf.h 29 * @file printf.h
30 * @brief Wrapper for write functions with a printf-like interface. 30 * @brief Wrapper for write-functions with a printf-like interface.
31 * @author Mike Becker 31 * @author Mike Becker
32 * @author Olaf Wintermann 32 * @author Olaf Wintermann
33 * @copyright 2-Clause BSD License 33 * @copyright 2-Clause BSD License
34 */ 34 */
35 35
54 54
55 55
56 /** 56 /**
57 * The maximum string length that fits into stack memory. 57 * The maximum string length that fits into stack memory.
58 */ 58 */
59 cx_attr_export 59 CX_EXPORT extern const unsigned cx_printf_sbo_size;
60 extern const unsigned cx_printf_sbo_size;
61 60
62 /** 61 /**
63 * A @c fprintf like function which writes the output to a stream by 62 * A @c fprintf like function which writes the output to a stream by
64 * using a write_func. 63 * using a write_func.
65 * 64 *
67 * @param wfc the write function 66 * @param wfc the write function
68 * @param fmt format string 67 * @param fmt format string
69 * @param ... additional arguments 68 * @param ... additional arguments
70 * @return the total number of bytes written or an error code from stdlib printf implementation 69 * @return the total number of bytes written or an error code from stdlib printf implementation
71 */ 70 */
72 cx_attr_nonnull_arg(1, 2, 3) 71 cx_attr_nonnull_arg(1, 2, 3) cx_attr_printf(3, 4) cx_attr_cstr_arg(3)
73 cx_attr_printf(3, 4) 72 CX_EXPORT int cx_fprintf(void *stream, cx_write_func wfc, const char *fmt, ...);
74 cx_attr_cstr_arg(3)
75 cx_attr_export
76 int cx_fprintf(
77 void *stream,
78 cx_write_func wfc,
79 const char *fmt,
80 ...
81 );
82 73
83 /** 74 /**
84 * A @c vfprintf like function which writes the output to a stream by 75 * A @c vfprintf like function which writes the output to a stream by
85 * using a write_func. 76 * using a write_func.
86 * 77 *
89 * @param fmt format string 80 * @param fmt format string
90 * @param ap argument list 81 * @param ap argument list
91 * @return the total number of bytes written or an error code from stdlib printf implementation 82 * @return the total number of bytes written or an error code from stdlib printf implementation
92 * @see cx_fprintf() 83 * @see cx_fprintf()
93 */ 84 */
94 cx_attr_nonnull 85 cx_attr_nonnull cx_attr_cstr_arg(3)
95 cx_attr_cstr_arg(3) 86 CX_EXPORT int cx_vfprintf(void *stream, cx_write_func wfc, const char *fmt, va_list ap);
96 cx_attr_export 87
97 int cx_vfprintf( 88 /**
98 void *stream, 89 * An @c asprintf like function which allocates space for a string
99 cx_write_func wfc,
100 const char *fmt,
101 va_list ap
102 );
103
104 /**
105 * A @c asprintf like function which allocates space for a string
106 * the result is written to. 90 * the result is written to.
107 * 91 *
108 * @note The resulting string is guaranteed to be zero-terminated, 92 * @note The resulting string is guaranteed to be zero-terminated,
109 * unless there was an error, in which case the string's pointer 93 * unless there was an error, in which case the string's pointer
110 * will be @c NULL. 94 * will be @c NULL.
113 * @param fmt format string 97 * @param fmt format string
114 * @param ... additional arguments 98 * @param ... additional arguments
115 * @return the formatted string 99 * @return the formatted string
116 * @see cx_strfree_a() 100 * @see cx_strfree_a()
117 */ 101 */
118 cx_attr_nonnull_arg(1, 2) 102 cx_attr_nonnull_arg(1, 2) cx_attr_printf(2, 3) cx_attr_cstr_arg(2)
119 cx_attr_printf(2, 3) 103 CX_EXPORT cxmutstr cx_asprintf_a(const CxAllocator *allocator, const char *fmt, ...);
120 cx_attr_cstr_arg(2) 104
121 cx_attr_export 105 /**
122 cxmutstr cx_asprintf_a( 106 * An @c asprintf like function which allocates space for a string
123 const CxAllocator *allocator,
124 const char *fmt,
125 ...
126 );
127
128 /**
129 * A @c asprintf like function which allocates space for a string
130 * the result is written to. 107 * the result is written to.
131 * 108 *
132 * @note The resulting string is guaranteed to be zero-terminated, 109 * @note The resulting string is guaranteed to be zero-terminated,
133 * unless there was an error, in which case the string's pointer 110 * unless there was an error, in which case the string's pointer
134 * will be @c NULL. 111 * will be @c NULL.
136 * @param fmt (@c char*) format string 113 * @param fmt (@c char*) format string
137 * @param ... additional arguments 114 * @param ... additional arguments
138 * @return (@c cxmutstr) the formatted string 115 * @return (@c cxmutstr) the formatted string
139 * @see cx_strfree() 116 * @see cx_strfree()
140 */ 117 */
141 #define cx_asprintf(fmt, ...) \ 118 #define cx_asprintf(fmt, ...) cx_asprintf_a(cxDefaultAllocator, fmt, __VA_ARGS__)
142 cx_asprintf_a(cxDefaultAllocator, fmt, __VA_ARGS__)
143 119
144 /** 120 /**
145 * A @c vasprintf like function which allocates space for a string 121 * A @c vasprintf like function which allocates space for a string
146 * the result is written to. 122 * the result is written to.
147 * 123 *
153 * @param fmt format string 129 * @param fmt format string
154 * @param ap argument list 130 * @param ap argument list
155 * @return the formatted string 131 * @return the formatted string
156 * @see cx_asprintf_a() 132 * @see cx_asprintf_a()
157 */ 133 */
158 cx_attr_nonnull 134 cx_attr_nonnull cx_attr_cstr_arg(2)
159 cx_attr_cstr_arg(2) 135 CX_EXPORT cxmutstr cx_vasprintf_a(const CxAllocator *allocator, const char *fmt, va_list ap);
160 cx_attr_export
161 cxmutstr cx_vasprintf_a(
162 const CxAllocator *allocator,
163 const char *fmt,
164 va_list ap
165 );
166 136
167 /** 137 /**
168 * A @c vasprintf like function which allocates space for a string 138 * A @c vasprintf like function which allocates space for a string
169 * the result is written to. 139 * the result is written to.
170 * 140 *
171 * @note The resulting string is guaranteed to be zero-terminated, 141 * @note The resulting string is guaranteed to be zero-terminated,
172 * unless there was in error, in which case the string's pointer 142 * unless there was an error, in which case the string's pointer
173 * will be @c NULL. 143 * will be @c NULL.
174 * 144 *
175 * @param fmt (@c char*) format string 145 * @param fmt (@c char*) format string
176 * @param ap (@c va_list) argument list 146 * @param ap (@c va_list) argument list
177 * @return (@c cxmutstr) the formatted string 147 * @return (@c cxmutstr) the formatted string
187 * @param ... additional arguments 157 * @param ... additional arguments
188 * @return (@c int) the total number of bytes written or an error code from stdlib printf implementation 158 * @return (@c int) the total number of bytes written or an error code from stdlib printf implementation
189 * @see cx_fprintf() 159 * @see cx_fprintf()
190 * @see cxBufferWrite() 160 * @see cxBufferWrite()
191 */ 161 */
192 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((void*)buffer, \ 162 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((void*)buffer, cxBufferWriteFunc, fmt, __VA_ARGS__)
193 cxBufferWriteFunc, fmt, __VA_ARGS__)
194 163
195 164
196 /** 165 /**
197 * An @c sprintf like function which reallocates the string when the buffer is not large enough. 166 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
198 * 167 *
202 * 171 *
203 * @param str (@c char**) a pointer to the string buffer 172 * @param str (@c char**) a pointer to the string buffer
204 * @param len (@c size_t*) a pointer to the length of the buffer 173 * @param len (@c size_t*) a pointer to the length of the buffer
205 * @param fmt (@c char*) the format string 174 * @param fmt (@c char*) the format string
206 * @param ... additional arguments 175 * @param ... additional arguments
207 * @return (@c int) the length of produced string or an error code from stdlib printf implementation 176 * @return (@c int) the length of the produced string or an error code from stdlib printf implementation
208 */ 177 */
209 #define cx_sprintf(str, len, fmt, ...) cx_sprintf_a(cxDefaultAllocator, str, len, fmt, __VA_ARGS__) 178 #define cx_sprintf(str, len, fmt, ...) cx_sprintf_a(cxDefaultAllocator, str, len, fmt, __VA_ARGS__)
210 179
211 /** 180 /**
212 * An @c sprintf like function which reallocates the string when the buffer is not large enough. 181 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
220 * @param alloc the allocator to use 189 * @param alloc the allocator to use
221 * @param str a pointer to the string buffer 190 * @param str a pointer to the string buffer
222 * @param len a pointer to the length of the buffer 191 * @param len a pointer to the length of the buffer
223 * @param fmt the format string 192 * @param fmt the format string
224 * @param ... additional arguments 193 * @param ... additional arguments
225 * @return the length of produced string or an error code from stdlib printf implementation 194 * @return the length of the produced string or an error code from stdlib printf implementation
226 */ 195 */
227 cx_attr_nonnull_arg(1, 2, 3, 4) 196 cx_attr_nonnull_arg(1, 2, 3, 4) cx_attr_printf(4, 5) cx_attr_cstr_arg(4)
228 cx_attr_printf(4, 5) 197 CX_EXPORT int cx_sprintf_a(const CxAllocator *alloc, char **str, size_t *len, const char *fmt, ...);
229 cx_attr_cstr_arg(4)
230 cx_attr_export
231 int cx_sprintf_a(
232 const CxAllocator *alloc,
233 char **str,
234 size_t *len,
235 const char *fmt,
236 ...
237 );
238 198
239 199
240 /** 200 /**
241 * An @c sprintf like function which reallocates the string when the buffer is not large enough. 201 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
242 * 202 *
246 * 206 *
247 * @param str (@c char**) a pointer to the string buffer 207 * @param str (@c char**) a pointer to the string buffer
248 * @param len (@c size_t*) a pointer to the length of the buffer 208 * @param len (@c size_t*) a pointer to the length of the buffer
249 * @param fmt (@c char*) the format string 209 * @param fmt (@c char*) the format string
250 * @param ap (@c va_list) argument list 210 * @param ap (@c va_list) argument list
251 * @return (@c int) the length of produced string or an error code from stdlib printf implementation 211 * @return (@c int) the length of the produced string or an error code from stdlib printf implementation
252 */ 212 */
253 #define cx_vsprintf(str, len, fmt, ap) cx_vsprintf_a(cxDefaultAllocator, str, len, fmt, ap) 213 #define cx_vsprintf(str, len, fmt, ap) cx_vsprintf_a(cxDefaultAllocator, str, len, fmt, ap)
254 214
255 /** 215 /**
256 * An @c sprintf like function which reallocates the string when the buffer is not large enough. 216 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
264 * @param alloc the allocator to use 224 * @param alloc the allocator to use
265 * @param str a pointer to the string buffer 225 * @param str a pointer to the string buffer
266 * @param len a pointer to the length of the buffer 226 * @param len a pointer to the length of the buffer
267 * @param fmt the format string 227 * @param fmt the format string
268 * @param ap argument list 228 * @param ap argument list
269 * @return the length of produced string or an error code from stdlib printf implementation 229 * @return the length of the produced string or an error code from stdlib printf implementation
270 */ 230 */
271 cx_attr_nonnull 231 cx_attr_nonnull cx_attr_cstr_arg(4) cx_attr_access_rw(2) cx_attr_access_rw(3)
272 cx_attr_cstr_arg(4) 232 CX_EXPORT int cx_vsprintf_a(const CxAllocator *alloc, char **str, size_t *len, const char *fmt, va_list ap);
273 cx_attr_access_rw(2)
274 cx_attr_access_rw(3)
275 cx_attr_export
276 int cx_vsprintf_a(
277 const CxAllocator *alloc,
278 char **str,
279 size_t *len,
280 const char *fmt,
281 va_list ap
282 );
283 233
284 234
285 /** 235 /**
286 * An @c sprintf like function which allocates a new string when the buffer is not large enough. 236 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
287 * 237 *
298 * @param buf (@c char*) a pointer to the buffer 248 * @param buf (@c char*) a pointer to the buffer
299 * @param len (@c size_t*) a pointer to the length of the buffer 249 * @param len (@c size_t*) a pointer to the length of the buffer
300 * @param str (@c char**) a pointer where the location of the result shall be stored 250 * @param str (@c char**) a pointer where the location of the result shall be stored
301 * @param fmt (@c char*) the format string 251 * @param fmt (@c char*) the format string
302 * @param ... additional arguments 252 * @param ... additional arguments
303 * @return (@c int) the length of produced string or an error code from stdlib printf implementation 253 * @return (@c int) the length of the produced string or an error code from stdlib printf implementation
304 */ 254 */
305 #define cx_sprintf_s(buf, len, str, fmt, ...) cx_sprintf_sa(cxDefaultAllocator, buf, len, str, fmt, __VA_ARGS__) 255 #define cx_sprintf_s(buf, len, str, fmt, ...) cx_sprintf_sa(cxDefaultAllocator, buf, len, str, fmt, __VA_ARGS__)
306 256
307 /** 257 /**
308 * An @c sprintf like function which allocates a new string when the buffer is not large enough. 258 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
321 * @param buf a pointer to the buffer 271 * @param buf a pointer to the buffer
322 * @param len a pointer to the length of the buffer 272 * @param len a pointer to the length of the buffer
323 * @param str a pointer where the location of the result shall be stored 273 * @param str a pointer where the location of the result shall be stored
324 * @param fmt the format string 274 * @param fmt the format string
325 * @param ... additional arguments 275 * @param ... additional arguments
326 * @return the length of produced string or an error code from stdlib printf implementation 276 * @return the length of the produced string or an error code from stdlib printf implementation
327 */ 277 */
328 cx_attr_nonnull_arg(1, 2, 4, 5) 278 cx_attr_nonnull_arg(1, 2, 4, 5) cx_attr_printf(5, 6) cx_attr_cstr_arg(5)
329 cx_attr_printf(5, 6) 279 cx_attr_access_rw(2) cx_attr_access_rw(3) cx_attr_access_rw(4)
330 cx_attr_cstr_arg(5) 280 CX_EXPORT int cx_sprintf_sa(const CxAllocator *alloc, char *buf, size_t *len, char **str, const char *fmt, ...);
331 cx_attr_access_rw(2)
332 cx_attr_access_rw(3)
333 cx_attr_access_rw(4)
334 cx_attr_export
335 int cx_sprintf_sa(
336 const CxAllocator *alloc,
337 char *buf,
338 size_t *len,
339 char **str,
340 const char *fmt,
341 ...
342 );
343 281
344 /** 282 /**
345 * An @c sprintf like function which allocates a new string when the buffer is not large enough. 283 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
346 * 284 *
347 * The size of the buffer will be updated in @p len when necessary. 285 * The size of the buffer will be updated in @p len when necessary.
357 * @param buf (@c char*) a pointer to the buffer 295 * @param buf (@c char*) a pointer to the buffer
358 * @param len (@c size_t*) a pointer to the length of the buffer 296 * @param len (@c size_t*) a pointer to the length of the buffer
359 * @param str (@c char**) a pointer where the location of the result shall be stored 297 * @param str (@c char**) a pointer where the location of the result shall be stored
360 * @param fmt (@c char*) the format string 298 * @param fmt (@c char*) the format string
361 * @param ap (@c va_list) argument list 299 * @param ap (@c va_list) argument list
362 * @return (@c int) the length of produced string or an error code from stdlib printf implementation 300 * @return (@c int) the length of the produced string or an error code from stdlib printf implementation
363 */ 301 */
364 #define cx_vsprintf_s(buf, len, str, fmt, ap) cx_vsprintf_sa(cxDefaultAllocator, buf, len, str, fmt, ap) 302 #define cx_vsprintf_s(buf, len, str, fmt, ap) cx_vsprintf_sa(cxDefaultAllocator, buf, len, str, fmt, ap)
365 303
366 /** 304 /**
367 * An @c sprintf like function which allocates a new string when the buffer is not large enough. 305 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
380 * @param buf a pointer to the buffer 318 * @param buf a pointer to the buffer
381 * @param len a pointer to the length of the buffer 319 * @param len a pointer to the length of the buffer
382 * @param str a pointer where the location of the result shall be stored 320 * @param str a pointer where the location of the result shall be stored
383 * @param fmt the format string 321 * @param fmt the format string
384 * @param ap argument list 322 * @param ap argument list
385 * @return the length of produced string or an error code from stdlib printf implementation 323 * @return the length of the produced string or an error code from stdlib printf implementation
386 */ 324 */
387 cx_attr_nonnull 325 cx_attr_nonnull cx_attr_cstr_arg(5)
388 cx_attr_cstr_arg(5) 326 CX_EXPORT int cx_vsprintf_sa(const CxAllocator *alloc, char *buf, size_t *len, char **str, const char *fmt, va_list ap);
389 cx_attr_export
390 int cx_vsprintf_sa(
391 const CxAllocator *alloc,
392 char *buf,
393 size_t *len,
394 char **str,
395 const char *fmt,
396 va_list ap
397 );
398 327
399 328
400 #ifdef __cplusplus 329 #ifdef __cplusplus
401 } // extern "C" 330 } // extern "C"
402 #endif 331 #endif

Mercurial Repository: dav

mercurial