3 * $Id: dstr.h,v 1.5 1999/05/13 22:47:57 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 Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (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 Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with mLib; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.5 1999/05/13 22:47:57 mdw
34 * Misc documentation fixes. Change `-ise' to `-ize' throughout.
36 * Revision 1.4 1999/05/06 19:51:35 mdw
37 * Reformatted the LGPL notice a little bit.
39 * Revision 1.3 1999/05/05 18:50:31 mdw
40 * Change licensing conditions to LGPL.
42 * Revision 1.2 1998/12/15 23:53:23 mdw
43 * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
44 * formatting in a safe way.
46 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
47 * Initial version of mLib
58 /*----- Rationale ---------------------------------------------------------*
60 * This file declares what is hopefully a fairly useful collection of
61 * primitive string handling functions. The idea is that the strings
62 * allocate memory for themselves as required. The @dstr@ routines don't
63 * assume any sort of terminator character, so arbitrary binary data can
64 * be stored in a dynamic string. With luck, this should put a stop to
65 * any buffer overflow problems.
68 /*----- Header files ------------------------------------------------------*/
73 /*----- Data structures ---------------------------------------------------*/
76 char *buf; /* Pointer to string buffer */
77 size_t sz; /* Size of the buffer */
78 size_t len; /* Length of the string */
81 /*----- Functions provided ------------------------------------------------*/
83 /* --- @dstr_create@ --- *
85 * Arguments: @dstr *d@ = pointer to a dynamic string block
89 * Use: Initializes a dynamic string.
92 extern void dstr_create(dstr */*d*/);
94 /* --- @dstr_destroy@ --- *
96 * Arguments: @dstr *d@ = pointer to a dynamic string block
100 * Use: Reclaims the space used by a dynamic string.
103 extern void dstr_destroy(dstr */*d*/);
105 /* --- @dstr_reset@ --- *
107 * Arguments: @dstr *d@ = pointer to a dynaimc string block
111 * Use: Resets a string so that new data gets put at the beginning.
114 extern void dstr_reset(dstr */*d*/);
116 /* --- @dstr_ensure@ --- *
118 * Arguments: @dstr *d@ = pointer to a dynamic string block
119 * @size_t sz@ = amount of free space to ensure
123 * Use: Ensures that at least @sz@ bytes are available in the
127 extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
129 #define DENSURE(d, rq) do { \
130 if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq)); \
133 /* --- @dstr_putc@ --- *
135 * Arguments: @dstr *d@ = pointer to a dynamic string block
136 * @char ch@ = character to append
140 * Use: Appends a character to a string.
143 extern void dstr_putc(dstr */*d*/, char /*ch*/);
145 #define DPUTC(d, ch) do { \
147 (d)->buf[(d)->len++] = (ch); \
150 /* --- @dstr_putz@ --- *
152 * Arguments: @dstr *d@ = pointer to a dynamic string block
156 * Use: Appends a null byte to a string. The null byte does not
157 * contribute to the string's length, and will be overwritten
158 * by subsequent `put' operations.
161 extern void dstr_putz(dstr */*d*/);
163 #define DPUTZ(d) do { \
165 (d)->buf[(d)->len] = 0; \
168 /* --- @dstr_puts@ --- *
170 * Arguments: @dstr *d@ = pointer to a dynamic string block
171 * @const char *s@ = pointer to string to append
175 * Use: Appends a character string to a string. A trailing null
176 * byte is added, as for @dstr_putz@.
179 extern void dstr_puts(dstr */*d*/, const char */*s*/);
181 #define DPUTS(d, s) do { \
182 size_t sz = strlen(s); \
183 DENSURE((d), sz + 1); \
184 memcpy((d)->buf + (d)->len, (s), sz + 1); \
188 /* --- @dstr_vputf@ --- *
190 * Arguments: @dstr *d@ = pointer to a dynamic string block
191 * @const char *p@ = pointer to @printf@-style format string
192 * @va_list ap@ = argument handle
194 * Returns: The number of characters written to the string.
196 * Use: As for @dstr_putf@, but may be used as a back-end to user-
197 * supplied functions with @printf@-style interfaces.
200 extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list /*ap*/);
202 /* --- @dstr_putf@ --- *
204 * Arguments: @dstr *d@ = pointer to a dynamic string block
205 * @const char *p@ = pointer to @printf@-style format string
206 * @...@ = argument handle
208 * Returns: The number of characters written to the string.
210 * Use: Writes a piece of text to a dynamic string, doing @printf@-
211 * style substitutions as it goes. Intended to be robust if
212 * faced with malicious arguments, but not if the format string
213 * itself is malicious.
216 extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
218 /* --- @dstr_putd@ --- *
220 * Arguments: @dstr *d@ = pointer to a dynamic string block
221 * @const dstr *s@ = pointer to a dynamic string to append
225 * Use: Appends a dynamic string to a string. A trailing null
226 * byte is added, as for @dstr_putz@.
229 extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
231 #define DPUTD(d, s) do { \
232 DENSURE((d), (s)->len + 1); \
233 memcpy((d)->buf + (d)->len, (s)->buf, (s)->len); \
234 (d)->len += (s)->len; \
235 (d)->buf[(d)->len] = 0; \
238 /* --- @dstr_putm@ --- *
240 * Arguments: @dstr *d@ = pointer to a dynamic string block
241 * @const void *p@ = pointer to a block to append
242 * @size_t sz@ = size of the block
244 * Returns: Appends an arbitrary data block to a string. No trailing
248 extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
250 #define DPUTM(d, p, sz) do { \
251 DENSURE((d), (sz)); \
252 memcpy((d)->buf + (d)->len, (p), (sz)); \
256 /* --- @dstr_tidy@ --- *
258 * Arguments: @dstr *d@ = pointer to a dynamic string block
262 * Use: Reduces the amount of memory used by a string. A trailing
263 * null byte is added, as for @dstr_putz@.
266 extern void dstr_tidy(dstr */*d*/);
268 /* --- @dstr_putline@ --- *
270 * Arguments: @dstr *d@ = pointer to a dynamic string block
271 * @FILE *fp@ = a stream to read from
273 * Returns: The number of characters read into the buffer, or @EOF@ if
274 * end-of-file was reached before any characters were read.
276 * Use: Appends the next line from the given input stream to the
277 * string. A trailing newline is not added; a trailing null
278 * byte is appended, as for @dstr_putz@.
281 extern int dstr_putline(dstr */*d*/, FILE */*fp*/);
283 /* --- @dstr_write@ --- *
285 * Arguments: @dstr *d@ = pointer to a dynamic string block
286 * @FILE *fp@ = a stream to write on
288 * Returns: The number of bytes written (as for @fwrite@).
290 * Use: Writes a dynamic string to a file.
293 extern size_t dstr_write(const dstr */*d*/, FILE */*fp*/);
295 /*----- That's all, folks -------------------------------------------------*/