3 * $Id: dstr.h,v 1.2 1998/12/15 23:53:23 mdw Exp $
5 * Handle dynamically growing strings
7 * (c) 1998 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
14 * mLib is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
19 * mLib is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with mLib; if not, write to the Free Software Foundation,
26 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
29 /*----- Revision history --------------------------------------------------*
32 * Revision 1.2 1998/12/15 23:53:23 mdw
33 * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
34 * formatting in a safe way.
36 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
37 * Initial version of mLib
48 /*----- Rationale ---------------------------------------------------------*
50 * This file declares what is hopefully a fairly useful collection of
51 * primitive string handling functions. The idea is that the strings
52 * allocate memory for themselves as required. The @dstr@ routines don't
53 * assume any sort of terminator character, so arbitrary binary data can
54 * be stored in a dynamic string. With luck, this should put a stop to
55 * any buffer overflow problems.
58 /*----- Header files ------------------------------------------------------*/
63 /*----- Data structures ---------------------------------------------------*/
66 char *buf; /* Pointer to string buffer */
67 size_t sz; /* Size of the buffer */
68 size_t len; /* Length of the string */
71 /*----- Functions provided ------------------------------------------------*/
73 /* --- @dstr_create@ --- *
75 * Arguments: @dstr *d@ = pointer to a dynamic string block
79 * Use: Initialises a dynamic string.
82 extern void dstr_create(dstr */*d*/);
84 /* --- @dstr_destroy@ --- *
86 * Arguments: @dstr *d@ = pointer to a dynamic string block
90 * Use: Reclaims the space used by a dynamic string.
93 extern void dstr_destroy(dstr */*d*/);
95 /* --- @dstr_reset@ --- *
97 * Arguments: @dstr *d@ = pointer to a dynaimc string block
101 * Use: Resets a string so that new data gets put at the beginning.
104 extern void dstr_reset(dstr */*d*/);
106 /* --- @dstr_ensure@ --- *
108 * Arguments: @dstr *d@ = pointer to a dynamic string block
109 * @size_t sz@ = amount of free space to ensure
113 * Use: Ensures that at least @sz@ bytes are available in the
117 extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
119 #define DENSURE(d, rq) do { \
120 if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq)); \
123 /* --- @dstr_putc@ --- *
125 * Arguments: @dstr *d@ = pointer to a dynamic string block
126 * @char ch@ = character to append
130 * Use: Appends a character to a string.
133 extern void dstr_putc(dstr */*d*/, char /*ch*/);
135 #define DPUTC(d, ch) do { \
137 (d)->buf[(d)->len++] = (ch); \
140 /* --- @dstr_putz@ --- *
142 * Arguments: @dstr *d@ = pointer to a dynamic string block
146 * Use: Appends a null byte to a string. The null byte does not
147 * contribute to the string's length, and will be overwritten
148 * by subsequent `put' operations.
151 extern void dstr_putz(dstr */*d*/);
153 #define DPUTZ(d) do { \
155 (d)->buf[(d)->len] = 0; \
158 /* --- @dstr_puts@ --- *
160 * Arguments: @dstr *d@ = pointer to a dynamic string block
161 * @const char *s@ = pointer to string to append
165 * Use: Appends a character string to a string. A trailing null
166 * byte is added, as for @dstr_putz@.
169 extern void dstr_puts(dstr */*d*/, const char */*s*/);
171 #define DPUTS(d, s) do { \
172 size_t sz = strlen(s); \
173 DENSURE((d), sz + 1); \
174 memcpy((d)->buf + (d)->len, (s), sz + 1); \
178 /* --- @dstr_vputf@ --- *
180 * Arguments: @dstr *d@ = pointer to a dynamic string block
181 * @const char *p@ = pointer to @printf@-style format string
182 * @va_list ap@ = argument handle
186 * Use: As for @dstr_putf@, but may be used as a back-end to user-
187 * supplied functions with @printf@-style interfaces.
190 extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list /*ap*/);
192 /* --- @dstr_putf@ --- *
194 * Arguments: @dstr *d@ = pointer to a dynamic string block
195 * @const char *p@ = pointer to @printf@-style format string
196 * @...@ = argument handle
200 * Use: Writes a piece of text to a dynamic string, doing @printf@-
201 * style substitutions as it goes. Intended to be robust if
202 * faced with malicious arguments, but not if the format string
203 * itself is malicious.
206 extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
208 /* --- @dstr_putd@ --- *
210 * Arguments: @dstr *d@ = pointer to a dynamic string block
211 * @const dstr *s@ = pointer to a dynamic string to append
215 * Use: Appends a dynamic string to a string. A trailing null
216 * byte is added, as for @dstr_putz@.
219 extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
221 #define DPUTD(d, s) do { \
222 DENSURE((d), (s)->len + 1); \
223 memcpy((d)->buf + (d)->len, (s)->buf, (s)->len); \
224 (d)->len += (s)->len; \
225 (d)->buf[(d)->len] = 0; \
228 /* --- @dstr_putm@ --- *
230 * Arguments: @dstr *d@ = pointer to a dynamic string block
231 * @const void *p@ = pointer to a block to append
232 * @size_t sz@ = size of the block
234 * Returns: Appends an arbitrary data block to a string. No trailing
238 extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
240 #define DPUTM(d, p, sz) do { \
241 DENSURE((d), (sz)); \
242 memcpy((d)->buf + (d)->len, (p), (sz)); \
246 /* --- @dstr_tidy@ --- *
248 * Arguments: @dstr *d@ = pointer to a dynamic string block
252 * Use: Reduces the amount of memory used by a string. A trailing
253 * null byte is added, as for @dstr_putz@.
256 extern void dstr_tidy(dstr */*d*/);
258 /* --- @dstr_putline@ --- *
260 * Arguments: @dstr *d@ = pointer to a dynamic string block
261 * @FILE *fp@ = a stream to read from
263 * Returns: The number of characters read into the buffer, or @EOF@ if
264 * end-of-file was reached before any characters were read.
266 * Use: Appends the next line from the given input stream to the
267 * string. A trailing newline is not added; a trailing null
268 * byte is appended, as for @dstr_putz@.
271 extern int dstr_putline(dstr */*d*/, FILE */*fp*/);
273 /* --- @dstr_write@ --- *
275 * Arguments: @dstr *d@ = pointer to a dynamic string block
276 * @FILE *fp@ = a stream to write on
278 * Returns: The number of bytes written (as for @fwrite@).
280 * Use: Writes a dynamic string to a file.
283 extern size_t dstr_write(dstr */*d*/, FILE */*fp*/);
285 /*----- That's all, folks -------------------------------------------------*/