chiark / gitweb /
Change licensing conditions to LGPL.
[mLib] / dstr.h
1 /* -*-c-*-
2  *
3  * $Id: dstr.h,v 1.3 1999/05/05 18:50:31 mdw Exp $
4  *
5  * Handle dynamically growing strings
6  *
7  * (c) 1998 Straylight/Edgeware
8  */
9
10 /*----- Licensing notice --------------------------------------------------* 
11  *
12  * This file is part of the mLib utilities library.
13  *
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.
18  * 
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.
23  * 
24  * You should have received a copy of the GNU Library General Public
25  * License along with mLib; if not, write to the Free Software
26  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
27  */
28
29 /*----- Revision history --------------------------------------------------*
30  *
31  * $Log: dstr.h,v $
32  * Revision 1.3  1999/05/05 18:50:31  mdw
33  * Change licensing conditions to LGPL.
34  *
35  * Revision 1.2  1998/12/15 23:53:23  mdw
36  * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
37  * formatting in a safe way.
38  *
39  * Revision 1.1.1.1  1998/06/17 23:44:42  mdw
40  * Initial version of mLib
41  *
42  */
43
44 #ifndef DSTR_H
45 #define DSTR_H
46
47 #ifdef __cplusplus
48   extern "C" {
49 #endif
50
51 /*----- Rationale ---------------------------------------------------------*
52  *
53  * This file declares what is hopefully a fairly useful collection of
54  * primitive string handling functions.  The idea is that the strings
55  * allocate memory for themselves as required.  The @dstr@ routines don't
56  * assume any sort of terminator character, so arbitrary binary data can
57  * be stored in a dynamic string.  With luck, this should put a stop to
58  * any buffer overflow problems.
59  */
60
61 /*----- Header files ------------------------------------------------------*/
62
63 #include <stdarg.h>
64 #include <stdio.h>
65
66 /*----- Data structures ---------------------------------------------------*/
67
68 typedef struct dstr {
69   char *buf;                            /* Pointer to string buffer */
70   size_t sz;                            /* Size of the buffer */
71   size_t len;                           /* Length of the string */
72 } dstr;
73
74 /*----- Functions provided ------------------------------------------------*/
75
76 /* --- @dstr_create@ --- *
77  *
78  * Arguments:   @dstr *d@ = pointer to a dynamic string block
79  *
80  * Returns:     ---
81  *
82  * Use:         Initialises a dynamic string.
83  */
84
85 extern void dstr_create(dstr */*d*/);
86
87 /* --- @dstr_destroy@ --- *
88  *
89  * Arguments:   @dstr *d@ = pointer to a dynamic string block
90  *
91  * Returns:     ---
92  *
93  * Use:         Reclaims the space used by a dynamic string.
94  */
95
96 extern void dstr_destroy(dstr */*d*/);
97
98 /* --- @dstr_reset@ --- *
99  *
100  * Arguments:   @dstr *d@ = pointer to a dynaimc string block
101  *
102  * Returns:     ---
103  *
104  * Use:         Resets a string so that new data gets put at the beginning.
105  */
106
107 extern void dstr_reset(dstr */*d*/);
108
109 /* --- @dstr_ensure@ --- *
110  *
111  * Arguments:   @dstr *d@ = pointer to a dynamic string block
112  *              @size_t sz@ = amount of free space to ensure
113  *
114  * Returns:     ---
115  *
116  * Use:         Ensures that at least @sz@ bytes are available in the
117  *              given string.
118  */
119
120 extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
121
122 #define DENSURE(d, rq) do {                                             \
123   if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq));                \
124 } while (0)
125
126 /* --- @dstr_putc@ --- *
127  *
128  * Arguments:   @dstr *d@ = pointer to a dynamic string block
129  *              @char ch@ = character to append
130  *
131  * Returns:     ---
132  *
133  * Use:         Appends a character to a string.
134  */
135
136 extern void dstr_putc(dstr */*d*/, char /*ch*/);
137
138 #define DPUTC(d, ch) do {                                               \
139   DENSURE((d), 1);                                                      \
140   (d)->buf[(d)->len++] = (ch);                                          \
141 } while (0)
142
143 /* --- @dstr_putz@ --- *
144  *
145  * Arguments:   @dstr *d@ = pointer to a dynamic string block
146  *
147  * Returns:     ---
148  *
149  * Use:         Appends a null byte to a string.  The null byte does not
150  *              contribute to the string's length, and will be overwritten
151  *              by subsequent `put' operations.
152  */
153
154 extern void dstr_putz(dstr */*d*/);
155
156 #define DPUTZ(d) do {                                                   \
157   DENSURE((d), 1);                                                      \
158   (d)->buf[(d)->len] = 0;                                               \
159 } while (0)
160
161 /* --- @dstr_puts@ --- *
162  *
163  * Arguments:   @dstr *d@ = pointer to a dynamic string block
164  *              @const char *s@ = pointer to string to append
165  *
166  * Returns:     ---
167  *
168  * Use:         Appends a character string to a string.  A trailing null
169  *              byte is added, as for @dstr_putz@.
170  */
171
172 extern void dstr_puts(dstr */*d*/, const char */*s*/);
173
174 #define DPUTS(d, s) do {                                                \
175   size_t sz = strlen(s);                                                \
176   DENSURE((d), sz + 1);                                                 \
177   memcpy((d)->buf + (d)->len, (s), sz + 1);                             \
178   (d)->len += sz;                                                       \
179 } while (0)
180
181 /* --- @dstr_vputf@ --- *
182  *
183  * Arguments:   @dstr *d@ = pointer to a dynamic string block
184  *              @const char *p@ = pointer to @printf@-style format string
185  *              @va_list ap@ = argument handle
186  *
187  * Returns:     ---
188  *
189  * Use:         As for @dstr_putf@, but may be used as a back-end to user-
190  *              supplied functions with @printf@-style interfaces.
191  */
192
193 extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list /*ap*/);
194
195 /* --- @dstr_putf@ --- *
196  *
197  * Arguments:   @dstr *d@ = pointer to a dynamic string block
198  *              @const char *p@ = pointer to @printf@-style format string
199  *              @...@ = argument handle
200  *
201  * Returns:     ---
202  *
203  * Use:         Writes a piece of text to a dynamic string, doing @printf@-
204  *              style substitutions as it goes.  Intended to be robust if
205  *              faced with malicious arguments, but not if the format string
206  *              itself is malicious.
207  */
208
209 extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
210
211 /* --- @dstr_putd@ --- *
212  *
213  * Arguments:   @dstr *d@ = pointer to a dynamic string block
214  *              @const dstr *s@ = pointer to a dynamic string to append
215  *
216  * Returns:     ---
217  *
218  * Use:         Appends a dynamic string to a string.  A trailing null
219  *              byte is added, as for @dstr_putz@.
220  */
221
222 extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
223
224 #define DPUTD(d, s) do {                                                \
225   DENSURE((d), (s)->len + 1);                                           \
226   memcpy((d)->buf + (d)->len, (s)->buf, (s)->len);                      \
227   (d)->len += (s)->len;                                                 \
228   (d)->buf[(d)->len] = 0;                                               \
229 } while (0)
230
231 /* --- @dstr_putm@ --- *
232  *
233  * Arguments:   @dstr *d@ = pointer to a dynamic string block
234  *              @const void *p@ = pointer to a block to append
235  *              @size_t sz@ = size of the block
236  *
237  * Returns:     Appends an arbitrary data block to a string.  No trailing
238  *              null is appended.
239  */
240
241 extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
242
243 #define DPUTM(d, p, sz) do {                                            \
244   DENSURE((d), (sz));                                                   \
245   memcpy((d)->buf + (d)->len, (p), (sz));                               \
246   (d)->len += (sz);                                                     \
247 } while (0)
248
249 /* --- @dstr_tidy@ --- *
250  *
251  * Arguments:   @dstr *d@ = pointer to a dynamic string block
252  *
253  * Returns:     ---
254  *
255  * Use:         Reduces the amount of memory used by a string.  A trailing
256  *              null byte is added, as for @dstr_putz@.
257  */
258
259 extern void dstr_tidy(dstr */*d*/);
260
261 /* --- @dstr_putline@ --- *
262  *
263  * Arguments:   @dstr *d@ = pointer to a dynamic string block
264  *              @FILE *fp@ = a stream to read from
265  *
266  * Returns:     The number of characters read into the buffer, or @EOF@ if
267  *              end-of-file was reached before any characters were read.
268  *
269  * Use:         Appends the next line from the given input stream to the
270  *              string.  A trailing newline is not added; a trailing null
271  *              byte is appended, as for @dstr_putz@.
272  */
273
274 extern int dstr_putline(dstr */*d*/, FILE */*fp*/);
275
276 /* --- @dstr_write@ --- *
277  *
278  * Arguments:   @dstr *d@ = pointer to a dynamic string block
279  *              @FILE *fp@ = a stream to write on
280  *
281  * Returns:     The number of bytes written (as for @fwrite@).
282  *
283  * Use:         Writes a dynamic string to a file.
284  */
285
286 extern size_t dstr_write(dstr */*d*/, FILE */*fp*/);
287
288 /*----- That's all, folks -------------------------------------------------*/
289
290 #ifdef __cplusplus
291   }
292 #endif
293
294 #endif