PostgreSQL Source Code  git master
stringinfo.h
Go to the documentation of this file.
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-2024, 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.
24  * len is the current string length. Except in the case of read-only
25  * strings described below, there is guaranteed to be a
26  * terminating '\0' at data[len].
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, except
31  * in the read-only case described below.
32  * cursor is initialized to zero by makeStringInfo, initStringInfo,
33  * initReadOnlyStringInfo and initStringInfoFromString but is not
34  * otherwise touched by the stringinfo.c routines. Some routines
35  * use it to scan through a StringInfo.
36  *
37  * As a special case, a StringInfoData can be initialized with a read-only
38  * string buffer. In this case "data" does not necessarily point at a
39  * palloc'd chunk, and management of the buffer storage is the caller's
40  * responsibility. maxlen is set to zero to indicate that this is the case.
41  * Read-only StringInfoDatas cannot be appended to or reset.
42  * Also, it is caller's option whether a read-only string buffer has a
43  * terminating '\0' or not. This depends on the intended usage.
44  *-------------------------
45  */
46 typedef struct StringInfoData
47 {
48  char *data;
49  int len;
50  int maxlen;
51  int cursor;
53 
55 
56 
57 /*------------------------
58  * There are four ways to create a StringInfo object initially:
59  *
60  * StringInfo stringptr = makeStringInfo();
61  * Both the StringInfoData and the data buffer are palloc'd.
62  *
63  * StringInfoData string;
64  * initStringInfo(&string);
65  * The data buffer is palloc'd but the StringInfoData is just local.
66  * This is the easiest approach for a StringInfo object that will
67  * only live as long as the current routine.
68  *
69  * StringInfoData string;
70  * initReadOnlyStringInfo(&string, existingbuf, len);
71  * The StringInfoData's data field is set to point directly to the
72  * existing buffer and the StringInfoData's len is set to the given len.
73  * The given buffer can point to memory that's not managed by palloc or
74  * is pointing partway through a palloc'd chunk. The maxlen field is set
75  * to 0. A read-only StringInfo cannot be appended to using any of the
76  * appendStringInfo functions or reset with resetStringInfo(). The given
77  * buffer can optionally omit the trailing NUL.
78  *
79  * StringInfoData string;
80  * initStringInfoFromString(&string, palloced_buf, len);
81  * The StringInfoData's data field is set to point directly to the given
82  * buffer and the StringInfoData's len is set to the given len. This
83  * method of initialization is useful when the buffer already exists.
84  * StringInfos initialized this way can be appended to using the
85  * appendStringInfo functions and reset with resetStringInfo(). The
86  * given buffer must be NUL-terminated. The palloc'd buffer is assumed
87  * to be len + 1 in size.
88  *
89  * To destroy a StringInfo, pfree() the data buffer, and then pfree() the
90  * StringInfoData if it was palloc'd. There's no special support for this.
91  * However, if the StringInfo was initialized using initReadOnlyStringInfo()
92  * then the caller will need to consider if it is safe to pfree the data
93  * buffer.
94  *
95  * NOTE: some routines build up a string using StringInfo, and then
96  * release the StringInfoData but return the data string itself to their
97  * caller. At that point the data string looks like a plain palloc'd
98  * string.
99  *-------------------------
100  */
101 
102 /*------------------------
103  * makeStringInfo
104  * Create an empty 'StringInfoData' & return a pointer to it.
105  */
106 extern StringInfo makeStringInfo(void);
107 
108 /*------------------------
109  * initStringInfo
110  * Initialize a StringInfoData struct (with previously undefined contents)
111  * to describe an empty string.
112  */
113 extern void initStringInfo(StringInfo str);
114 
115 /*------------------------
116  * initReadOnlyStringInfo
117  * Initialize a StringInfoData struct from an existing string without copying
118  * the string. The caller is responsible for ensuring the given string
119  * remains valid as long as the StringInfoData does. Calls to this are used
120  * in performance critical locations where allocating a new buffer and copying
121  * would be too costly. Read-only StringInfoData's may not be appended to
122  * using any of the appendStringInfo functions or reset with
123  * resetStringInfo().
124  *
125  * 'data' does not need to point directly to a palloc'd chunk of memory and may
126  * omit the NUL termination character at data[len].
127  */
128 static inline void
130 {
131  str->data = data;
132  str->len = len;
133  str->maxlen = 0; /* read-only */
134  str->cursor = 0;
135 }
136 
137 /*------------------------
138  * initStringInfoFromString
139  * Initialize a StringInfoData struct from an existing string without copying
140  * the string. 'data' must be a valid palloc'd chunk of memory that can have
141  * repalloc() called should more space be required during a call to any of the
142  * appendStringInfo functions.
143  *
144  * 'data' must be NUL terminated at 'len' bytes.
145  */
146 static inline void
148 {
149  Assert(data[len] == '\0');
150 
151  str->data = data;
152  str->len = len;
153  str->maxlen = len + 1;
154  str->cursor = 0;
155 }
156 
157 /*------------------------
158  * resetStringInfo
159  * Clears the current content of the StringInfo, if any. The
160  * StringInfo remains valid.
161  */
162 extern void resetStringInfo(StringInfo str);
163 
164 /*------------------------
165  * appendStringInfo
166  * Format text data under the control of fmt (an sprintf-style format string)
167  * and append it to whatever is already in str. More space is allocated
168  * to str if necessary. This is sort of like a combination of sprintf and
169  * strcat.
170  */
171 extern void appendStringInfo(StringInfo str, const char *fmt,...) pg_attribute_printf(2, 3);
172 
173 /*------------------------
174  * appendStringInfoVA
175  * Attempt to format text data under the control of fmt (an sprintf-style
176  * format string) and append it to whatever is already in str. If successful
177  * return zero; if not (because there's not enough space), return an estimate
178  * of the space needed, without modifying str. Typically the caller should
179  * pass the return value to enlargeStringInfo() before trying again; see
180  * appendStringInfo for standard usage pattern.
181  */
182 extern int appendStringInfoVA(StringInfo str, const char *fmt, va_list args) pg_attribute_printf(2, 0);
183 
184 /*------------------------
185  * appendStringInfoString
186  * Append a null-terminated string to str.
187  * Like appendStringInfo(str, "%s", s) but faster.
188  */
189 extern void appendStringInfoString(StringInfo str, const char *s);
190 
191 /*------------------------
192  * appendStringInfoChar
193  * Append a single byte to str.
194  * Like appendStringInfo(str, "%c", ch) but much faster.
195  */
196 extern void appendStringInfoChar(StringInfo str, char ch);
197 
198 /*------------------------
199  * appendStringInfoCharMacro
200  * As above, but a macro for even more speed where it matters.
201  * Caution: str argument will be evaluated multiple times.
202  */
203 #define appendStringInfoCharMacro(str,ch) \
204  (((str)->len + 1 >= (str)->maxlen) ? \
205  appendStringInfoChar(str, ch) : \
206  (void)((str)->data[(str)->len] = (ch), (str)->data[++(str)->len] = '\0'))
207 
208 /*------------------------
209  * appendStringInfoSpaces
210  * Append a given number of spaces to str.
211  */
212 extern void appendStringInfoSpaces(StringInfo str, int count);
213 
214 /*------------------------
215  * appendBinaryStringInfo
216  * Append arbitrary binary data to a StringInfo, allocating more space
217  * if necessary.
218  */
220  const void *data, int datalen);
221 
222 /*------------------------
223  * appendBinaryStringInfoNT
224  * Append arbitrary binary data to a StringInfo, allocating more space
225  * if necessary. Does not ensure a trailing null-byte exists.
226  */
228  const void *data, int datalen);
229 
230 /*------------------------
231  * enlargeStringInfo
232  * Make sure a StringInfo's buffer can hold at least 'needed' more bytes.
233  */
234 extern void enlargeStringInfo(StringInfo str, int needed);
235 
236 #endif /* STRINGINFO_H */
#define pg_attribute_printf(f, a)
Definition: c.h:180
static void const char * fmt
Assert(fmt[strlen(fmt) - 1] !='\n')
const void size_t len
const void * data
void appendStringInfo(StringInfo str, const char *fmt,...) pg_attribute_printf(2
static void initStringInfoFromString(StringInfo str, char *data, int len)
Definition: stringinfo.h:147
StringInfo makeStringInfo(void)
Definition: stringinfo.c:41
struct StringInfoData StringInfoData
StringInfoData * StringInfo
Definition: stringinfo.h:54
void int void appendStringInfoString(StringInfo str, const char *s)
Definition: stringinfo.c:182
void resetStringInfo(StringInfo str)
Definition: stringinfo.c:78
void enlargeStringInfo(StringInfo str, int needed)
Definition: stringinfo.c:289
void appendBinaryStringInfoNT(StringInfo str, const void *data, int datalen)
Definition: stringinfo.c:259
void appendBinaryStringInfo(StringInfo str, const void *data, int datalen)
Definition: stringinfo.c:233
void int appendStringInfoVA(StringInfo str, const char *fmt, va_list args) pg_attribute_printf(2
static void initReadOnlyStringInfo(StringInfo str, char *data, int len)
Definition: stringinfo.h:129
void appendStringInfoSpaces(StringInfo str, int count)
Definition: stringinfo.c:212
void appendStringInfoChar(StringInfo str, char ch)
Definition: stringinfo.c:194
void initStringInfo(StringInfo str)
Definition: stringinfo.c:59