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-2023, 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;
43 
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  */
145  const void *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  */
153  const void *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 */
#define pg_attribute_printf(f, a)
Definition: c.h:175
static void const char * fmt
const void * data
void appendStringInfo(StringInfo str, const char *fmt,...) pg_attribute_printf(2
StringInfo makeStringInfo(void)
Definition: stringinfo.c:41
struct StringInfoData StringInfoData
StringInfoData * StringInfo
Definition: stringinfo.h:44
void int void appendStringInfoString(StringInfo str, const char *s)
Definition: stringinfo.c:176
void resetStringInfo(StringInfo str)
Definition: stringinfo.c:75
void enlargeStringInfo(StringInfo str, int needed)
Definition: stringinfo.c:283
void appendBinaryStringInfoNT(StringInfo str, const void *data, int datalen)
Definition: stringinfo.c:253
void appendBinaryStringInfo(StringInfo str, const void *data, int datalen)
Definition: stringinfo.c:227
void int appendStringInfoVA(StringInfo str, const char *fmt, va_list args) pg_attribute_printf(2
void appendStringInfoSpaces(StringInfo str, int count)
Definition: stringinfo.c:206
void appendStringInfoChar(StringInfo str, char ch)
Definition: stringinfo.c:188
void initStringInfo(StringInfo str)
Definition: stringinfo.c:59