17 \h'-\w'\\$1\ 'u'\\$1\ \c
22 .TH dstr 3 "8 May 1999" "mLib"
23 dstr \- a simple dynamic string type
52 .B "#include <mLib/dstr.h>"
54 .BI "void dstr_create(dstr *" d );
55 .BI "void dstr_destroy(dstr *" d );
56 .BI "void dstr_reset(dstr *" d );
58 .BI "void dstr_ensure(dstr *" d ", size_t " sz );
59 .BI "void dstr_tidy(dstr *" d );
61 .BI "void dstr_putc(dstr *" d ", char " ch );
62 .BI "void dstr_putz(dstr *" d );
63 .BI "void dstr_puts(dstr *" d ", const char *" s );
64 .BI "int dstr_vputf(dstr *" d ", va_list " ap );
65 .BI "int dstr_putf(dstr *" d ", ...);
66 .BI "void dstr_putd(dstr *" d ", const dstr *" p );
67 .BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
68 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
69 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
71 .BI "void DCREATE(dstr *" d );
72 .BI "void DDESTROY(dstr *" d );
73 .BI "void DRESET(dstr *" d );
74 .BI "void DENSURE(dstr *" d ", size_t " sz );
75 .BI "void DPUTC(dstr *" c ", char " ch );
76 .BI "void DPUTZ(dstr *" d );
77 .BI "void DPUTS(dstr *" d ", const char *" s );
78 .BI "void DPUTD(dstr *" d ", const dstr *" p );
79 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
80 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
85 declares a type for representing dynamically extending strings, and a
86 small collection of useful operations on them. None of the operations
87 returns a failure result on an out-of-memory condition; instead, the
92 Many of the functions which act on dynamic strings have macro
93 equivalents. These equivalent macros may evaluate their arguments
98 object is a small structure with the following members:
100 typedef struct dstr {
101 char *buf; /* Pointer to string buffer */
102 size_t sz; /* Size of the buffer */
103 size_t len; /* Length of the string */
108 member points to the actual character data in the string. The data may
109 or may not be null terminated, depending on what operations have
110 recently been performed on it. None of the
112 functions depend on the string being null-terminated; indeed, all of
113 them work fine on strings containing arbitrary binary data. You can
114 force null-termination by calling the
122 member describes the current size of the buffer. This reflects the
123 maximum possible length of string that can be represented in
125 without allocating a new buffer.
129 member describes the current length of the string. It is the number of
130 bytes in the string which are actually interesting. The length does
132 include a null-terminating byte, if there is one.
134 The following invariants are maintained by
136 and must hold when any function is called:
142 points to a block of memory of length
151 .BI sz " >= " len\fR.
153 Note that there is no equaivalent of the standard C distinction between
154 the empty string (a pointer to an array of characters whose first
155 element is zero) and the nonexistant string (a null pointer). Any
159 is zero is an empty string.
160 .SH "CREATION AND DESTRUCTION"
161 The caller is responsible for allocating the
163 structure. It can be initialized in any of the following ways:
167 as an initializer in the declaration of the object.
169 Passing its address to the
173 Passing its address to the (equivalent)
177 The initial value of a
181 The additional storage space for a string's contents may be reclaimed by
186 macro. After destruction, a string's value is reset to the empty
188 .I "it's still a valid"
190 However, once a string has been destroyed, it's safe to deallocate the
197 function empties a string
199 deallocating any memory. Therefore appending more characters is quick,
200 beause the old buffer is still there and doesn't need to be allocated.
205 is equivalent to directly assinging
211 which does the same job as the
214 .SH "EXTENDING A STRING"
215 All memory allocation for strings is done by the function
223 the function ensures that there are at least
225 unused bytes in the string's buffer. The current algorithm for
226 extending the buffer is fairly unsophisticated, but seems to work
227 relatively well \- see the source if you really want to know what it's
230 Extending a string never returns a failure result. Instead, if there
231 isn't enough memory for a longer string, the exception
235 for more information about
237 exception handling system.
239 Note that if an ensure operation needs to reallocate a string buffer,
240 any pointers you've taken into the string become invalid.
244 which does a quick inline check to see whether there's enough space in
245 a string's buffer. This saves a procedure call when no reallocation
246 needs to be done. The
248 macro is called in the same way as the
254 `trims' a string's buffer so that it's just large enough for the string
255 contents and a null terminating byte. This might raise an exception due
256 to lack of memory. (There are two possible ways this might happen.
257 Firstly, the underlying allocator might just be braindamaged enough to
258 fail on reducing a block's size. Secondly, tidying an empty string with no
259 buffer allocated for it causes allocation of a buffer large enough for
260 the terminating null byte.)
261 .SH "CONTRIBUTING DATA TO A STRING"
262 There are a collection of functions which add data to a string. All of
263 these functions add their new data to the
265 of the string. This is good, because programs usually build strings
266 left-to-right. If you want to do something more clever, that's up to
269 Several of these functions have equivalent macros which do the main work
270 inline. (There still might need to be a function call if the buffer
271 needs to be extended.)
273 Any of these functions might extend the string, causing pointers into
274 the string buffer to be invalidated. If you don't want that to happen,
275 pre-ensure enough space before you start.
277 The simplest function is
279 which appends a single character
281 to the end of the string. It has a macro equivalent called
286 places a zero byte at the end of the string. It does
288 affect the string's length, so any other data added to the string will
289 overwrite the null terminator. This is useful if you want to pass your
290 string to one of the standard C library string-handling functions. The
297 writes a C-style null-terminated string to the end of a dynamic string.
298 A terminating zero byte is also written, as if
300 were called. The macro
306 works similarly to the standard
308 function. It accepts a
310 format string and an arbitrary number of arguments to format and writes
311 the resulting text to the end of a dynamic string, returning the number
312 of characters so written. A terminating zero byte is also appended.
313 The formatting is intended to be convenient and safe rather than
314 efficient, so don't expect blistering performance. Similarly, there may
315 be differences between the formatting done by
319 because the former has to do most of its work itself. In particular,
321 doesn't (and probably never will) understand the
323 positional paramter notation accepted by many Unix C libraries. There
324 is no macro equivalent of
329 provides access to the `guts' of
331 given a format string and a
333 pointer, it will format the arguments according to the format string,
340 appends the contents of one dynamic string to another. A null
341 terminator is also appended. The macro
347 puts an arbitrary block of memory, addressed by
351 bytes, at the end of a dynamic string. No terminating null is appended:
352 it's assumed that if you're playing with arbitrary chunks of memory then
353 you're probably not going to be using the resulting data as a normal
354 text string. The macro
360 reads a line from an input stream
362 and appends it to a string. If an error occurs, or end-of-file is
363 encountered, before any characters have been read, then
367 Otherwise, it reads until it encounters a newline character, an error,
368 or end-of-file, and returns the number of characters read. If reading
369 was terminated by a newline character, the newline character is
371 inserted in the buffer. A terminating null is appended, as by
373 .SH "OTHER FUNCTIONS"
376 function writes a string to an output stream
378 It returns the number of characters written, or
380 if an error occurred before the first write. No newline character is
381 written to the stream, unless the string actually contains one already.
385 .SH "SECURITY CONSIDERATIONS"
386 The implemenetation of the
388 functions is designed to do string handling in security-critical
389 programs. However, there may be bugs in the code somewhere. In
392 functions is quite complicated, and could do with some checking by
393 independent people who know what they're doing.
398 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob