17 \h'-\w'\\$1\ 'u'\\$1\ \c
22 .TH dstr 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
24 dstr \- a simple dynamic string type
54 .B "#include <mLib/dstr.h>"
56 .B "typedef struct { ...\& } dstr;"
57 .B "#define DSTR_INIT ..."
59 .BI "void dstr_create(dstr *" d );
60 .BI "void dstr_destroy(dstr *" d );
61 .BI "void dstr_reset(dstr *" d );
63 .BI "void dstr_ensure(dstr *" d ", size_t " sz );
64 .BI "void dstr_tidy(dstr *" d );
66 .BI "void dstr_putc(dstr *" d ", int " ch );
67 .BI "void dstr_putz(dstr *" d );
68 .BI "void dstr_puts(dstr *" d ", const char *" s );
69 .BI "int dstr_vputf(dstr *" d ", va_list *" ap );
70 .BI "int dstr_putf(dstr *" d ", ...);"
71 .BI "void dstr_putd(dstr *" d ", const dstr *" p );
72 .BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
73 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
74 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
76 .BI "void DCREATE(dstr *" d );
77 .BI "void DDESTROY(dstr *" d );
78 .BI "void DRESET(dstr *" d );
79 .BI "void DENSURE(dstr *" d ", size_t " sz );
80 .BI "void DPUTC(dstr *" c ", char " ch );
81 .BI "void DPUTZ(dstr *" d );
82 .BI "void DPUTS(dstr *" d ", const char *" s );
83 .BI "void DPUTD(dstr *" d ", const dstr *" p );
84 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
85 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
90 declares a type for representing dynamically extending strings, and a
91 small collection of useful operations on them. None of the operations
92 returns a failure result on an out-of-memory condition; instead, the
97 Many of the functions which act on dynamic strings have macro
98 equivalents. These equivalent macros may evaluate their arguments
100 .SS "Underlying type"
103 object is a small structure with the following members.
106 member points to the actual character data in the string. The data may
107 or may not be null terminated, depending on what operations have
108 recently been performed on it. None of the
110 functions depend on the string being null-terminated; indeed, all of
111 them work fine on strings containing arbitrary binary data. You can
112 force null-termination by calling the
120 member describes the current size of the buffer. This reflects the
121 maximum possible length of string that can be represented in
123 without allocating a new buffer.
127 member describes the current length of the string. It is the number of
128 bytes in the string which are actually interesting. The length does
130 include a null-terminating byte, if there is one.
132 The following invariants are maintained by
134 and must hold when any function is called:
140 points to a block of memory of length
151 Note that there is no equivalent of the standard C distinction between
152 the empty string (a pointer to an array of characters whose first
153 element is zero) and the nonexistent string (a null pointer). Any
157 is zero is an empty string.
161 member refers to the arena from which the string's buffer has been
162 allocated. Immediately after creation, this is set to be
163 .BR arena_stdlib (3);
164 you can set it to point to any other arena of your choice before the
166 .SS "Creation and destruction"
167 The caller is responsible for allocating the
169 structure. It can be initialized:
173 as an initializer in the declaration of the object,
175 passing its address to the
179 passing its address to the (equivalent)
183 The initial value of a
187 The additional storage space for a string's contents may be reclaimed by
192 macro. After destruction, a string's value is reset to the empty
194 .I "it's still a valid"
196 However, once a string has been destroyed, it's safe to deallocate the
203 function empties a string
205 deallocating any memory. Therefore appending more characters is quick,
206 because the old buffer is still there and doesn't need to be allocated.
211 is equivalent to directly assigning
217 which does the same job as the
220 .SS "Extending a string"
221 All memory allocation for strings is done by the function
229 the function ensures that there are at least
231 unused bytes in the string's buffer. The current algorithm for
232 extending the buffer is fairly unsophisticated, but seems to work
233 relatively well \- see the source if you really want to know what it's
236 Extending a string never returns a failure result. Instead, if there
237 isn't enough memory for a longer string, the exception
241 for more information about
243 exception handling system.
245 Note that if an ensure operation needs to reallocate a string buffer,
246 any pointers you've taken into the string become invalid.
250 which does a quick inline check to see whether there's enough space in
251 a string's buffer. This saves a procedure call when no reallocation
252 needs to be done. The
254 macro is called in the same way as the
260 `trims' a string's buffer so that it's just large enough for the string
261 contents and a null terminating byte. This might raise an exception due
262 to lack of memory. (There are two possible ways this might happen.
263 Firstly, the underlying allocator might just be brain-damaged enough to
264 fail on reducing a block's size. Secondly, tidying an empty string with no
265 buffer allocated for it causes allocation of a buffer large enough for
266 the terminating null byte.)
267 .SS "Contributing data to a string"
268 There are a collection of functions which add data to a string. All of
269 these functions add their new data to the
271 of the string. This is good, because programs usually build strings
272 left-to-right. If you want to do something more clever, that's up to
275 Several of these functions have equivalent macros which do the main work
276 inline. (There still might need to be a function call if the buffer
277 needs to be extended.)
279 Any of these functions might extend the string, causing pointers into
280 the string buffer to be invalidated. If you don't want that to happen,
281 pre-ensure enough space before you start.
283 The simplest function is
285 which appends a single character
287 to the end of the string. It has a macro equivalent called
292 places a zero byte at the end of the string. It does
294 affect the string's length, so any other data added to the string will
295 overwrite the null terminator. This is useful if you want to pass your
296 string to one of the standard C library string-handling functions. The
303 writes a C-style null-terminated string to the end of a dynamic string.
304 A terminating zero byte is also written, as if
306 were called. The macro
312 works similarly to the standard
314 function. It accepts a
316 format string and an arbitrary number of arguments to format and writes
317 the resulting text to the end of a dynamic string, returning the number
318 of characters so written. A terminating zero byte is also appended.
319 The formatting is intended to be convenient and safe rather than
320 efficient, so don't expect blistering performance. Similarly, there may
321 be differences between the formatting done by
325 because the former has to do most of its work itself. In particular,
327 understands the POSIX
329 positional parameter notation accepted by many Unix C libraries, even if
330 the underlying C library does not. There is no macro equivalent of
335 provides access to the `guts' of
337 given a format string and a pointer to a
339 it will format the arguments according to the format string, just as
341 does. (Note: that's a
345 so that it gets updated properly on exit.)
349 appends the contents of one dynamic string to another. A null
350 terminator is also appended. The macro
356 puts an arbitrary block of memory, addressed by
360 bytes, at the end of a dynamic string. No terminating null is appended:
361 it's assumed that if you're playing with arbitrary chunks of memory then
362 you're probably not going to be using the resulting data as a normal
363 text string. The macro
369 reads a line from an input stream
371 and appends it to a string. If an error occurs, or end-of-file is
372 encountered, before any characters have been read, then
376 and does not extend the string. Otherwise, it reads until it encounters
377 a newline character, an error, or end-of-file, and returns the number of
378 characters read. If reading was terminated by a newline character, the
381 inserted in the buffer. A terminating null is appended, as by
383 .SS "Other functions"
386 function writes a string to an output stream
388 It returns the number of characters written, or
390 if an error occurred before the first write. No newline character is
391 written to the stream, unless the string actually contains one already.
395 .SH "SECURITY CONSIDERATIONS"
396 The implementation of the
398 functions is designed to do string handling in security-critical
399 programs. However, there may be bugs in the code somewhere. In
402 functions are quite complicated, and could do with some checking by
403 independent people who know what they're doing.
408 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob