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