chiark / gitweb /
Change naming to match newer mLib conventions.
[mLib] / dstr.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
96c5fe33 3 * $Id: dstr.h,v 1.5 1999/05/13 22:47:57 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 $
96c5fe33 33 * Revision 1.5 1999/05/13 22:47:57 mdw
34 * Misc documentation fixes. Change `-ise' to `-ize' throughout.
35 *
0bd98442 36 * Revision 1.4 1999/05/06 19:51:35 mdw
37 * Reformatted the LGPL notice a little bit.
38 *
c846879c 39 * Revision 1.3 1999/05/05 18:50:31 mdw
40 * Change licensing conditions to LGPL.
41 *
00c7638b 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
0875b58f 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
00c7638b 70#include <stdarg.h>
0875b58f 71#include <stdio.h>
72
73/*----- Data structures ---------------------------------------------------*/
74
75typedef 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 *
96c5fe33 89 * Use: Initializes a dynamic string.
0875b58f 90 */
91
92extern 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
103extern 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
114extern 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
127extern 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
143extern 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
161extern 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
179extern 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
00c7638b 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 *
96c5fe33 194 * Returns: The number of characters written to the string.
00c7638b 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
200extern 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 *
96c5fe33 208 * Returns: The number of characters written to the string.
00c7638b 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
216extern int dstr_putf(dstr */*d*/, const char */*p*/, ...);
217
0875b58f 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
229extern 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
248extern 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
266extern 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
281extern 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
96c5fe33 293extern size_t dstr_write(const dstr */*d*/, FILE */*fp*/);
0875b58f 294
295/*----- That's all, folks -------------------------------------------------*/
296
297#ifdef __cplusplus
298 }
299#endif
300
301#endif