src/include/lib/stringinfo.h

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