3 * Handle dynamically growing strings
5 * (c) 1998 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the mLib utilities library.
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.
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.
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,
35 /*----- Rationale ---------------------------------------------------------*
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.
45 /*----- Header files ------------------------------------------------------*/
63 /*----- Data structures ---------------------------------------------------*/
66 char *buf
; /* Pointer to string buffer */
67 size_t sz
; /* Size of the buffer */
68 size_t len
; /* Length of the string */
69 arena
*a
; /* Pointer to arena */
72 #define DSTR_INIT { 0, 0, 0, &arena_stdlib } /* How to initialize one */
74 /*----- Functions provided ------------------------------------------------*/
76 /* --- @dstr_create@ --- *
78 * Arguments: @dstr *d@ = pointer to a dynamic string block
82 * Use: Initializes a dynamic string.
85 extern void dstr_create(dstr */
*d*/
);
87 #define DCREATE(d) do { \
92 _dd->a = &arena_stdlib; \
95 /* --- @dstr_destroy@ --- *
97 * Arguments: @dstr *d@ = pointer to a dynamic string block
101 * Use: Reclaims the space used by a dynamic string.
104 extern void dstr_destroy(dstr */
*d*/
);
106 #define DDESTROY(d) do { \
109 x_free(_d->a, _d->buf); \
113 /* --- @dstr_reset@ --- *
115 * Arguments: @dstr *d@ = pointer to a dynamic string block
119 * Use: Resets a string so that new data gets put at the beginning.
122 extern void dstr_reset(dstr */
*d*/
);
124 #define DRESET(d) ((d)->len = 0)
126 /* --- @dstr_ensure@ --- *
128 * Arguments: @dstr *d@ = pointer to a dynamic string block
129 * @size_t sz@ = amount of free space to ensure
133 * Use: Ensures that at least @sz@ bytes are available in the
137 extern void dstr_ensure(dstr */
*d*/
, size_t /*sz*/);
139 #define DENSURE(d, rq) do { \
142 if (_dd->len + _rq > _dd->sz) dstr_ensure(_dd, _rq); \
145 /* --- @dstr_putc@ --- *
147 * Arguments: @dstr *d@ = pointer to a dynamic string block
148 * @int ch@ = character to append
152 * Use: Appends a character to a string.
155 extern void dstr_putc(dstr */
*d*/
, int /*ch*/);
157 #define DPUTC(d, ch) do { \
160 *((unsigned char *)_d->buf + _d->len++) = (ch); \
163 /* --- @dstr_putz@ --- *
165 * Arguments: @dstr *d@ = pointer to a dynamic string block
169 * Use: Appends a null byte to a string. The null byte does not
170 * contribute to the string's length, and will be overwritten
171 * by subsequent `put' operations.
174 extern void dstr_putz(dstr */
*d*/
);
176 #define DPUTZ(d) do { \
179 _d->buf[_d->len] = 0; \
182 /* --- @dstr_puts@ --- *
184 * Arguments: @dstr *d@ = pointer to a dynamic string block
185 * @const char *s@ = pointer to string to append
189 * Use: Appends a character string to a string. A trailing null
190 * byte is added, as for @dstr_putz@.
193 extern void dstr_puts(dstr */
*d*/
, const char */
*s*/
);
195 #define DPUTS(d, s) do { \
197 const char *_s = (s); \
198 size_t _sz = strlen(_s); \
199 DENSURE(_d, _sz + 1); \
200 memcpy(_d->buf + _d->len, _s, _sz + 1); \
204 /* --- @dstr_vputf@ --- *
206 * Arguments: @dstr *d@ = pointer to a dynamic string block
207 * @const char *p@ = pointer to @printf@-style format string
208 * @va_list *ap@ = argument handle
210 * Returns: The number of characters written to the string.
212 * Use: As for @dstr_putf@, but may be used as a back-end to user-
213 * supplied functions with @printf@-style interfaces.
216 extern int dstr_vputf(dstr */
*d*/
, const char */
*p*/
, va_list */
*ap*/
);
218 /* --- @dstr_putf@ --- *
220 * Arguments: @dstr *d@ = pointer to a dynamic string block
221 * @const char *p@ = pointer to @printf@-style format string
222 * @...@ = argument handle
224 * Returns: The number of characters written to the string.
226 * Use: Writes a piece of text to a dynamic string, doing @printf@-
227 * style substitutions as it goes. Intended to be robust if
228 * faced with malicious arguments, but not if the format string
229 * itself is malicious.
232 extern int PRINTF_LIKE(2, 3)
233 dstr_putf(dstr */
*d*/
, const char */
*p*/
, ...);
235 /* --- @dstr_putd@ --- *
237 * Arguments: @dstr *d@ = pointer to a dynamic string block
238 * @const dstr *s@ = pointer to a dynamic string to append
242 * Use: Appends a dynamic string to a string. A trailing null
243 * byte is added, as for @dstr_putz@.
246 extern void dstr_putd(dstr */
*d*/
, const dstr */
*s*/
);
248 #define DPUTD(d, s) do { \
250 const dstr *_s = (s); \
251 DENSURE(_d, _s->len + 1); \
252 memcpy(_d->buf + _d->len, _s->buf, _s->len); \
253 _d->len += _s->len; \
254 _d->buf[_d->len] = 0; \
257 /* --- @dstr_putm@ --- *
259 * Arguments: @dstr *d@ = pointer to a dynamic string block
260 * @const void *p@ = pointer to a block to append
261 * @size_t sz@ = size of the block
263 * Returns: Appends an arbitrary data block to a string. No trailing
267 extern void dstr_putm(dstr */
*d*/
, const void */
*p*/
, size_t /*sz*/);
269 #define DPUTM(d, p, sz) do { \
273 memcpy(_d->buf + _d->len, (p), _sz); \
277 /* --- @dstr_tidy@ --- *
279 * Arguments: @dstr *d@ = pointer to a dynamic string block
283 * Use: Reduces the amount of memory used by a string. A trailing
284 * null byte is added, as for @dstr_putz@.
287 extern void dstr_tidy(dstr */
*d*/
);
289 /* --- @dstr_putline@ --- *
291 * Arguments: @dstr *d@ = pointer to a dynamic string block
292 * @FILE *fp@ = a stream to read from
294 * Returns: The number of characters read into the buffer, or @EOF@ if
295 * end-of-file was reached before any characters were read.
297 * Use: Appends the next line from the given input stream to the
298 * string. A trailing newline is not added; a trailing null
299 * byte is appended, as for @dstr_putz@.
302 extern int dstr_putline(dstr */
*d*/
, FILE */
*fp*/
);
304 /* --- @dstr_write@ --- *
306 * Arguments: @dstr *d@ = pointer to a dynamic string block
307 * @FILE *fp@ = a stream to write on
309 * Returns: The number of bytes written (as for @fwrite@).
311 * Use: Writes a dynamic string to a file.
314 extern size_t dstr_write(const dstr */
*d*/
, FILE */
*fp*/
);
316 #define DWRITE(d, fp) fwrite((d)->buf, 1, (d)->len, (fp))
318 /*----- That's all, folks -------------------------------------------------*/