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 .BI "void dstr_create(dstr *" d );
57 .BI "void dstr_destroy(dstr *" d );
58 .BI "void dstr_reset(dstr *" d );
60 .BI "void dstr_ensure(dstr *" d ", size_t " sz );
61 .BI "void dstr_tidy(dstr *" d );
63 .BI "void dstr_putc(dstr *" d ", char " ch );
64 .BI "void dstr_putz(dstr *" d );
65 .BI "void dstr_puts(dstr *" d ", const char *" s );
66 .BI "int dstr_vputf(dstr *" d ", va_list *" ap );
67 .BI "int dstr_putf(dstr *" d ", ...);"
68 .BI "void dstr_putd(dstr *" d ", const dstr *" p );
69 .BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
70 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
71 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
73 .BI "dstr " d " = DSTR_INIT;"
74 .BI "void DCREATE(dstr *" d );
75 .BI "void DDESTROY(dstr *" d );
76 .BI "void DRESET(dstr *" d );
77 .BI "void DENSURE(dstr *" d ", size_t " sz );
78 .BI "void DPUTC(dstr *" c ", char " ch );
79 .BI "void DPUTZ(dstr *" d );
80 .BI "void DPUTS(dstr *" d ", const char *" s );
81 .BI "void DPUTD(dstr *" d ", const dstr *" p );
82 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
83 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
88 declares a type for representing dynamically extending strings, and a
89 small collection of useful operations on them. None of the operations
90 returns a failure result on an out-of-memory condition; instead, the
95 Many of the functions which act on dynamic strings have macro
96 equivalents. These equivalent macros may evaluate their arguments
101 object is a small structure with the following members:
103 typedef struct dstr {
104 char *buf; /* Pointer to string buffer */
105 size_t sz; /* Size of the buffer */
106 size_t len; /* Length of the string */
107 arena *a; /* Pointer to arena */
112 member points to the actual character data in the string. The data may
113 or may not be null terminated, depending on what operations have
114 recently been performed on it. None of the
116 functions depend on the string being null-terminated; indeed, all of
117 them work fine on strings containing arbitrary binary data. You can
118 force null-termination by calling the
126 member describes the current size of the buffer. This reflects the
127 maximum possible length of string that can be represented in
129 without allocating a new buffer.
133 member describes the current length of the string. It is the number of
134 bytes in the string which are actually interesting. The length does
136 include a null-terminating byte, if there is one.
138 The following invariants are maintained by
140 and must hold when any function is called:
146 points to a block of memory of length
157 Note that there is no equivalent of the standard C distinction between
158 the empty string (a pointer to an array of characters whose first
159 element is zero) and the nonexistent string (a null pointer). Any
163 is zero is an empty string.
167 member refers to the arena from which the string's buffer has been
168 allocated. Immediately after creation, this is set to be
169 .BR arena_stdlib (3);
170 you can set it to point to any other arena of your choice before the
172 .SS "Creation and destruction"
173 The caller is responsible for allocating the
175 structure. It can be initialized:
179 as an initializer in the declaration of the object,
181 passing its address to the
185 passing its address to the (equivalent)
189 The initial value of a
193 The additional storage space for a string's contents may be reclaimed by
198 macro. After destruction, a string's value is reset to the empty
200 .I "it's still a valid"
202 However, once a string has been destroyed, it's safe to deallocate the
209 function empties a string
211 deallocating any memory. Therefore appending more characters is quick,
212 because the old buffer is still there and doesn't need to be allocated.
217 is equivalent to directly assigning
223 which does the same job as the
226 .SS "Extending a string"
227 All memory allocation for strings is done by the function
235 the function ensures that there are at least
237 unused bytes in the string's buffer. The current algorithm for
238 extending the buffer is fairly unsophisticated, but seems to work
239 relatively well \- see the source if you really want to know what it's
242 Extending a string never returns a failure result. Instead, if there
243 isn't enough memory for a longer string, the exception
247 for more information about
249 exception handling system.
251 Note that if an ensure operation needs to reallocate a string buffer,
252 any pointers you've taken into the string become invalid.
256 which does a quick inline check to see whether there's enough space in
257 a string's buffer. This saves a procedure call when no reallocation
258 needs to be done. The
260 macro is called in the same way as the
266 `trims' a string's buffer so that it's just large enough for the string
267 contents and a null terminating byte. This might raise an exception due
268 to lack of memory. (There are two possible ways this might happen.
269 Firstly, the underlying allocator might just be brain-damaged enough to
270 fail on reducing a block's size. Secondly, tidying an empty string with no
271 buffer allocated for it causes allocation of a buffer large enough for
272 the terminating null byte.)
273 .SS "Contributing data to a string"
274 There are a collection of functions which add data to a string. All of
275 these functions add their new data to the
277 of the string. This is good, because programs usually build strings
278 left-to-right. If you want to do something more clever, that's up to
281 Several of these functions have equivalent macros which do the main work
282 inline. (There still might need to be a function call if the buffer
283 needs to be extended.)
285 Any of these functions might extend the string, causing pointers into
286 the string buffer to be invalidated. If you don't want that to happen,
287 pre-ensure enough space before you start.
289 The simplest function is
291 which appends a single character
293 to the end of the string. It has a macro equivalent called
298 places a zero byte at the end of the string. It does
300 affect the string's length, so any other data added to the string will
301 overwrite the null terminator. This is useful if you want to pass your
302 string to one of the standard C library string-handling functions. The
309 writes a C-style null-terminated string to the end of a dynamic string.
310 A terminating zero byte is also written, as if
312 were called. The macro
318 works similarly to the standard
320 function. It accepts a
322 format string and an arbitrary number of arguments to format and writes
323 the resulting text to the end of a dynamic string, returning the number
324 of characters so written. A terminating zero byte is also appended.
325 The formatting is intended to be convenient and safe rather than
326 efficient, so don't expect blistering performance. Similarly, there may
327 be differences between the formatting done by
331 because the former has to do most of its work itself. In particular,
333 doesn't (and probably never will) understand the
335 positional parameter notation accepted by many Unix C libraries. There
336 is no macro equivalent of
341 provides access to the `guts' of
343 given a format string and a pointer to a
345 it will format the arguments according to the format string, just as
347 does. (Note: that's a
351 so that it gets updated properly on exit.)
355 appends the contents of one dynamic string to another. A null
356 terminator is also appended. The macro
362 puts an arbitrary block of memory, addressed by
366 bytes, at the end of a dynamic string. No terminating null is appended:
367 it's assumed that if you're playing with arbitrary chunks of memory then
368 you're probably not going to be using the resulting data as a normal
369 text string. The macro
375 reads a line from an input stream
377 and appends it to a string. If an error occurs, or end-of-file is
378 encountered, before any characters have been read, then
382 and does not extend the string. Otherwise, it reads until it encounters
383 a newline character, an error, or end-of-file, and returns the number of
384 characters read. If reading was terminated by a newline character, the
387 inserted in the buffer. A terminating null is appended, as by
389 .SS "Other functions"
392 function writes a string to an output stream
394 It returns the number of characters written, or
396 if an error occurred before the first write. No newline character is
397 written to the stream, unless the string actually contains one already.
401 .SH "SECURITY CONSIDERATIONS"
402 The implementation of the
404 functions is designed to do string handling in security-critical
405 programs. However, there may be bugs in the code somewhere. In
408 functions are quite complicated, and could do with some checking by
409 independent people who know what they're doing.
414 Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blob