chiark / gitweb /
Reformatted the LGPL notice a little bit.
[mLib] / dstr.h
1 /* -*-c-*-
2  *
3  * $Id: dstr.h,v 1.4 1999/05/06 19:51:35 mdw Exp $
4  *
5  * Handle dynamically growing strings
6  *
7  * (c) 1998 Straylight/Edgeware
8  */
9
10 /*----- Licensing notice --------------------------------------------------* 
11  *
12  * This file is part of the mLib utilities library.
13  *
14  * mLib is free software; you can redistribute it and/or modify
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  * 
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
22  * GNU Library General Public License for more details.
23  * 
24  * You should have received a copy of the GNU Library General Public
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.
28  */
29
30 /*----- Revision history --------------------------------------------------*
31  *
32  * $Log: dstr.h,v $
33  * Revision 1.4  1999/05/06 19:51:35  mdw
34  * Reformatted the LGPL notice a little bit.
35  *
36  * Revision 1.3  1999/05/05 18:50:31  mdw
37  * Change licensing conditions to LGPL.
38  *
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
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
67 #include <stdarg.h>
68 #include <stdio.h>
69
70 /*----- Data structures ---------------------------------------------------*/
71
72 typedef 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
89 extern 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
100 extern 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
111 extern 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
124 extern 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
140 extern 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
158 extern 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
176 extern 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
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
197 extern 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
213 extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
214
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
226 extern 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
245 extern 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
263 extern 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
278 extern 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
290 extern size_t dstr_write(dstr */*d*/, FILE */*fp*/);
291
292 /*----- That's all, folks -------------------------------------------------*/
293
294 #ifdef __cplusplus
295   }
296 #endif
297
298 #endif