← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to src/include/lib/stringinfo.h

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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-2005, PostgreSQL Global Development Group
 
11
 * Portions Copyright (c) 1994, Regents of the University of California
 
12
 *
 
13
 * $PostgreSQL: pgsql/src/include/lib/stringinfo.h,v 1.31 2004-12-31 22:03:31 pgsql Exp $
 
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
 * appendStringInfo
 
83
 * Format text data under the control of fmt (an sprintf-style format string)
 
84
 * and append it to whatever is already in str.  More space is allocated
 
85
 * to str if necessary.  This is sort of like a combination of sprintf and
 
86
 * strcat.
 
87
 */
 
88
extern void
 
89
appendStringInfo(StringInfo str, const char *fmt,...)
 
90
/* This extension allows gcc to check the format string */
 
91
__attribute__((format(printf, 2, 3)));
 
92
 
 
93
/*------------------------
 
94
 * appendStringInfoVA
 
95
 * Attempt to format text data under the control of fmt (an sprintf-style
 
96
 * format string) and append it to whatever is already in str.  If successful
 
97
 * return true; if not (because there's not enough space), return false
 
98
 * without modifying str.  Typically the caller would enlarge str and retry
 
99
 * on false return --- see appendStringInfo for standard usage pattern.
 
100
 */
 
101
extern bool appendStringInfoVA(StringInfo str, const char *fmt, va_list args);
 
102
 
 
103
/*------------------------
 
104
 * appendStringInfoString
 
105
 * Append a null-terminated string to str.
 
106
 * Like appendStringInfo(str, "%s", s) but faster.
 
107
 */
 
108
extern void appendStringInfoString(StringInfo str, const char *s);
 
109
 
 
110
/*------------------------
 
111
 * appendStringInfoChar
 
112
 * Append a single byte to str.
 
113
 * Like appendStringInfo(str, "%c", ch) but much faster.
 
114
 */
 
115
extern void appendStringInfoChar(StringInfo str, char ch);
 
116
 
 
117
/*------------------------
 
118
 * appendStringInfoCharMacro
 
119
 * As above, but a macro for even more speed where it matters.
 
120
 * Caution: str argument will be evaluated multiple times.
 
121
 */
 
122
#define appendStringInfoCharMacro(str,ch) \
 
123
        (((str)->len + 1 >= (str)->maxlen) ? \
 
124
         appendStringInfoChar(str, ch) : \
 
125
         (void)((str)->data[(str)->len] = (ch), (str)->data[++(str)->len] = '\0'))
 
126
 
 
127
/*------------------------
 
128
 * appendBinaryStringInfo
 
129
 * Append arbitrary binary data to a StringInfo, allocating more space
 
130
 * if necessary.
 
131
 */
 
132
extern void appendBinaryStringInfo(StringInfo str,
 
133
                                           const char *data, int datalen);
 
134
 
 
135
/*------------------------
 
136
 * enlargeStringInfo
 
137
 * Make sure a StringInfo's buffer can hold at least 'needed' more bytes.
 
138
 */
 
139
extern void enlargeStringInfo(StringInfo str, int needed);
 
140
 
 
141
#endif   /* STRINGINFO_H */