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