Mercurial > hg > dbutils / file comparison

comparison: ucx/cx/printf.h

ucx/cx/printf.h

changeset 16
04c9f8d8f03b
parent 11
0aa8cbd7912e
child 21
5ea41679e15d
equal deleted inserted replaced
15:862ab606ee06 16:04c9f8d8f03b
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
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
36 #ifndef UCX_PRINTF_H 36 #ifndef UCX_PRINTF_H
37 #define UCX_PRINTF_H 37 #define UCX_PRINTF_H
38 38
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 extern const unsigned cx_printf_sbo_size; 60 extern const unsigned cx_printf_sbo_size;
60 61
61 /** 62 /**
62 * A \c fprintf like function which writes the output to a stream by 63 * A @c fprintf like function which writes the output to a stream by
63 * using a write_func. 64 * using a write_func.
64 * 65 *
65 * @param stream the stream the data is written to 66 * @param stream the stream the data is written to
66 * @param wfc the write function 67 * @param wfc the write function
67 * @param fmt format string 68 * @param fmt format string
68 * @param ... additional arguments 69 * @param ... additional arguments
69 * @return the total number of bytes written 70 * @return the total number of bytes written or an error code from stdlib printf implementation
70 */ 71 */
71 cx_attr_nonnull_arg(1, 2, 3) 72 cx_attr_nonnull_arg(1, 2, 3)
72 cx_attr_printf(3, 4) 73 cx_attr_printf(3, 4)
73 cx_attr_cstr_arg(3) 74 cx_attr_cstr_arg(3)
75 cx_attr_export
74 int cx_fprintf( 76 int cx_fprintf(
75 void *stream, 77 void *stream,
76 cx_write_func wfc, 78 cx_write_func wfc,
77 const char *fmt, 79 const char *fmt,
78 ... 80 ...
79 ); 81 );
80 82
81 /** 83 /**
82 * A \c vfprintf like function which writes the output to a stream by 84 * A @c vfprintf like function which writes the output to a stream by
83 * using a write_func. 85 * using a write_func.
84 * 86 *
85 * @param stream the stream the data is written to 87 * @param stream the stream the data is written to
86 * @param wfc the write function 88 * @param wfc the write function
87 * @param fmt format string 89 * @param fmt format string
88 * @param ap argument list 90 * @param ap argument list
89 * @return the total number of bytes written 91 * @return the total number of bytes written or an error code from stdlib printf implementation
90 * @see cx_fprintf() 92 * @see cx_fprintf()
91 */ 93 */
92 cx_attr_nonnull 94 cx_attr_nonnull
93 cx_attr_cstr_arg(3) 95 cx_attr_cstr_arg(3)
96 cx_attr_export
94 int cx_vfprintf( 97 int cx_vfprintf(
95 void *stream, 98 void *stream,
96 cx_write_func wfc, 99 cx_write_func wfc,
97 const char *fmt, 100 const char *fmt,
98 va_list ap 101 va_list ap
99 ); 102 );
100 103
101 /** 104 /**
102 * A \c asprintf like function which allocates space for a string 105 * A @c asprintf like function which allocates space for a string
103 * the result is written to. 106 * the result is written to.
104 * 107 *
105 * \note The resulting string is guaranteed to be zero-terminated. 108 * @note The resulting string is guaranteed to be zero-terminated,
109 * unless there was an error, in which case the string's pointer
110 * will be @c NULL.
106 * 111 *
107 * @param allocator the CxAllocator used for allocating the string 112 * @param allocator the CxAllocator used for allocating the string
108 * @param fmt format string 113 * @param fmt format string
109 * @param ... additional arguments 114 * @param ... additional arguments
110 * @return the formatted string 115 * @return the formatted string
111 * @see cx_strfree_a() 116 * @see cx_strfree_a()
112 */ 117 */
113 cx_attr_nonnull_arg(1, 2) 118 cx_attr_nonnull_arg(1, 2)
114 cx_attr_printf(2, 3) 119 cx_attr_printf(2, 3)
115 cx_attr_cstr_arg(2) 120 cx_attr_cstr_arg(2)
121 cx_attr_export
116 cxmutstr cx_asprintf_a( 122 cxmutstr cx_asprintf_a(
117 const CxAllocator *allocator, 123 const CxAllocator *allocator,
118 const char *fmt, 124 const char *fmt,
119 ... 125 ...
120 ); 126 );
121 127
122 /** 128 /**
123 * A \c asprintf like function which allocates space for a string 129 * A @c asprintf like function which allocates space for a string
124 * the result is written to. 130 * the result is written to.
125 * 131 *
126 * \note The resulting string is guaranteed to be zero-terminated. 132 * @note The resulting string is guaranteed to be zero-terminated,
127 * 133 * unless there was an error, in which case the string's pointer
128 * @param fmt format string 134 * will be @c NULL.
129 * @param ... additional arguments 135 *
130 * @return the formatted string 136 * @param fmt (@c char*) format string
137 * @param ... additional arguments
138 * @return (@c cxmutstr) the formatted string
131 * @see cx_strfree() 139 * @see cx_strfree()
132 */ 140 */
133 #define cx_asprintf(fmt, ...) \ 141 #define cx_asprintf(fmt, ...) \
134 cx_asprintf_a(cxDefaultAllocator, fmt, __VA_ARGS__) 142 cx_asprintf_a(cxDefaultAllocator, fmt, __VA_ARGS__)
135 143
136 /** 144 /**
137 * A \c vasprintf like function which allocates space for a string 145 * A @c vasprintf like function which allocates space for a string
138 * the result is written to. 146 * the result is written to.
139 * 147 *
140 * \note The resulting string is guaranteed to be zero-terminated. 148 * @note The resulting string is guaranteed to be zero-terminated,
149 * unless there was an error, in which case the string's pointer
150 * will be @c NULL.
141 * 151 *
142 * @param allocator the CxAllocator used for allocating the string 152 * @param allocator the CxAllocator used for allocating the string
143 * @param fmt format string 153 * @param fmt format string
144 * @param ap argument list 154 * @param ap argument list
145 * @return the formatted string 155 * @return the formatted string
146 * @see cx_asprintf_a() 156 * @see cx_asprintf_a()
147 */ 157 */
148 cx_attr_nonnull 158 cx_attr_nonnull
149 cx_attr_cstr_arg(2) 159 cx_attr_cstr_arg(2)
160 cx_attr_export
150 cxmutstr cx_vasprintf_a( 161 cxmutstr cx_vasprintf_a(
151 const CxAllocator *allocator, 162 const CxAllocator *allocator,
152 const char *fmt, 163 const char *fmt,
153 va_list ap 164 va_list ap
154 ); 165 );
155 166
156 /** 167 /**
157 * A \c vasprintf like function which allocates space for a string 168 * A @c vasprintf like function which allocates space for a string
158 * the result is written to. 169 * the result is written to.
159 * 170 *
160 * \note The resulting string is guaranteed to be zero-terminated. 171 * @note The resulting string is guaranteed to be zero-terminated,
161 * 172 * unless there was in error, in which case the string's pointer
162 * @param fmt format string 173 * will be @c NULL.
163 * @param ap argument list 174 *
164 * @return the formatted string 175 * @param fmt (@c char*) format string
176 * @param ap (@c va_list) argument list
177 * @return (@c cxmutstr) the formatted string
165 * @see cx_asprintf() 178 * @see cx_asprintf()
166 */ 179 */
167 #define cx_vasprintf(fmt, ap) cx_vasprintf_a(cxDefaultAllocator, fmt, ap) 180 #define cx_vasprintf(fmt, ap) cx_vasprintf_a(cxDefaultAllocator, fmt, ap)
168 181
169 /** 182 /**
170 * A \c printf like function which writes the output to a CxBuffer. 183 * A @c printf like function which writes the output to a CxBuffer.
171 * 184 *
172 * @param buffer a pointer to the buffer the data is written to 185 * @param buffer (@c CxBuffer*) a pointer to the buffer the data is written to
173 * @param fmt the format string 186 * @param fmt (@c char*) the format string
174 * @param ... additional arguments 187 * @param ... additional arguments
175 * @return the total number of bytes written 188 * @return (@c int) the total number of bytes written or an error code from stdlib printf implementation
176 * @see ucx_fprintf() 189 * @see cx_fprintf()
177 */ 190 * @see cxBufferWrite()
178 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((CxBuffer*)buffer, \ 191 */
179 (cx_write_func) cxBufferWrite, fmt, __VA_ARGS__) 192 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((void*)buffer, \
180 193 cxBufferWriteFunc, fmt, __VA_ARGS__)
181 194
182 /** 195
183 * An \c sprintf like function which reallocates the string when the buffer is not large enough. 196 /**
184 * 197 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
185 * The size of the buffer will be updated in \p len when necessary. 198 *
186 * 199 * The size of the buffer will be updated in @p len when necessary.
187 * \note The resulting string is guaranteed to be zero-terminated. 200 *
188 * 201 * @note The resulting string, if successful, is guaranteed to be zero-terminated.
189 * @param str a pointer to the string buffer 202 *
190 * @param len a pointer to the length of the buffer 203 * @param str (@c char**) a pointer to the string buffer
191 * @param fmt the format string 204 * @param len (@c size_t*) a pointer to the length of the buffer
192 * @param ... additional arguments 205 * @param fmt (@c char*) the format string
193 * @return the length of produced string 206 * @param ... additional arguments
207 * @return (@c int) the length of produced string or an error code from stdlib printf implementation
194 */ 208 */
195 #define cx_sprintf(str, len, fmt, ...) cx_sprintf_a(cxDefaultAllocator, str, len, fmt, __VA_ARGS__) 209 #define cx_sprintf(str, len, fmt, ...) cx_sprintf_a(cxDefaultAllocator, str, len, fmt, __VA_ARGS__)
196 210
197 /** 211 /**
198 * An \c sprintf like function which reallocates the string when the buffer is not large enough. 212 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
199 * 213 *
200 * The size of the buffer will be updated in \p len when necessary. 214 * The size of the buffer will be updated in @p len when necessary.
201 * 215 *
202 * \note The resulting string is guaranteed to be zero-terminated. 216 * @note The resulting string, if successful, is guaranteed to be zero-terminated.
203 * 217 *
204 * \attention The original buffer MUST have been allocated with the same allocator! 218 * @attention The original buffer MUST have been allocated with the same allocator!
205 * 219 *
206 * @param alloc the allocator to use 220 * @param alloc the allocator to use
207 * @param str a pointer to the string buffer 221 * @param str a pointer to the string buffer
208 * @param len a pointer to the length of the buffer 222 * @param len a pointer to the length of the buffer
209 * @param fmt the format string 223 * @param fmt the format string
210 * @param ... additional arguments 224 * @param ... additional arguments
211 * @return the length of produced string 225 * @return the length of produced string or an error code from stdlib printf implementation
212 */ 226 */
213 cx_attr_nonnull_arg(1, 2, 3, 4) 227 cx_attr_nonnull_arg(1, 2, 3, 4)
214 cx_attr_printf(4, 5) 228 cx_attr_printf(4, 5)
215 cx_attr_cstr_arg(4) 229 cx_attr_cstr_arg(4)
230 cx_attr_export
216 int cx_sprintf_a( 231 int cx_sprintf_a(
217 CxAllocator *alloc, 232 CxAllocator *alloc,
218 char **str, 233 char **str,
219 size_t *len, 234 size_t *len,
220 const char *fmt, 235 const char *fmt,
221 ... 236 ...
222 ); 237 );
223 238
224 239
225 /** 240 /**
226 * An \c sprintf like function which reallocates the string when the buffer is not large enough. 241 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
227 * 242 *
228 * The size of the buffer will be updated in \p len when necessary. 243 * The size of the buffer will be updated in @p len when necessary.
229 * 244 *
230 * \note The resulting string is guaranteed to be zero-terminated. 245 * @note The resulting string, if successful, is guaranteed to be zero-terminated.
231 * 246 *
232 * @param str a pointer to the string buffer 247 * @param str (@c char**) a pointer to the string buffer
233 * @param len a pointer to the length of the buffer 248 * @param len (@c size_t*) a pointer to the length of the buffer
234 * @param fmt the format string 249 * @param fmt (@c char*) the format string
235 * @param ap argument list 250 * @param ap (@c va_list) argument list
236 * @return the length of produced string 251 * @return (@c int) the length of produced string or an error code from stdlib printf implementation
237 */ 252 */
238 #define cx_vsprintf(str, len, fmt, ap) cx_vsprintf_a(cxDefaultAllocator, str, len, fmt, ap) 253 #define cx_vsprintf(str, len, fmt, ap) cx_vsprintf_a(cxDefaultAllocator, str, len, fmt, ap)
239 254
240 /** 255 /**
241 * An \c sprintf like function which reallocates the string when the buffer is not large enough. 256 * An @c sprintf like function which reallocates the string when the buffer is not large enough.
242 * 257 *
243 * The size of the buffer will be updated in \p len when necessary. 258 * The size of the buffer will be updated in @p len when necessary.
244 * 259 *
245 * \note The resulting string is guaranteed to be zero-terminated. 260 * @note The resulting string is guaranteed to be zero-terminated.
246 * 261 *
247 * \attention The original buffer MUST have been allocated with the same allocator! 262 * @attention The original buffer MUST have been allocated with the same allocator!
248 * 263 *
249 * @param alloc the allocator to use 264 * @param alloc the allocator to use
250 * @param str a pointer to the string buffer 265 * @param str a pointer to the string buffer
251 * @param len a pointer to the length of the buffer 266 * @param len a pointer to the length of the buffer
252 * @param fmt the format string 267 * @param fmt the format string
253 * @param ap argument list 268 * @param ap argument list
254 * @return the length of produced string 269 * @return the length of produced string or an error code from stdlib printf implementation
255 */ 270 */
256 cx_attr_nonnull 271 cx_attr_nonnull
257 cx_attr_cstr_arg(4) 272 cx_attr_cstr_arg(4)
273 cx_attr_access_rw(2)
274 cx_attr_access_rw(3)
275 cx_attr_export
258 int cx_vsprintf_a( 276 int cx_vsprintf_a(
259 CxAllocator *alloc, 277 CxAllocator *alloc,
260 char **str, 278 char **str,
261 size_t *len, 279 size_t *len,
262 const char *fmt, 280 const char *fmt,
263 va_list ap 281 va_list ap
264 ); 282 );
265 283
266 284
267 /** 285 /**
268 * An \c sprintf like function which allocates a new string when the buffer is not large enough. 286 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
269 * 287 *
270 * The size of the buffer will be updated in \p len when necessary. 288 * The size of the buffer will be updated in @p len when necessary.
271 * 289 *
272 * The location of the resulting string will \em always be stored to \p str. When the buffer 290 * The location of the resulting string will @em always be stored to @p str. When the buffer
273 * was sufficiently large, \p buf itself will be stored to the location of \p str. 291 * was sufficiently large, @p buf itself will be stored to the location of @p str.
274 * 292 *
275 * \note The resulting string is guaranteed to be zero-terminated. 293 * @note The resulting string, if successful, is guaranteed to be zero-terminated.
276 * 294 *
277 * \remark When a new string needed to be allocated, the contents of \p buf will be 295 * @remark When a new string needed to be allocated, the contents of @p buf will be
278 * poisoned after the call, because this function tries to produce the string in \p buf, first. 296 * poisoned after the call, because this function tries to produce the string in @p buf, first.
279 * 297 *
280 * @param buf a pointer to the buffer 298 * @param buf (@c char*) a pointer to the buffer
281 * @param len a pointer to the length of the buffer 299 * @param len (@c size_t*) a pointer to the length of the buffer
282 * @param str a pointer to the location 300 * @param str (@c char**) a pointer where the location of the result shall be stored
283 * @param fmt the format string 301 * @param fmt (@c char*) the format string
284 * @param ... additional arguments 302 * @param ... additional arguments
285 * @return the length of produced string 303 * @return (@c int) the length of produced string or an error code from stdlib printf implementation
286 */ 304 */
287 #define cx_sprintf_s(buf, len, str, fmt, ...) cx_sprintf_sa(cxDefaultAllocator, buf, len, str, fmt, __VA_ARGS__) 305 #define cx_sprintf_s(buf, len, str, fmt, ...) cx_sprintf_sa(cxDefaultAllocator, buf, len, str, fmt, __VA_ARGS__)
288 306
289 /** 307 /**
290 * An \c sprintf like function which allocates a new string when the buffer is not large enough. 308 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
291 * 309 *
292 * The size of the buffer will be updated in \p len when necessary. 310 * The size of the buffer will be updated in @p len when necessary.
293 * 311 *
294 * The location of the resulting string will \em always be stored to \p str. When the buffer 312 * The location of the resulting string will @em always be stored to @p str. When the buffer
295 * was sufficiently large, \p buf itself will be stored to the location of \p str. 313 * was sufficiently large, @p buf itself will be stored to the location of @p str.
296 * 314 *
297 * \note The resulting string is guaranteed to be zero-terminated. 315 * @note The resulting string, if successful, is guaranteed to be zero-terminated.
298 * 316 *
299 * \remark When a new string needed to be allocated, the contents of \p buf will be 317 * @remark When a new string needed to be allocated, the contents of @p buf will be
300 * poisoned after the call, because this function tries to produce the string in \p buf, first. 318 * poisoned after the call, because this function tries to produce the string in @p buf, first.
301 * 319 *
302 * @param alloc the allocator to use 320 * @param alloc the allocator to use
303 * @param buf a pointer to the buffer 321 * @param buf a pointer to the buffer
304 * @param len a pointer to the length of the buffer 322 * @param len a pointer to the length of the buffer
305 * @param str a pointer to the location 323 * @param str a pointer where the location of the result shall be stored
306 * @param fmt the format string 324 * @param fmt the format string
307 * @param ... additional arguments 325 * @param ... additional arguments
308 * @return the length of produced string 326 * @return the length of produced string or an error code from stdlib printf implementation
309 */ 327 */
310 __attribute__((__nonnull__(1, 2, 4, 5), __format__(printf, 5, 6)))
311 cx_attr_nonnull_arg(1, 2, 4, 5) 328 cx_attr_nonnull_arg(1, 2, 4, 5)
312 cx_attr_printf(5, 6) 329 cx_attr_printf(5, 6)
313 cx_attr_cstr_arg(5) 330 cx_attr_cstr_arg(5)
331 cx_attr_access_rw(2)
332 cx_attr_access_rw(3)
333 cx_attr_access_rw(4)
334 cx_attr_export
314 int cx_sprintf_sa( 335 int cx_sprintf_sa(
315 CxAllocator *alloc, 336 CxAllocator *alloc,
316 char *buf, 337 char *buf,
317 size_t *len, 338 size_t *len,
318 char **str, 339 char **str,
319 const char *fmt, 340 const char *fmt,
320 ... 341 ...
321 ); 342 );
322 343
323 /** 344 /**
324 * An \c sprintf like function which allocates a new string when the buffer is not large enough. 345 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
325 * 346 *
326 * The size of the buffer will be updated in \p len when necessary. 347 * The size of the buffer will be updated in @p len when necessary.
327 * 348 *
328 * The location of the resulting string will \em always be stored to \p str. When the buffer 349 * The location of the resulting string will @em always be stored to @p str. When the buffer
329 * was sufficiently large, \p buf itself will be stored to the location of \p str. 350 * was sufficiently large, @p buf itself will be stored to the location of @p str.
330 * 351 *
331 * \note The resulting string is guaranteed to be zero-terminated. 352 * @note The resulting string is guaranteed to be zero-terminated.
332 * 353 *
333 * \remark When a new string needed to be allocated, the contents of \p buf will be 354 * @remark When a new string needed to be allocated, the contents of @p buf will be
334 * poisoned after the call, because this function tries to produce the string in \p buf, first. 355 * poisoned after the call, because this function tries to produce the string in @p buf, first.
335 * 356 *
336 * @param buf a pointer to the buffer 357 * @param buf (@c char*) a pointer to the buffer
337 * @param len a pointer to the length of the buffer 358 * @param len (@c size_t*) a pointer to the length of the buffer
338 * @param str a pointer to the location 359 * @param str (@c char**) a pointer where the location of the result shall be stored
339 * @param fmt the format string 360 * @param fmt (@c char*) the format string
340 * @param ap argument list 361 * @param ap (@c va_list) argument list
341 * @return the length of produced string 362 * @return (@c int) the length of produced string or an error code from stdlib printf implementation
342 */ 363 */
343 #define cx_vsprintf_s(buf, len, str, fmt, ap) cx_vsprintf_sa(cxDefaultAllocator, buf, len, str, fmt, ap) 364 #define cx_vsprintf_s(buf, len, str, fmt, ap) cx_vsprintf_sa(cxDefaultAllocator, buf, len, str, fmt, ap)
344 365
345 /** 366 /**
346 * An \c sprintf like function which allocates a new string when the buffer is not large enough. 367 * An @c sprintf like function which allocates a new string when the buffer is not large enough.
347 * 368 *
348 * The size of the buffer will be updated in \p len when necessary. 369 * The size of the buffer will be updated in @p len when necessary.
349 * 370 *
350 * The location of the resulting string will \em always be stored to \p str. When the buffer 371 * The location of the resulting string will @em always be stored to @p str. When the buffer
351 * was sufficiently large, \p buf itself will be stored to the location of \p str. 372 * was sufficiently large, @p buf itself will be stored to the location of @p str.
352 * 373 *
353 * \note The resulting string is guaranteed to be zero-terminated. 374 * @note The resulting string is guaranteed to be zero-terminated.
354 * 375 *
355 * \remark When a new string needed to be allocated, the contents of \p buf will be 376 * @remark When a new string needed to be allocated, the contents of @p buf will be
356 * poisoned after the call, because this function tries to produce the string in \p buf, first. 377 * poisoned after the call, because this function tries to produce the string in @p buf, first.
357 * 378 *
358 * @param alloc the allocator to use 379 * @param alloc the allocator to use
359 * @param buf a pointer to the buffer 380 * @param buf a pointer to the buffer
360 * @param len a pointer to the length of the buffer 381 * @param len a pointer to the length of the buffer
361 * @param str a pointer to the location 382 * @param str a pointer where the location of the result shall be stored
362 * @param fmt the format string 383 * @param fmt the format string
363 * @param ap argument list 384 * @param ap argument list
364 * @return the length of produced string 385 * @return the length of produced string or an error code from stdlib printf implementation
365 */ 386 */
366 cx_attr_nonnull 387 cx_attr_nonnull
367 cx_attr_cstr_arg(5) 388 cx_attr_cstr_arg(5)
389 cx_attr_export
368 int cx_vsprintf_sa( 390 int cx_vsprintf_sa(
369 CxAllocator *alloc, 391 CxAllocator *alloc,
370 char *buf, 392 char *buf,
371 size_t *len, 393 size_t *len,
372 char **str, 394 char **str,

Mercurial Repository: dbutils

mercurial