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 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 struct printbuf {
  31   char *buf;
  32   int bpos;
  33   int size;
  34 };
  35 typedef struct printbuf printbuf;
  36
  37 extern struct printbuf*
  38 printbuf_new(void);
  39
  40 /* As an optimization, printbuf_memappend_fast() is defined as a macro
  41  * that handles copying data if the buffer is large enough; otherwise
  42  * it invokes printbuf_memappend() which performs the heavy
  43  * lifting of realloc()ing the buffer and copying data.
  44  *
  45  * Your code should not use printbuf_memappend() directly unless it
  46  * checks the return code. Use printbuf_memappend_fast() instead.
  47  */
  48 extern int
  49 printbuf_memappend(struct printbuf *p, const char *buf, int size);
  50
  51 #define printbuf_memappend_fast(p, bufptr, bufsize)          \
  52 do {                                                         \
  53   if ((p->size - p->bpos) > bufsize) {                       \
  54     memcpy(p->buf + p->bpos, (bufptr), bufsize);             \
  55     p->bpos += bufsize;                                      \
  56     p->buf[p->bpos]= '\0';                                   \
  57   } else {  printbuf_memappend(p, (bufptr), bufsize); }      \
  58 } while (0)
  59
  60 #define printbuf_length(p) ((p)->bpos)
  61
  62 /**
  63  * Results in a compile error if the argument is not a string literal.
  64  */
  65 #define _printbuf_check_literal(mystr) ("" mystr)
  66
  67 /**
  68  * This is an optimization wrapper around printbuf_memappend() that is useful
  69  * for appending string literals. Since the size of string constants is known
  70  * at compile time, using this macro can avoid a costly strlen() call. This is
  71  * especially helpful when a constant string must be appended many times. If
  72  * you got here because of a compilation error caused by passing something
  73  * other than a string literal, use printbuf_memappend_fast() in conjunction
  74  * with strlen().
  75  *
  76  * See also:
  77  *   printbuf_memappend_fast()
  78  *   printbuf_memappend()
  79  *   sprintbuf()
  80  */
  81 #define printbuf_strappend(pb, str) \
  82    printbuf_memappend ((pb), _printbuf_check_literal(str), sizeof(str) - 1)
  83
  84 /**
  85  * Set len bytes of the buffer to charvalue, starting at offset offset.
  86  * Similar to calling memset(x, charvalue, len);
  87  *
  88  * The memory allocated for the buffer is extended as necessary.
  89  *
  90  * If offset is -1, this starts at the end of the current data in the buffer.
  91  */
  92 extern int
  93 printbuf_memset(struct printbuf *pb, int offset, int charvalue, int len);
  94
  95 /**
  96  * Formatted print to printbuf.
  97  *
  98  * This function is the most expensive of the available functions for appending
  99  * string data to a printbuf and should be used only where convenience is more
 100  * important than speed. Avoid using this function in high performance code or
 101  * tight loops; in these scenarios, consider using snprintf() with a static
 102  * buffer in conjunction with one of the printbuf_*append() functions.
 103  *
 104  * See also:
 105  *   printbuf_memappend_fast()
 106  *   printbuf_memappend()
 107  *   printbuf_strappend()
 108  */
 109 extern int
 110 sprintbuf(struct printbuf *p, const char *msg, ...);
 111
 112 extern void
 113 printbuf_reset(struct printbuf *p);
 114
 115 extern void
 116 printbuf_free(struct printbuf *p);
 117
 118 #ifdef __cplusplus
 119 }
 120 #endif
 121
 122 #endif