src/include/lib/stringinfo.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * stringinfo.h
   4  *        Declarations/definitions for "StringInfo" functions.
   5  *
   6  * StringInfo provides an indefinitely-extensible string data type.
   7  * It can be used to buffer either ordinary C strings (null-terminated text)
   8  * or arbitrary binary data.  All storage is allocated with palloc().
   9  *
  10  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  11  * Portions Copyright (c) 1994, Regents of the University of California
  12  *
  13  * $PostgreSQL$
  14  *
  15  *-------------------------------------------------------------------------
  16  */
  17 #ifndef STRINGINFO_H
  18 #define STRINGINFO_H
  19
  20 /*-------------------------
  21  * StringInfoData holds information about an extensible string.
  22  *              data    is the current buffer for the string (allocated with palloc).
  23  *              len             is the current string length.  There is guaranteed to be
  24  *                              a terminating '\0' at data[len], although this is not very
  25  *                              useful when the string holds binary data rather than text.
  26  *              maxlen  is the allocated size in bytes of 'data', i.e. the maximum
  27  *                              string size (including the terminating '\0' char) that we can
  28  *                              currently store in 'data' without having to reallocate
  29  *                              more space.  We must always have maxlen > len.
  30  *              cursor  is initialized to zero by makeStringInfo or initStringInfo,
  31  *                              but is not otherwise touched by the stringinfo.c routines.
  32  *                              Some routines use it to scan through a StringInfo.
  33  *-------------------------
  34  */
  35 typedef struct StringInfoData
  36 {
  37         char       *data;
  38         int                     len;
  39         int                     maxlen;
  40         int                     cursor;
  41 } StringInfoData;
  42
  43 typedef StringInfoData *StringInfo;
  44
  45
  46 /*------------------------
  47  * There are two ways to create a StringInfo object initially:
  48  *
  49  * StringInfo stringptr = makeStringInfo();
  50  *              Both the StringInfoData and the data buffer are palloc'd.
  51  *
  52  * StringInfoData string;
  53  * initStringInfo(&string);
  54  *              The data buffer is palloc'd but the StringInfoData is just local.
  55  *              This is the easiest approach for a StringInfo object that will
  56  *              only live as long as the current routine.
  57  *
  58  * To destroy a StringInfo, pfree() the data buffer, and then pfree() the
  59  * StringInfoData if it was palloc'd.  There's no special support for this.
  60  *
  61  * NOTE: some routines build up a string using StringInfo, and then
  62  * release the StringInfoData but return the data string itself to their
  63  * caller.      At that point the data string looks like a plain palloc'd
  64  * string.
  65  *-------------------------
  66  */
  67
  68 /*------------------------
  69  * makeStringInfo
  70  * Create an empty 'StringInfoData' & return a pointer to it.
  71  */
  72 extern StringInfo makeStringInfo(void);
  73
  74 /*------------------------
  75  * initStringInfo
  76  * Initialize a StringInfoData struct (with previously undefined contents)
  77  * to describe an empty string.
  78  */
  79 extern void initStringInfo(StringInfo str);
  80
  81 /*------------------------
  82  * resetStringInfo
  83  * Clears the current content of the StringInfo, if any. The
  84  * StringInfo remains valid.
  85  */
  86 extern void resetStringInfo(StringInfo str);
  87
  88 /*------------------------
  89  * appendStringInfo
  90  * Format text data under the control of fmt (an sprintf-style format string)
  91  * and append it to whatever is already in str.  More space is allocated
  92  * to str if necessary.  This is sort of like a combination of sprintf and
  93  * strcat.
  94  */
  95 extern void
  96 appendStringInfo(StringInfo str, const char *fmt,...)
  97 /* This extension allows gcc to check the format string */
  98 __attribute__((format(printf, 2, 3)));
  99
 100 /*------------------------
 101  * appendStringInfoVA
 102  * Attempt to format text data under the control of fmt (an sprintf-style
 103  * format string) and append it to whatever is already in str.  If successful
 104  * return true; if not (because there's not enough space), return false
 105  * without modifying str.  Typically the caller would enlarge str and retry
 106  * on false return --- see appendStringInfo for standard usage pattern.
 107  */
 108 extern bool appendStringInfoVA(StringInfo str, const char *fmt, va_list args);
 109
 110 /*------------------------
 111  * appendStringInfoString
 112  * Append a null-terminated string to str.
 113  * Like appendStringInfo(str, "%s", s) but faster.
 114  */
 115 extern void appendStringInfoString(StringInfo str, const char *s);
 116
 117 /*------------------------
 118  * appendStringInfoChar
 119  * Append a single byte to str.
 120  * Like appendStringInfo(str, "%c", ch) but much faster.
 121  */
 122 extern void appendStringInfoChar(StringInfo str, char ch);
 123
 124 /*------------------------
 125  * appendStringInfoCharMacro
 126  * As above, but a macro for even more speed where it matters.
 127  * Caution: str argument will be evaluated multiple times.
 128  */
 129 #define appendStringInfoCharMacro(str,ch) \
 130         (((str)->len + 1 >= (str)->maxlen) ? \
 131          appendStringInfoChar(str, ch) : \
 132          (void)((str)->data[(str)->len] = (ch), (str)->data[++(str)->len] = '\0'))
 133
 134 /*------------------------
 135  * appendBinaryStringInfo
 136  * Append arbitrary binary data to a StringInfo, allocating more space
 137  * if necessary.
 138  */
 139 extern void appendBinaryStringInfo(StringInfo str,
 140                                            const char *data, int datalen);
 141
 142 /*------------------------
 143  * enlargeStringInfo
 144  * Make sure a StringInfo's buffer can hold at least 'needed' more bytes.
 145  */
 146 extern void enlargeStringInfo(StringInfo str, int needed);
 147
 148 #endif   /* STRINGINFO_H */