codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * stringinfo.h4 *	  Declarations/definitions for "StringInfo" functions.5 *6 * StringInfo provides an extensible string data type (currently limited to a7 * length of 1GB).  It can be used to buffer either ordinary C strings8 * (null-terminated text) or arbitrary binary data.  All storage is allocated9 * with palloc() (falling back to malloc in frontend code).10 *11 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group12 * Portions Copyright (c) 1994, Regents of the University of California13 *14 * src/include/lib/stringinfo.h15 *16 *-------------------------------------------------------------------------17 */18#ifndef STRINGINFO_H19#define STRINGINFO_H20 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 be25 *				a terminating '\0' at data[len], although this is not very26 *				useful when the string holds binary data rather than text.27 *		maxlen	is the allocated size in bytes of 'data', i.e. the maximum28 *				string size (including the terminating '\0' char) that we can29 *				currently store in 'data' without having to reallocate30 *				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 */36typedef struct StringInfoData37{38	char	   *data;39	int			len;40	int			maxlen;41	int			cursor;42} StringInfoData;43 44typedef 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 will57 *		only live as long as the current routine.58 *59 * To destroy a StringInfo, pfree() the data buffer, and then pfree() the60 * 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 then63 * release the StringInfoData but return the data string itself to their64 * caller.  At that point the data string looks like a plain palloc'd65 * string.66 *-------------------------67 */68 69/*------------------------70 * makeStringInfo71 * Create an empty 'StringInfoData' & return a pointer to it.72 */73extern StringInfo makeStringInfo(void);74 75/*------------------------76 * initStringInfo77 * Initialize a StringInfoData struct (with previously undefined contents)78 * to describe an empty string.79 */80extern void initStringInfo(StringInfo str);81 82/*------------------------83 * resetStringInfo84 * Clears the current content of the StringInfo, if any. The85 * StringInfo remains valid.86 */87extern void resetStringInfo(StringInfo str);88 89/*------------------------90 * appendStringInfo91 * 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 allocated93 * to str if necessary.  This is sort of like a combination of sprintf and94 * strcat.95 */96extern void appendStringInfo(StringInfo str, const char *fmt,...) pg_attribute_printf(2, 3);97 98/*------------------------99 * appendStringInfoVA100 * Attempt to format text data under the control of fmt (an sprintf-style101 * format string) and append it to whatever is already in str.  If successful102 * return zero; if not (because there's not enough space), return an estimate103 * of the space needed, without modifying str.  Typically the caller should104 * pass the return value to enlargeStringInfo() before trying again; see105 * appendStringInfo for standard usage pattern.106 */107extern int	appendStringInfoVA(StringInfo str, const char *fmt, va_list args) pg_attribute_printf(2, 0);108 109/*------------------------110 * appendStringInfoString111 * Append a null-terminated string to str.112 * Like appendStringInfo(str, "%s", s) but faster.113 */114extern void appendStringInfoString(StringInfo str, const char *s);115 116/*------------------------117 * appendStringInfoChar118 * Append a single byte to str.119 * Like appendStringInfo(str, "%c", ch) but much faster.120 */121extern void appendStringInfoChar(StringInfo str, char ch);122 123/*------------------------124 * appendStringInfoCharMacro125 * 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 * appendStringInfoSpaces135 * Append a given number of spaces to str.136 */137extern void appendStringInfoSpaces(StringInfo str, int count);138 139/*------------------------140 * appendBinaryStringInfo141 * Append arbitrary binary data to a StringInfo, allocating more space142 * if necessary.143 */144extern void appendBinaryStringInfo(StringInfo str,145								   const void *data, int datalen);146 147/*------------------------148 * appendBinaryStringInfoNT149 * Append arbitrary binary data to a StringInfo, allocating more space150 * if necessary. Does not ensure a trailing null-byte exists.151 */152extern void appendBinaryStringInfoNT(StringInfo str,153									 const void *data, int datalen);154 155/*------------------------156 * enlargeStringInfo157 * Make sure a StringInfo's buffer can hold at least 'needed' more bytes.158 */159extern void enlargeStringInfo(StringInfo str, int needed);160 161#endif							/* STRINGINFO_H */162