include/json-c/printbuf.h

0001 /*
0002  * $Id: printbuf.h,v 1.4 2006/01/26 02:16:28 mclark Exp $
0003  *
0004  * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd.
0005  * Michael Clark <michael@metaparadigm.com>
0006  *
0007  * This library is free software; you can redistribute it and/or modify
0008  * it under the terms of the MIT license. See COPYING for details.
0009  *
0010  *
0011  * Copyright (c) 2008-2009 Yahoo! Inc.  All rights reserved.
0012  * The copyrights to the contents of this file are licensed under the MIT License
0013  * (https://www.opensource.org/licenses/mit-license.php)
0014  */
0015
0016 /**
0017  * @file
0018  * @brief Internal string buffer handling.  Unless you're writing a
0019  *        json_object_to_json_string_fn implementation for use with
0020  *        json_object_set_serializer() direct use of this is not
0021  *        recommended.
0022  */
0023 #ifndef _json_c_printbuf_h_
0024 #define _json_c_printbuf_h_
0025
0026 #ifndef JSON_EXPORT
0027 #if defined(_MSC_VER) && defined(JSON_C_DLL)
0028 #define JSON_EXPORT __declspec(dllexport)
0029 #else
0030 #define JSON_EXPORT extern
0031 #endif
0032 #endif
0033
0034 #ifdef __cplusplus
0035 extern "C" {
0036 #endif
0037
0038 struct printbuf
0039 {
0040     char *buf;
0041     int bpos;
0042     int size;
0043 };
0044 typedef struct printbuf printbuf;
0045
0046 JSON_EXPORT struct printbuf *printbuf_new(void);
0047
0048 /* As an optimization, printbuf_memappend_fast() is defined as a macro
0049  * that handles copying data if the buffer is large enough; otherwise
0050  * it invokes printbuf_memappend() which performs the heavy
0051  * lifting of realloc()ing the buffer and copying data.
0052  *
0053  * Your code should not use printbuf_memappend() directly unless it
0054  * checks the return code. Use printbuf_memappend_fast() instead.
0055  */
0056 JSON_EXPORT int printbuf_memappend(struct printbuf *p, const char *buf, int size);
0057
0058 #define printbuf_memappend_fast(p, bufptr, bufsize)                  \
0059     do                                                           \
0060     {                                                            \
0061         if ((p->size - p->bpos) > bufsize)                   \
0062         {                                                    \
0063             memcpy(p->buf + p->bpos, (bufptr), bufsize); \
0064             p->bpos += bufsize;                          \
0065             p->buf[p->bpos] = '\0';                      \
0066         }                                                    \
0067         else                                                 \
0068         {                                                    \
0069             printbuf_memappend(p, (bufptr), bufsize);    \
0070         }                                                    \
0071     } while (0)
0072
0073 #define printbuf_length(p) ((p)->bpos)
0074
0075 /**
0076  * Results in a compile error if the argument is not a string literal.
0077  */
0078 #define _printbuf_check_literal(mystr) ("" mystr)
0079
0080 /**
0081  * This is an optimization wrapper around printbuf_memappend() that is useful
0082  * for appending string literals. Since the size of string constants is known
0083  * at compile time, using this macro can avoid a costly strlen() call. This is
0084  * especially helpful when a constant string must be appended many times. If
0085  * you got here because of a compilation error caused by passing something
0086  * other than a string literal, use printbuf_memappend_fast() in conjunction
0087  * with strlen().
0088  *
0089  * See also:
0090  *   printbuf_memappend_fast()
0091  *   printbuf_memappend()
0092  *   sprintbuf()
0093  */
0094 #define printbuf_strappend(pb, str) \
0095     printbuf_memappend((pb), _printbuf_check_literal(str), sizeof(str) - 1)
0096
0097 /**
0098  * Set len bytes of the buffer to charvalue, starting at offset offset.
0099  * Similar to calling memset(x, charvalue, len);
0100  *
0101  * The memory allocated for the buffer is extended as necessary.
0102  *
0103  * If offset is -1, this starts at the end of the current data in the buffer.
0104  */
0105 JSON_EXPORT int printbuf_memset(struct printbuf *pb, int offset, int charvalue, int len);
0106
0107 /**
0108  * Formatted print to printbuf.
0109  *
0110  * This function is the most expensive of the available functions for appending
0111  * string data to a printbuf and should be used only where convenience is more
0112  * important than speed. Avoid using this function in high performance code or
0113  * tight loops; in these scenarios, consider using snprintf() with a static
0114  * buffer in conjunction with one of the printbuf_*append() functions.
0115  *
0116  * See also:
0117  *   printbuf_memappend_fast()
0118  *   printbuf_memappend()
0119  *   printbuf_strappend()
0120  */
0121 JSON_EXPORT int sprintbuf(struct printbuf *p, const char *msg, ...);
0122
0123 JSON_EXPORT void printbuf_reset(struct printbuf *p);
0124
0125 JSON_EXPORT void printbuf_free(struct printbuf *p);
0126
0127 #ifdef __cplusplus
0128 }
0129 #endif
0130
0131 #endif