printbuf.h

   1 /*
   2  * $Id: printbuf.h,v 1.4 2006/01/26 02:16:28 mclark Exp $
   3  *
   4  * Copyright (c) 2004, 2005 Metaparadigm Pte. Ltd.
   5  * Michael Clark <michael@metaparadigm.com>
   6  *
   7  * This library is free software; you can redistribute it and/or modify
   8  * it under the terms of the MIT license. See COPYING for details.
   9  *
  10  *
  11  * Copyright (c) 2008-2009 Yahoo! Inc.  All rights reserved.
  12  * The copyrights to the contents of this file are licensed under the MIT License
  13  * (http://www.opensource.org/licenses/mit-license.php)
  14  */
  15
  16 /**
  17  * @file
  18  * @brief Internal string buffer handing.  Unless you're writing a
  19  *        json_object_to_json_string_fn implementation for use with
  20  *        json_object_set_serializer() direct use of this is not
  21  *        recommended.
  22  */
  23 #ifndef _printbuf_h_
  24 #define _printbuf_h_
  25
  26 #ifndef JSON_EXPORT
  27 #if defined(_MSC_VER)
  28 #define JSON_EXPORT __declspec(dllexport)
  29 #else
  30 #define JSON_EXPORT extern
  31 #endif
  32 #endif
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 struct printbuf
  39 {
  40         char *buf;
  41         int bpos;
  42         int size;
  43 };
  44 typedef struct printbuf printbuf;
  45
  46 JSON_EXPORT struct printbuf *printbuf_new(void);
  47
  48 /* As an optimization, printbuf_memappend_fast() is defined as a macro
  49  * that handles copying data if the buffer is large enough; otherwise
  50  * it invokes printbuf_memappend() which performs the heavy
  51  * lifting of realloc()ing the buffer and copying data.
  52  *
  53  * Your code should not use printbuf_memappend() directly unless it
  54  * checks the return code. Use printbuf_memappend_fast() instead.
  55  */
  56 JSON_EXPORT int printbuf_memappend(struct printbuf *p, const char *buf, int size);
  57
  58 #define printbuf_memappend_fast(p, bufptr, bufsize)                  \
  59         do                                                           \
  60         {                                                            \
  61                 if ((p->size - p->bpos) > bufsize)                   \
  62                 {                                                    \
  63                         memcpy(p->buf + p->bpos, (bufptr), bufsize); \
  64                         p->bpos += bufsize;                          \
  65                         p->buf[p->bpos] = '\0';                      \
  66                 }                                                    \
  67                 else                                                 \
  68                 {                                                    \
  69                         printbuf_memappend(p, (bufptr), bufsize);    \
  70                 }                                                    \
  71         } while (0)
  72
  73 #define printbuf_length(p) ((p)->bpos)
  74
  75 /**
  76  * Results in a compile error if the argument is not a string literal.
  77  */
  78 #define _printbuf_check_literal(mystr) ("" mystr)
  79
  80 /**
  81  * This is an optimization wrapper around printbuf_memappend() that is useful
  82  * for appending string literals. Since the size of string constants is known
  83  * at compile time, using this macro can avoid a costly strlen() call. This is
  84  * especially helpful when a constant string must be appended many times. If
  85  * you got here because of a compilation error caused by passing something
  86  * other than a string literal, use printbuf_memappend_fast() in conjunction
  87  * with strlen().
  88  *
  89  * See also:
  90  *   printbuf_memappend_fast()
  91  *   printbuf_memappend()
  92  *   sprintbuf()
  93  */
  94 #define printbuf_strappend(pb, str) \
  95         printbuf_memappend((pb), _printbuf_check_literal(str), sizeof(str) - 1)
  96
  97 /**
  98  * Set len bytes of the buffer to charvalue, starting at offset offset.
  99  * Similar to calling memset(x, charvalue, len);
 100  *
 101  * The memory allocated for the buffer is extended as necessary.
 102  *
 103  * If offset is -1, this starts at the end of the current data in the buffer.
 104  */
 105 JSON_EXPORT int printbuf_memset(struct printbuf *pb, int offset, int charvalue, int len);
 106
 107 /**
 108  * Formatted print to printbuf.
 109  *
 110  * This function is the most expensive of the available functions for appending
 111  * string data to a printbuf and should be used only where convenience is more
 112  * important than speed. Avoid using this function in high performance code or
 113  * tight loops; in these scenarios, consider using snprintf() with a static
 114  * buffer in conjunction with one of the printbuf_*append() functions.
 115  *
 116  * See also:
 117  *   printbuf_memappend_fast()
 118  *   printbuf_memappend()
 119  *   printbuf_strappend()
 120  */
 121 JSON_EXPORT int sprintbuf(struct printbuf *p, const char *msg, ...);
 122
 123 JSON_EXPORT void printbuf_reset(struct printbuf *p);
 124
 125 JSON_EXPORT void printbuf_free(struct printbuf *p);
 126
 127 #ifdef __cplusplus
 128 }
 129 #endif
 130
 131 #endif