~mdw / mLib / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
struct/dstr.[ch3] (dstr_putc): Accept an `int' argument.
[mLib] / struct / 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 * @int 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*/, int /*ch*/);
152
153 #define DPUTC(d, ch) do { \
154 dstr *_d = (d); \
155 DENSURE(_d, 1); \
156 *((unsigned char *)_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
mLib utilities library