chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / struct / dstr.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
0875b58f 3 * Handle dynamically growing strings
4 *
5 * (c) 1998 Straylight/Edgeware
6 */
7
d4efbcd9 8/*----- Licensing notice --------------------------------------------------*
0875b58f 9 *
10 * This file is part of the mLib utilities library.
11 *
12 * mLib is free software; you can redistribute it and/or modify
c846879c 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.
d4efbcd9 16 *
0875b58f 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
c846879c 20 * GNU Library General Public License for more details.
d4efbcd9 21 *
c846879c 22 * You should have received a copy of the GNU Library General Public
0bd98442 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.
0875b58f 26 */
27
c6e0eaf0 28#ifndef MLIB_DSTR_H
29#define MLIB_DSTR_H
0875b58f 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
00c7638b 47#include <stdarg.h>
0875b58f 48#include <stdio.h>
c44b6bde 49#include <stdlib.h>
0875b58f 50
20eb516f 51#ifndef MLIB_ALLOC_H
52# include "alloc.h"
53#endif
54
55#ifndef MLIB_ARENA_H
56# include "arena.h"
57#endif
58
0875b58f 59/*----- Data structures ---------------------------------------------------*/
60
61typedef 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 */
20eb516f 65 arena *a; /* Pointer to arena */
0875b58f 66} dstr;
67
20eb516f 68#define DSTR_INIT { 0, 0, 0, &arena_stdlib } /* How to initialize one */
c44b6bde 69
0875b58f 70/*----- Functions provided ------------------------------------------------*/
71
72/* --- @dstr_create@ --- *
73 *
74 * Arguments: @dstr *d@ = pointer to a dynamic string block
75 *
76 * Returns: ---
77 *
96c5fe33 78 * Use: Initializes a dynamic string.
0875b58f 79 */
80
81extern void dstr_create(dstr */*d*/);
82
c44b6bde 83#define DCREATE(d) do { \
077c6597 84 dstr *_dd = (d); \
85 _dd->buf = 0; \
86 _dd->sz = 0; \
87 _dd->len = 0; \
20eb516f 88 _dd->a = &arena_stdlib; \
c44b6bde 89} while (0)
90
0875b58f 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
100extern void dstr_destroy(dstr */*d*/);
101
c44b6bde 102#define DDESTROY(d) do { \
077c6597 103 dstr *_d = (d); \
104 if (_d->buf) \
20eb516f 105 x_free(_d->a, _d->buf); \
077c6597 106 DCREATE(_d); \
c44b6bde 107} while (0)
108
0875b58f 109/* --- @dstr_reset@ --- *
110 *
c6e0eaf0 111 * Arguments: @dstr *d@ = pointer to a dynamic string block
0875b58f 112 *
113 * Returns: ---
114 *
115 * Use: Resets a string so that new data gets put at the beginning.
116 */
117
118extern void dstr_reset(dstr */*d*/);
119
bd3d316a 120#define DRESET(d) ((d)->len = 0)
c44b6bde 121
0875b58f 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
133extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
134
135#define DENSURE(d, rq) do { \
077c6597 136 dstr *_dd = (d); \
137 size_t _rq = (rq); \
138 if (_dd->len + _rq > _dd->sz) dstr_ensure(_dd, _rq); \
0875b58f 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
151extern void dstr_putc(dstr */*d*/, char /*ch*/);
152
153#define DPUTC(d, ch) do { \
077c6597 154 dstr *_d = (d); \
155 DENSURE(_d, 1); \
156 _d->buf[_d->len++] = (ch); \
0875b58f 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
170extern void dstr_putz(dstr */*d*/);
171
172#define DPUTZ(d) do { \
077c6597 173 dstr *_d = (d); \
174 DENSURE(_d, 1); \
175 _d->buf[_d->len] = 0; \
0875b58f 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
189extern void dstr_puts(dstr */*d*/, const char */*s*/);
190
191#define DPUTS(d, s) do { \
077c6597 192 dstr *_d = (d); \
193 const char *_s = (s); \
c53c8c86 194 size_t _sz = strlen(_s); \
077c6597 195 DENSURE(_d, _sz + 1); \
196 memcpy(_d->buf + _d->len, _s, _sz + 1); \
197 _d->len += _sz; \
0875b58f 198} while (0)
199
00c7638b 200/* --- @dstr_vputf@ --- *
201 *
202 * Arguments: @dstr *d@ = pointer to a dynamic string block
203 * @const char *p@ = pointer to @printf@-style format string
5a18a126 204 * @va_list *ap@ = argument handle
00c7638b 205 *
96c5fe33 206 * Returns: The number of characters written to the string.
00c7638b 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
5a18a126 212extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list */*ap*/);
00c7638b 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 *
96c5fe33 220 * Returns: The number of characters written to the string.
00c7638b 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
228extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
229
0875b58f 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
241extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
242
243#define DPUTD(d, s) do { \
077c6597 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; \
0875b58f 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
262extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
263
264#define DPUTM(d, p, sz) do { \
077c6597 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; \
0875b58f 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
282extern 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
297extern 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
96c5fe33 309extern size_t dstr_write(const dstr */*d*/, FILE */*fp*/);
0875b58f 310
c44b6bde 311#define DWRITE(d, fp) fwrite((d)->buf, 1, (d)->len, (fp))
312
0875b58f 313/*----- That's all, folks -------------------------------------------------*/
314
315#ifdef __cplusplus
316 }
317#endif
318
319#endif