chiark / gitweb /
Test universal hashing and fix bugs.
[mLib] / dstr.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
5a18a126 3 * $Id: dstr.h,v 1.12 2002/01/13 13:30:48 mdw Exp $
0875b58f 4 *
5 * Handle dynamically growing strings
6 *
7 * (c) 1998 Straylight/Edgeware
8 */
9
c846879c 10/*----- Licensing notice --------------------------------------------------*
0875b58f 11 *
12 * This file is part of the mLib utilities library.
13 *
14 * mLib is free software; you can redistribute it and/or modify
c846879c 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 *
0875b58f 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
c846879c 22 * GNU Library General Public License for more details.
23 *
24 * You should have received a copy of the GNU Library General Public
0bd98442 25 * License along with mLib; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
27 * MA 02111-1307, USA.
0875b58f 28 */
29
30/*----- Revision history --------------------------------------------------*
31 *
32 * $Log: dstr.h,v $
5a18a126 33 * Revision 1.12 2002/01/13 13:30:48 mdw
34 * Change interface for @dstr_vputf@.
35 *
20eb516f 36 * Revision 1.11 2000/06/17 10:37:39 mdw
37 * Add support for arena management.
38 *
c53c8c86 39 * Revision 1.10 1999/12/22 15:39:51 mdw
40 * Fix argument reuse in DPUTS.
41 *
c6e0eaf0 42 * Revision 1.9 1999/12/10 23:42:04 mdw
43 * Change header file guard names.
44 *
077c6597 45 * Revision 1.8 1999/07/14 19:45:24 mdw
46 * Prevent some macros from re-evaluating their arguments.
47 *
bd3d316a 48 * Revision 1.7 1999/05/21 22:12:12 mdw
49 * Fix the bugs in the new macros. (Whoops.)
50 *
c44b6bde 51 * Revision 1.6 1999/05/21 08:38:14 mdw
52 * Add some more macros, particularly for creation and destruction.
53 *
96c5fe33 54 * Revision 1.5 1999/05/13 22:47:57 mdw
55 * Misc documentation fixes. Change `-ise' to `-ize' throughout.
56 *
0bd98442 57 * Revision 1.4 1999/05/06 19:51:35 mdw
58 * Reformatted the LGPL notice a little bit.
59 *
c846879c 60 * Revision 1.3 1999/05/05 18:50:31 mdw
61 * Change licensing conditions to LGPL.
62 *
00c7638b 63 * Revision 1.2 1998/12/15 23:53:23 mdw
64 * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
65 * formatting in a safe way.
66 *
67 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
68 * Initial version of mLib
0875b58f 69 *
70 */
71
c6e0eaf0 72#ifndef MLIB_DSTR_H
73#define MLIB_DSTR_H
0875b58f 74
75#ifdef __cplusplus
76 extern "C" {
77#endif
78
79/*----- Rationale ---------------------------------------------------------*
80 *
81 * This file declares what is hopefully a fairly useful collection of
82 * primitive string handling functions. The idea is that the strings
83 * allocate memory for themselves as required. The @dstr@ routines don't
84 * assume any sort of terminator character, so arbitrary binary data can
85 * be stored in a dynamic string. With luck, this should put a stop to
86 * any buffer overflow problems.
87 */
88
89/*----- Header files ------------------------------------------------------*/
90
00c7638b 91#include <stdarg.h>
0875b58f 92#include <stdio.h>
c44b6bde 93#include <stdlib.h>
0875b58f 94
20eb516f 95#ifndef MLIB_ALLOC_H
96# include "alloc.h"
97#endif
98
99#ifndef MLIB_ARENA_H
100# include "arena.h"
101#endif
102
0875b58f 103/*----- Data structures ---------------------------------------------------*/
104
105typedef struct dstr {
106 char *buf; /* Pointer to string buffer */
107 size_t sz; /* Size of the buffer */
108 size_t len; /* Length of the string */
20eb516f 109 arena *a; /* Pointer to arena */
0875b58f 110} dstr;
111
20eb516f 112#define DSTR_INIT { 0, 0, 0, &arena_stdlib } /* How to initialize one */
c44b6bde 113
0875b58f 114/*----- Functions provided ------------------------------------------------*/
115
116/* --- @dstr_create@ --- *
117 *
118 * Arguments: @dstr *d@ = pointer to a dynamic string block
119 *
120 * Returns: ---
121 *
96c5fe33 122 * Use: Initializes a dynamic string.
0875b58f 123 */
124
125extern void dstr_create(dstr */*d*/);
126
c44b6bde 127#define DCREATE(d) do { \
077c6597 128 dstr *_dd = (d); \
129 _dd->buf = 0; \
130 _dd->sz = 0; \
131 _dd->len = 0; \
20eb516f 132 _dd->a = &arena_stdlib; \
c44b6bde 133} while (0)
134
0875b58f 135/* --- @dstr_destroy@ --- *
136 *
137 * Arguments: @dstr *d@ = pointer to a dynamic string block
138 *
139 * Returns: ---
140 *
141 * Use: Reclaims the space used by a dynamic string.
142 */
143
144extern void dstr_destroy(dstr */*d*/);
145
c44b6bde 146#define DDESTROY(d) do { \
077c6597 147 dstr *_d = (d); \
148 if (_d->buf) \
20eb516f 149 x_free(_d->a, _d->buf); \
077c6597 150 DCREATE(_d); \
c44b6bde 151} while (0)
152
0875b58f 153/* --- @dstr_reset@ --- *
154 *
c6e0eaf0 155 * Arguments: @dstr *d@ = pointer to a dynamic string block
0875b58f 156 *
157 * Returns: ---
158 *
159 * Use: Resets a string so that new data gets put at the beginning.
160 */
161
162extern void dstr_reset(dstr */*d*/);
163
bd3d316a 164#define DRESET(d) ((d)->len = 0)
c44b6bde 165
0875b58f 166/* --- @dstr_ensure@ --- *
167 *
168 * Arguments: @dstr *d@ = pointer to a dynamic string block
169 * @size_t sz@ = amount of free space to ensure
170 *
171 * Returns: ---
172 *
173 * Use: Ensures that at least @sz@ bytes are available in the
174 * given string.
175 */
176
177extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
178
179#define DENSURE(d, rq) do { \
077c6597 180 dstr *_dd = (d); \
181 size_t _rq = (rq); \
182 if (_dd->len + _rq > _dd->sz) dstr_ensure(_dd, _rq); \
0875b58f 183} while (0)
184
185/* --- @dstr_putc@ --- *
186 *
187 * Arguments: @dstr *d@ = pointer to a dynamic string block
188 * @char ch@ = character to append
189 *
190 * Returns: ---
191 *
192 * Use: Appends a character to a string.
193 */
194
195extern void dstr_putc(dstr */*d*/, char /*ch*/);
196
197#define DPUTC(d, ch) do { \
077c6597 198 dstr *_d = (d); \
199 DENSURE(_d, 1); \
200 _d->buf[_d->len++] = (ch); \
0875b58f 201} while (0)
202
203/* --- @dstr_putz@ --- *
204 *
205 * Arguments: @dstr *d@ = pointer to a dynamic string block
206 *
207 * Returns: ---
208 *
209 * Use: Appends a null byte to a string. The null byte does not
210 * contribute to the string's length, and will be overwritten
211 * by subsequent `put' operations.
212 */
213
214extern void dstr_putz(dstr */*d*/);
215
216#define DPUTZ(d) do { \
077c6597 217 dstr *_d = (d); \
218 DENSURE(_d, 1); \
219 _d->buf[_d->len] = 0; \
0875b58f 220} while (0)
221
222/* --- @dstr_puts@ --- *
223 *
224 * Arguments: @dstr *d@ = pointer to a dynamic string block
225 * @const char *s@ = pointer to string to append
226 *
227 * Returns: ---
228 *
229 * Use: Appends a character string to a string. A trailing null
230 * byte is added, as for @dstr_putz@.
231 */
232
233extern void dstr_puts(dstr */*d*/, const char */*s*/);
234
235#define DPUTS(d, s) do { \
077c6597 236 dstr *_d = (d); \
237 const char *_s = (s); \
c53c8c86 238 size_t _sz = strlen(_s); \
077c6597 239 DENSURE(_d, _sz + 1); \
240 memcpy(_d->buf + _d->len, _s, _sz + 1); \
241 _d->len += _sz; \
0875b58f 242} while (0)
243
00c7638b 244/* --- @dstr_vputf@ --- *
245 *
246 * Arguments: @dstr *d@ = pointer to a dynamic string block
247 * @const char *p@ = pointer to @printf@-style format string
5a18a126 248 * @va_list *ap@ = argument handle
00c7638b 249 *
96c5fe33 250 * Returns: The number of characters written to the string.
00c7638b 251 *
252 * Use: As for @dstr_putf@, but may be used as a back-end to user-
253 * supplied functions with @printf@-style interfaces.
254 */
255
5a18a126 256extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list */*ap*/);
00c7638b 257
258/* --- @dstr_putf@ --- *
259 *
260 * Arguments: @dstr *d@ = pointer to a dynamic string block
261 * @const char *p@ = pointer to @printf@-style format string
262 * @...@ = argument handle
263 *
96c5fe33 264 * Returns: The number of characters written to the string.
00c7638b 265 *
266 * Use: Writes a piece of text to a dynamic string, doing @printf@-
267 * style substitutions as it goes. Intended to be robust if
268 * faced with malicious arguments, but not if the format string
269 * itself is malicious.
270 */
271
272extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
273
0875b58f 274/* --- @dstr_putd@ --- *
275 *
276 * Arguments: @dstr *d@ = pointer to a dynamic string block
277 * @const dstr *s@ = pointer to a dynamic string to append
278 *
279 * Returns: ---
280 *
281 * Use: Appends a dynamic string to a string. A trailing null
282 * byte is added, as for @dstr_putz@.
283 */
284
285extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
286
287#define DPUTD(d, s) do { \
077c6597 288 dstr *_d = (d); \
289 const dstr *_s = (s); \
290 DENSURE(_d, _s->len + 1); \
291 memcpy(_d->buf + _d->len, _s->buf, _s->len); \
292 _d->len += _s->len; \
293 _d->buf[_d->len] = 0; \
0875b58f 294} while (0)
295
296/* --- @dstr_putm@ --- *
297 *
298 * Arguments: @dstr *d@ = pointer to a dynamic string block
299 * @const void *p@ = pointer to a block to append
300 * @size_t sz@ = size of the block
301 *
302 * Returns: Appends an arbitrary data block to a string. No trailing
303 * null is appended.
304 */
305
306extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
307
308#define DPUTM(d, p, sz) do { \
077c6597 309 dstr *_d = (d); \
310 size_t _sz = (sz); \
311 DENSURE(_d, _sz); \
312 memcpy(_d->buf + _d->len, (p), _sz); \
313 _d->len += _sz; \
0875b58f 314} while (0)
315
316/* --- @dstr_tidy@ --- *
317 *
318 * Arguments: @dstr *d@ = pointer to a dynamic string block
319 *
320 * Returns: ---
321 *
322 * Use: Reduces the amount of memory used by a string. A trailing
323 * null byte is added, as for @dstr_putz@.
324 */
325
326extern void dstr_tidy(dstr */*d*/);
327
328/* --- @dstr_putline@ --- *
329 *
330 * Arguments: @dstr *d@ = pointer to a dynamic string block
331 * @FILE *fp@ = a stream to read from
332 *
333 * Returns: The number of characters read into the buffer, or @EOF@ if
334 * end-of-file was reached before any characters were read.
335 *
336 * Use: Appends the next line from the given input stream to the
337 * string. A trailing newline is not added; a trailing null
338 * byte is appended, as for @dstr_putz@.
339 */
340
341extern int dstr_putline(dstr */*d*/, FILE */*fp*/);
342
343/* --- @dstr_write@ --- *
344 *
345 * Arguments: @dstr *d@ = pointer to a dynamic string block
346 * @FILE *fp@ = a stream to write on
347 *
348 * Returns: The number of bytes written (as for @fwrite@).
349 *
350 * Use: Writes a dynamic string to a file.
351 */
352
96c5fe33 353extern size_t dstr_write(const dstr */*d*/, FILE */*fp*/);
0875b58f 354
c44b6bde 355#define DWRITE(d, fp) fwrite((d)->buf, 1, (d)->len, (fp))
356
0875b58f 357/*----- That's all, folks -------------------------------------------------*/
358
359#ifdef __cplusplus
360 }
361#endif
362
363#endif