comparison: ucx/cx/printf.h
ucx/cx/printf.h
- changeset 818
- bc782cca0759
- parent 816
- 839fefbdedc7
equal
deleted
inserted
replaced
| 817:22257f6d06a3 | 818:bc782cca0759 |
|---|---|
| 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 * \version 3.0 | |
| 34 * \copyright 2-Clause BSD License | 33 * \copyright 2-Clause BSD License |
| 35 */ | 34 */ |
| 36 | 35 |
| 37 #ifndef UCX_PRINTF_H | 36 #ifndef UCX_PRINTF_H |
| 38 #define UCX_PRINTF_H | 37 #define UCX_PRINTF_H |
| 42 #include <stdarg.h> | 41 #include <stdarg.h> |
| 43 | 42 |
| 44 #ifdef __cplusplus | 43 #ifdef __cplusplus |
| 45 extern "C" { | 44 extern "C" { |
| 46 #endif | 45 #endif |
| 46 | |
| 47 | |
| 48 /** | |
| 49 * The maximum string length that fits into stack memory. | |
| 50 */ | |
| 51 extern unsigned const cx_printf_sbo_size; | |
| 47 | 52 |
| 48 /** | 53 /** |
| 49 * A \c fprintf like function which writes the output to a stream by | 54 * A \c fprintf like function which writes the output to a stream by |
| 50 * using a write_func. | 55 * using a write_func. |
| 51 * | 56 * |
| 157 * @see ucx_fprintf() | 162 * @see ucx_fprintf() |
| 158 */ | 163 */ |
| 159 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((CxBuffer*)buffer, \ | 164 #define cx_bprintf(buffer, fmt, ...) cx_fprintf((CxBuffer*)buffer, \ |
| 160 (cx_write_func) cxBufferWrite, fmt, __VA_ARGS__) | 165 (cx_write_func) cxBufferWrite, fmt, __VA_ARGS__) |
| 161 | 166 |
| 167 | |
| 168 /** | |
| 169 * An \c sprintf like function which reallocates the string when the buffer is not large enough. | |
| 170 * | |
| 171 * The size of the buffer will be updated in \p len when necessary. | |
| 172 * | |
| 173 * \note The resulting string is guaranteed to be zero-terminated. | |
| 174 * | |
| 175 * @param str a pointer to the string buffer | |
| 176 * @param len a pointer to the length of the buffer | |
| 177 * @param fmt the format string | |
| 178 * @param ... additional arguments | |
| 179 * @return the length of produced string | |
| 180 */ | |
| 181 #define cx_sprintf(str, len, fmt, ...) cx_sprintf_a(cxDefaultAllocator, str, len, fmt, __VA_ARGS__) | |
| 182 | |
| 183 /** | |
| 184 * An \c sprintf like function which reallocates the string when the buffer is not large enough. | |
| 185 * | |
| 186 * The size of the buffer will be updated in \p len when necessary. | |
| 187 * | |
| 188 * \note The resulting string is guaranteed to be zero-terminated. | |
| 189 * | |
| 190 * \attention The original buffer MUST have been allocated with the same allocator! | |
| 191 * | |
| 192 * @param alloc the allocator to use | |
| 193 * @param str a pointer to the string buffer | |
| 194 * @param len a pointer to the length of the buffer | |
| 195 * @param fmt the format string | |
| 196 * @param ... additional arguments | |
| 197 * @return the length of produced string | |
| 198 */ | |
| 199 __attribute__((__nonnull__(1, 2, 3, 4), __format__(printf, 4, 5))) | |
| 200 int cx_sprintf_a(CxAllocator *alloc, char **str, size_t *len, const char *fmt, ... ); | |
| 201 | |
| 202 | |
| 203 /** | |
| 204 * An \c sprintf like function which reallocates the string when the buffer is not large enough. | |
| 205 * | |
| 206 * The size of the buffer will be updated in \p len when necessary. | |
| 207 * | |
| 208 * \note The resulting string is guaranteed to be zero-terminated. | |
| 209 * | |
| 210 * @param str a pointer to the string buffer | |
| 211 * @param len a pointer to the length of the buffer | |
| 212 * @param fmt the format string | |
| 213 * @param ap argument list | |
| 214 * @return the length of produced string | |
| 215 */ | |
| 216 #define cx_vsprintf(str, len, fmt, ap) cx_vsprintf_a(cxDefaultAllocator, str, len, fmt, ap) | |
| 217 | |
| 218 /** | |
| 219 * An \c sprintf like function which reallocates the string when the buffer is not large enough. | |
| 220 * | |
| 221 * The size of the buffer will be updated in \p len when necessary. | |
| 222 * | |
| 223 * \note The resulting string is guaranteed to be zero-terminated. | |
| 224 * | |
| 225 * \attention The original buffer MUST have been allocated with the same allocator! | |
| 226 * | |
| 227 * @param alloc the allocator to use | |
| 228 * @param str a pointer to the string buffer | |
| 229 * @param len a pointer to the length of the buffer | |
| 230 * @param fmt the format string | |
| 231 * @param ap argument list | |
| 232 * @return the length of produced string | |
| 233 */ | |
| 234 __attribute__((__nonnull__)) | |
| 235 int cx_vsprintf_a(CxAllocator *alloc, char **str, size_t *len, const char *fmt, va_list ap); | |
| 236 | |
| 237 | |
| 238 /** | |
| 239 * An \c sprintf like function which allocates a new string when the buffer is not large enough. | |
| 240 * | |
| 241 * The size of the buffer will be updated in \p len when necessary. | |
| 242 * | |
| 243 * The location of the resulting string will \em always be stored to \p str. When the buffer | |
| 244 * was sufficiently large, \p buf itself will be stored to the location of \p str. | |
| 245 * | |
| 246 * \note The resulting string is guaranteed to be zero-terminated. | |
| 247 * | |
| 248 * \remark When a new string needed to be allocated, the contents of \p buf will be | |
| 249 * poisoned after the call, because this function tries to produce the string in \p buf, first. | |
| 250 * | |
| 251 * @param buf a pointer to the buffer | |
| 252 * @param len a pointer to the length of the buffer | |
| 253 * @param str a pointer to the location | |
| 254 * @param fmt the format string | |
| 255 * @param ... additional arguments | |
| 256 * @return the length of produced string | |
| 257 */ | |
| 258 #define cx_sprintf_s(buf, len, str, fmt, ...) cx_sprintf_sa(cxDefaultAllocator, buf, len, str, fmt, __VA_ARGS__) | |
| 259 | |
| 260 /** | |
| 261 * An \c sprintf like function which allocates a new string when the buffer is not large enough. | |
| 262 * | |
| 263 * The size of the buffer will be updated in \p len when necessary. | |
| 264 * | |
| 265 * The location of the resulting string will \em always be stored to \p str. When the buffer | |
| 266 * was sufficiently large, \p buf itself will be stored to the location of \p str. | |
| 267 * | |
| 268 * \note The resulting string is guaranteed to be zero-terminated. | |
| 269 * | |
| 270 * \remark When a new string needed to be allocated, the contents of \p buf will be | |
| 271 * poisoned after the call, because this function tries to produce the string in \p buf, first. | |
| 272 * | |
| 273 * @param alloc the allocator to use | |
| 274 * @param buf a pointer to the buffer | |
| 275 * @param len a pointer to the length of the buffer | |
| 276 * @param str a pointer to the location | |
| 277 * @param fmt the format string | |
| 278 * @param ... additional arguments | |
| 279 * @return the length of produced string | |
| 280 */ | |
| 281 __attribute__((__nonnull__(1, 2, 4, 5), __format__(printf, 5, 6))) | |
| 282 int cx_sprintf_sa(CxAllocator *alloc, char *buf, size_t *len, char **str, const char *fmt, ... ); | |
| 283 | |
| 284 /** | |
| 285 * An \c sprintf like function which allocates a new string when the buffer is not large enough. | |
| 286 * | |
| 287 * The size of the buffer will be updated in \p len when necessary. | |
| 288 * | |
| 289 * The location of the resulting string will \em always be stored to \p str. When the buffer | |
| 290 * was sufficiently large, \p buf itself will be stored to the location of \p str. | |
| 291 * | |
| 292 * \note The resulting string is guaranteed to be zero-terminated. | |
| 293 * | |
| 294 * \remark When a new string needed to be allocated, the contents of \p buf will be | |
| 295 * poisoned after the call, because this function tries to produce the string in \p buf, first. | |
| 296 * | |
| 297 * @param buf a pointer to the buffer | |
| 298 * @param len a pointer to the length of the buffer | |
| 299 * @param str a pointer to the location | |
| 300 * @param fmt the format string | |
| 301 * @param ap argument list | |
| 302 * @return the length of produced string | |
| 303 */ | |
| 304 #define cx_vsprintf_s(buf, len, str, fmt, ap) cx_vsprintf_sa(cxDefaultAllocator, buf, len, str, fmt, ap) | |
| 305 | |
| 306 /** | |
| 307 * An \c sprintf like function which allocates a new string when the buffer is not large enough. | |
| 308 * | |
| 309 * The size of the buffer will be updated in \p len when necessary. | |
| 310 * | |
| 311 * The location of the resulting string will \em always be stored to \p str. When the buffer | |
| 312 * was sufficiently large, \p buf itself will be stored to the location of \p str. | |
| 313 * | |
| 314 * \note The resulting string is guaranteed to be zero-terminated. | |
| 315 * | |
| 316 * \remark When a new string needed to be allocated, the contents of \p buf will be | |
| 317 * poisoned after the call, because this function tries to produce the string in \p buf, first. | |
| 318 * | |
| 319 * @param alloc the allocator to use | |
| 320 * @param buf a pointer to the buffer | |
| 321 * @param len a pointer to the length of the buffer | |
| 322 * @param str a pointer to the location | |
| 323 * @param fmt the format string | |
| 324 * @param ap argument list | |
| 325 * @return the length of produced string | |
| 326 */ | |
| 327 __attribute__((__nonnull__)) | |
| 328 int cx_vsprintf_sa(CxAllocator *alloc, char *buf, size_t *len, char **str, const char *fmt, va_list ap); | |
| 329 | |
| 330 | |
| 162 #ifdef __cplusplus | 331 #ifdef __cplusplus |
| 163 } // extern "C" | 332 } // extern "C" |
| 164 #endif | 333 #endif |
| 165 | 334 |
| 166 #endif //UCX_PRINTF_H | 335 #endif //UCX_PRINTF_H |
