PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
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 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-2017, PostgreSQL Global Development Group
11  * Portions Copyright (c) 1994, Regents of the University of California
12  *
13  * src/include/lib/stringinfo.h
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  * long_ok whether this StringInfo can allocate more than MaxAllocSize
34  * bytes (but still up to 2GB).
35  *-------------------------
36  */
37 typedef struct StringInfoData
38 {
39  char *data;
40  int len;
41  int maxlen;
42  int cursor;
43  bool long_ok;
45 
47 
48 
49 /*------------------------
50  * There are two ways to create a StringInfo object initially:
51  *
52  * StringInfo stringptr = makeStringInfo(); // or makeLongStringInfo();
53  * Both the StringInfoData and the data buffer are palloc'd.
54  *
55  * StringInfoData string;
56  * initStringInfo(&string); // or initLongStringInfo();
57  * The data buffer is palloc'd but the StringInfoData is just local.
58  * This is the easiest approach for a StringInfo object that will
59  * only live as long as the current routine.
60  *
61  * To destroy a StringInfo, pfree() the data buffer, and then pfree() the
62  * StringInfoData if it was palloc'd. There's no special support for this.
63  *
64  * NOTE: some routines build up a string using StringInfo, and then
65  * release the StringInfoData but return the data string itself to their
66  * caller. At that point the data string looks like a plain palloc'd
67  * string.
68  *-------------------------
69  */
70 
71 /*------------------------
72  * makeStringInfo
73  * makeLongStringInfo
74  * Create an empty 'StringInfoData' & return a pointer to it. The former
75  * allows up to 1 GB in size, per palloc(); the latter allows up to 2 GB.
76  */
77 extern StringInfo makeStringInfo(void);
78 extern StringInfo makeLongStringInfo(void);
79 
80 /*------------------------
81  * initStringInfo
82  * initLongStringInfo
83  * Initialize a StringInfoData struct (with previously undefined contents)
84  * to describe an empty string. Size limits as above.
85  */
86 extern void initStringInfo(StringInfo str);
87 extern void initLongStringInfo(StringInfo str);
88 
89 /*------------------------
90  * resetStringInfo
91  * Clears the current content of the StringInfo, if any. The
92  * StringInfo remains valid. The long_ok flag is not reset.
93  */
94 extern void resetStringInfo(StringInfo str);
95 
96 /*------------------------
97  * appendStringInfo
98  * Format text data under the control of fmt (an sprintf-style format string)
99  * and append it to whatever is already in str. More space is allocated
100  * to str if necessary. This is sort of like a combination of sprintf and
101  * strcat.
102  */
103 extern void appendStringInfo(StringInfo str, const char *fmt,...) pg_attribute_printf(2, 3);
104 
105 /*------------------------
106  * appendStringInfoVA
107  * Attempt to format text data under the control of fmt (an sprintf-style
108  * format string) and append it to whatever is already in str. If successful
109  * return zero; if not (because there's not enough space), return an estimate
110  * of the space needed, without modifying str. Typically the caller should
111  * pass the return value to enlargeStringInfo() before trying again; see
112  * appendStringInfo for standard usage pattern.
113  */
114 extern int appendStringInfoVA(StringInfo str, const char *fmt, va_list args) pg_attribute_printf(2, 0);
115 
116 /*------------------------
117  * appendStringInfoString
118  * Append a null-terminated string to str.
119  * Like appendStringInfo(str, "%s", s) but faster.
120  */
121 extern void appendStringInfoString(StringInfo str, const char *s);
122 
123 /*------------------------
124  * appendStringInfoChar
125  * Append a single byte to str.
126  * Like appendStringInfo(str, "%c", ch) but much faster.
127  */
128 extern void appendStringInfoChar(StringInfo str, char ch);
129 
130 /*------------------------
131  * appendStringInfoCharMacro
132  * As above, but a macro for even more speed where it matters.
133  * Caution: str argument will be evaluated multiple times.
134  */
135 #define appendStringInfoCharMacro(str,ch) \
136  (((str)->len + 1 >= (str)->maxlen) ? \
137  appendStringInfoChar(str, ch) : \
138  (void)((str)->data[(str)->len] = (ch), (str)->data[++(str)->len] = '\0'))
139 
140 /*------------------------
141  * appendStringInfoSpaces
142  * Append a given number of spaces to str.
143  */
144 extern void appendStringInfoSpaces(StringInfo str, int count);
145 
146 /*------------------------
147  * appendBinaryStringInfo
148  * Append arbitrary binary data to a StringInfo, allocating more space
149  * if necessary.
150  */
151 extern void appendBinaryStringInfo(StringInfo str,
152  const char *data, int datalen);
153 
154 /*------------------------
155  * enlargeStringInfo
156  * Make sure a StringInfo's buffer can hold at least 'needed' more bytes.
157  */
158 extern void enlargeStringInfo(StringInfo str, int needed);
159 
160 #endif /* STRINGINFO_H */
struct StringInfoData StringInfoData
void int appendStringInfoVA(StringInfo str, const char *fmt, va_list args) pg_attribute_printf(2
StringInfo makeLongStringInfo(void)
Definition: stringinfo.c:46
StringInfoData * StringInfo
Definition: stringinfo.h:46
void appendStringInfoSpaces(StringInfo str, int count)
Definition: stringinfo.c:219
void resetStringInfo(StringInfo str)
Definition: stringinfo.c:94
#define pg_attribute_printf(f, a)
Definition: c.h:633
void appendStringInfo(StringInfo str, const char *fmt,...) pg_attribute_printf(2
void initLongStringInfo(StringInfo str)
Definition: stringinfo.c:81
void int void appendStringInfoString(StringInfo str, const char *s)
Definition: stringinfo.c:189
void appendBinaryStringInfo(StringInfo str, const char *data, int datalen)
Definition: stringinfo.c:240
void appendStringInfoChar(StringInfo str, char ch)
Definition: stringinfo.c:201
void enlargeStringInfo(StringInfo str, int needed)
Definition: stringinfo.c:277
StringInfo makeStringInfo(void)
Definition: stringinfo.c:29
void initStringInfo(StringInfo str)
Definition: stringinfo.c:65