chiark / gitweb /
Reformatted the LGPL notice a little bit.
[mLib] / dstr.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
0bd98442 3 * $Id: dstr.h,v 1.4 1999/05/06 19:51:35 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 $
0bd98442 33 * Revision 1.4 1999/05/06 19:51:35 mdw
34 * Reformatted the LGPL notice a little bit.
35 *
c846879c 36 * Revision 1.3 1999/05/05 18:50:31 mdw
37 * Change licensing conditions to LGPL.
38 *
00c7638b 39 * Revision 1.2 1998/12/15 23:53:23 mdw
40 * New functions `dstr_putf' and `dstr_vputf' which do `printf'-style
41 * formatting in a safe way.
42 *
43 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
44 * Initial version of mLib
0875b58f 45 *
46 */
47
48#ifndef DSTR_H
49#define DSTR_H
50
51#ifdef __cplusplus
52 extern "C" {
53#endif
54
55/*----- Rationale ---------------------------------------------------------*
56 *
57 * This file declares what is hopefully a fairly useful collection of
58 * primitive string handling functions. The idea is that the strings
59 * allocate memory for themselves as required. The @dstr@ routines don't
60 * assume any sort of terminator character, so arbitrary binary data can
61 * be stored in a dynamic string. With luck, this should put a stop to
62 * any buffer overflow problems.
63 */
64
65/*----- Header files ------------------------------------------------------*/
66
00c7638b 67#include <stdarg.h>
0875b58f 68#include <stdio.h>
69
70/*----- Data structures ---------------------------------------------------*/
71
72typedef struct dstr {
73 char *buf; /* Pointer to string buffer */
74 size_t sz; /* Size of the buffer */
75 size_t len; /* Length of the string */
76} dstr;
77
78/*----- Functions provided ------------------------------------------------*/
79
80/* --- @dstr_create@ --- *
81 *
82 * Arguments: @dstr *d@ = pointer to a dynamic string block
83 *
84 * Returns: ---
85 *
86 * Use: Initialises a dynamic string.
87 */
88
89extern void dstr_create(dstr */*d*/);
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
100extern void dstr_destroy(dstr */*d*/);
101
102/* --- @dstr_reset@ --- *
103 *
104 * Arguments: @dstr *d@ = pointer to a dynaimc string block
105 *
106 * Returns: ---
107 *
108 * Use: Resets a string so that new data gets put at the beginning.
109 */
110
111extern void dstr_reset(dstr */*d*/);
112
113/* --- @dstr_ensure@ --- *
114 *
115 * Arguments: @dstr *d@ = pointer to a dynamic string block
116 * @size_t sz@ = amount of free space to ensure
117 *
118 * Returns: ---
119 *
120 * Use: Ensures that at least @sz@ bytes are available in the
121 * given string.
122 */
123
124extern void dstr_ensure(dstr */*d*/, size_t /*sz*/);
125
126#define DENSURE(d, rq) do { \
127 if ((d)->len + (rq) > (d)->sz) dstr_ensure((d), (rq)); \
128} while (0)
129
130/* --- @dstr_putc@ --- *
131 *
132 * Arguments: @dstr *d@ = pointer to a dynamic string block
133 * @char ch@ = character to append
134 *
135 * Returns: ---
136 *
137 * Use: Appends a character to a string.
138 */
139
140extern void dstr_putc(dstr */*d*/, char /*ch*/);
141
142#define DPUTC(d, ch) do { \
143 DENSURE((d), 1); \
144 (d)->buf[(d)->len++] = (ch); \
145} while (0)
146
147/* --- @dstr_putz@ --- *
148 *
149 * Arguments: @dstr *d@ = pointer to a dynamic string block
150 *
151 * Returns: ---
152 *
153 * Use: Appends a null byte to a string. The null byte does not
154 * contribute to the string's length, and will be overwritten
155 * by subsequent `put' operations.
156 */
157
158extern void dstr_putz(dstr */*d*/);
159
160#define DPUTZ(d) do { \
161 DENSURE((d), 1); \
162 (d)->buf[(d)->len] = 0; \
163} while (0)
164
165/* --- @dstr_puts@ --- *
166 *
167 * Arguments: @dstr *d@ = pointer to a dynamic string block
168 * @const char *s@ = pointer to string to append
169 *
170 * Returns: ---
171 *
172 * Use: Appends a character string to a string. A trailing null
173 * byte is added, as for @dstr_putz@.
174 */
175
176extern void dstr_puts(dstr */*d*/, const char */*s*/);
177
178#define DPUTS(d, s) do { \
179 size_t sz = strlen(s); \
180 DENSURE((d), sz + 1); \
181 memcpy((d)->buf + (d)->len, (s), sz + 1); \
182 (d)->len += sz; \
183} while (0)
184
00c7638b 185/* --- @dstr_vputf@ --- *
186 *
187 * Arguments: @dstr *d@ = pointer to a dynamic string block
188 * @const char *p@ = pointer to @printf@-style format string
189 * @va_list ap@ = argument handle
190 *
191 * Returns: ---
192 *
193 * Use: As for @dstr_putf@, but may be used as a back-end to user-
194 * supplied functions with @printf@-style interfaces.
195 */
196
197extern int dstr_vputf(dstr */*d*/, const char */*p*/, va_list /*ap*/);
198
199/* --- @dstr_putf@ --- *
200 *
201 * Arguments: @dstr *d@ = pointer to a dynamic string block
202 * @const char *p@ = pointer to @printf@-style format string
203 * @...@ = argument handle
204 *
205 * Returns: ---
206 *
207 * Use: Writes a piece of text to a dynamic string, doing @printf@-
208 * style substitutions as it goes. Intended to be robust if
209 * faced with malicious arguments, but not if the format string
210 * itself is malicious.
211 */
212
213extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
214
0875b58f 215/* --- @dstr_putd@ --- *
216 *
217 * Arguments: @dstr *d@ = pointer to a dynamic string block
218 * @const dstr *s@ = pointer to a dynamic string to append
219 *
220 * Returns: ---
221 *
222 * Use: Appends a dynamic string to a string. A trailing null
223 * byte is added, as for @dstr_putz@.
224 */
225
226extern void dstr_putd(dstr */*d*/, const dstr */*s*/);
227
228#define DPUTD(d, s) do { \
229 DENSURE((d), (s)->len + 1); \
230 memcpy((d)->buf + (d)->len, (s)->buf, (s)->len); \
231 (d)->len += (s)->len; \
232 (d)->buf[(d)->len] = 0; \
233} while (0)
234
235/* --- @dstr_putm@ --- *
236 *
237 * Arguments: @dstr *d@ = pointer to a dynamic string block
238 * @const void *p@ = pointer to a block to append
239 * @size_t sz@ = size of the block
240 *
241 * Returns: Appends an arbitrary data block to a string. No trailing
242 * null is appended.
243 */
244
245extern void dstr_putm(dstr */*d*/, const void */*p*/, size_t /*sz*/);
246
247#define DPUTM(d, p, sz) do { \
248 DENSURE((d), (sz)); \
249 memcpy((d)->buf + (d)->len, (p), (sz)); \
250 (d)->len += (sz); \
251} while (0)
252
253/* --- @dstr_tidy@ --- *
254 *
255 * Arguments: @dstr *d@ = pointer to a dynamic string block
256 *
257 * Returns: ---
258 *
259 * Use: Reduces the amount of memory used by a string. A trailing
260 * null byte is added, as for @dstr_putz@.
261 */
262
263extern void dstr_tidy(dstr */*d*/);
264
265/* --- @dstr_putline@ --- *
266 *
267 * Arguments: @dstr *d@ = pointer to a dynamic string block
268 * @FILE *fp@ = a stream to read from
269 *
270 * Returns: The number of characters read into the buffer, or @EOF@ if
271 * end-of-file was reached before any characters were read.
272 *
273 * Use: Appends the next line from the given input stream to the
274 * string. A trailing newline is not added; a trailing null
275 * byte is appended, as for @dstr_putz@.
276 */
277
278extern int dstr_putline(dstr */*d*/, FILE */*fp*/);
279
280/* --- @dstr_write@ --- *
281 *
282 * Arguments: @dstr *d@ = pointer to a dynamic string block
283 * @FILE *fp@ = a stream to write on
284 *
285 * Returns: The number of bytes written (as for @fwrite@).
286 *
287 * Use: Writes a dynamic string to a file.
288 */
289
290extern size_t dstr_write(dstr */*d*/, FILE */*fp*/);
291
292/*----- That's all, folks -------------------------------------------------*/
293
294#ifdef __cplusplus
295 }
296#endif
297
298#endif