17 \h'-\w'\\$1\ 'u'\\$1\ \c
22 .TH dstr 3 "8 May 1999" "mLib"
23 dstr \- a simple dynamic string type
53 .B "#include <mLib/dstr.h>"
55 .BI "void dstr_create(dstr *" d );
56 .BI "void dstr_destroy(dstr *" d );
57 .BI "void dstr_reset(dstr *" d );
59 .BI "void dstr_ensure(dstr *" d ", size_t " sz );
60 .BI "void dstr_tidy(dstr *" d );
62 .BI "void dstr_putc(dstr *" d ", char " ch );
63 .BI "void dstr_putz(dstr *" d );
64 .BI "void dstr_puts(dstr *" d ", const char *" s );
65 .BI "int dstr_vputf(dstr *" d ", va_list " ap );
66 .BI "int dstr_putf(dstr *" d ", ...);"
67 .BI "void dstr_putd(dstr *" d ", const dstr *" p );
68 .BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
69 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
70 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
72 .BI "dstr " d " = DSTR_INIT;"
73 .BI "void DCREATE(dstr *" d );
74 .BI "void DDESTROY(dstr *" d );
75 .BI "void DRESET(dstr *" d );
76 .BI "void DENSURE(dstr *" d ", size_t " sz );
77 .BI "void DPUTC(dstr *" c ", char " ch );
78 .BI "void DPUTZ(dstr *" d );
79 .BI "void DPUTS(dstr *" d ", const char *" s );
80 .BI "void DPUTD(dstr *" d ", const dstr *" p );
81 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
82 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
87 declares a type for representing dynamically extending strings, and a
88 small collection of useful operations on them. None of the operations
89 returns a failure result on an out-of-memory condition; instead, the
94 Many of the functions which act on dynamic strings have macro
95 equivalents. These equivalent macros may evaluate their arguments
100 object is a small structure with the following members:
102 typedef struct dstr {
103 char *buf; /* Pointer to string buffer */
104 size_t sz; /* Size of the buffer */
105 size_t len; /* Length of the string */
110 member points to the actual character data in the string. The data may
111 or may not be null terminated, depending on what operations have
112 recently been performed on it. None of the
114 functions depend on the string being null-terminated; indeed, all of
115 them work fine on strings containing arbitrary binary data. You can
116 force null-termination by calling the
124 member describes the current size of the buffer. This reflects the
125 maximum possible length of string that can be represented in
127 without allocating a new buffer.
131 member describes the current length of the string. It is the number of
132 bytes in the string which are actually interesting. The length does
134 include a null-terminating byte, if there is one.
136 The following invariants are maintained by
138 and must hold when any function is called:
144 points to a block of memory of length
153 .BI sz " >= " len\fR.
155 Note that there is no equivalent of the standard C distinction between
156 the empty string (a pointer to an array of characters whose first
157 element is zero) and the nonexistent string (a null pointer). Any
161 is zero is an empty string.
162 .SH "CREATION AND DESTRUCTION"
163 The caller is responsible for allocating the
165 structure. It can be initialized in any of the following ways:
169 as an initializer in the declaration of the object.
171 Passing its address to the
175 Passing its address to the (equivalent)
179 The initial value of a
183 The additional storage space for a string's contents may be reclaimed by
188 macro. After destruction, a string's value is reset to the empty
190 .I "it's still a valid"
192 However, once a string has been destroyed, it's safe to deallocate the
199 function empties a string
201 deallocating any memory. Therefore appending more characters is quick,
202 because the old buffer is still there and doesn't need to be allocated.
207 is equivalent to directly assigning
213 which does the same job as the
216 .SH "EXTENDING A STRING"
217 All memory allocation for strings is done by the function
225 the function ensures that there are at least
227 unused bytes in the string's buffer. The current algorithm for
228 extending the buffer is fairly unsophisticated, but seems to work
229 relatively well \- see the source if you really want to know what it's
232 Extending a string never returns a failure result. Instead, if there
233 isn't enough memory for a longer string, the exception
237 for more information about
239 exception handling system.
241 Note that if an ensure operation needs to reallocate a string buffer,
242 any pointers you've taken into the string become invalid.
246 which does a quick inline check to see whether there's enough space in
247 a string's buffer. This saves a procedure call when no reallocation
248 needs to be done. The
250 macro is called in the same way as the
256 `trims' a string's buffer so that it's just large enough for the string
257 contents and a null terminating byte. This might raise an exception due
258 to lack of memory. (There are two possible ways this might happen.
259 Firstly, the underlying allocator might just be brain-damaged enough to
260 fail on reducing a block's size. Secondly, tidying an empty string with no
261 buffer allocated for it causes allocation of a buffer large enough for
262 the terminating null byte.)
263 .SH "CONTRIBUTING DATA TO A STRING"
264 There are a collection of functions which add data to a string. All of
265 these functions add their new data to the
267 of the string. This is good, because programs usually build strings
268 left-to-right. If you want to do something more clever, that's up to
271 Several of these functions have equivalent macros which do the main work
272 inline. (There still might need to be a function call if the buffer
273 needs to be extended.)
275 Any of these functions might extend the string, causing pointers into
276 the string buffer to be invalidated. If you don't want that to happen,
277 pre-ensure enough space before you start.
279 The simplest function is
281 which appends a single character
283 to the end of the string. It has a macro equivalent called
288 places a zero byte at the end of the string. It does
290 affect the string's length, so any other data added to the string will
291 overwrite the null terminator. This is useful if you want to pass your
292 string to one of the standard C library string-handling functions. The
299 writes a C-style null-terminated string to the end of a dynamic string.
300 A terminating zero byte is also written, as if
302 were called. The macro
308 works similarly to the standard
310 function. It accepts a
312 format string and an arbitrary number of arguments to format and writes
313 the resulting text to the end of a dynamic string, returning the number
314 of characters so written. A terminating zero byte is also appended.
315 The formatting is intended to be convenient and safe rather than
316 efficient, so don't expect blistering performance. Similarly, there may
317 be differences between the formatting done by
321 because the former has to do most of its work itself. In particular,
323 doesn't (and probably never will) understand the
325 positional parameter notation accepted by many Unix C libraries. There
326 is no macro equivalent of
331 provides access to the `guts' of
333 given a format string and a
335 pointer, it will format the arguments according to the format string,
342 appends the contents of one dynamic string to another. A null
343 terminator is also appended. The macro
349 puts an arbitrary block of memory, addressed by
353 bytes, at the end of a dynamic string. No terminating null is appended:
354 it's assumed that if you're playing with arbitrary chunks of memory then
355 you're probably not going to be using the resulting data as a normal
356 text string. The macro
362 reads a line from an input stream
364 and appends it to a string. If an error occurs, or end-of-file is
365 encountered, before any characters have been read, then
369 Otherwise, it reads until it encounters a newline character, an error,
370 or end-of-file, and returns the number of characters read. If reading
371 was terminated by a newline character, the newline character is
373 inserted in the buffer. A terminating null is appended, as by
375 .SH "OTHER FUNCTIONS"
378 function writes a string to an output stream
380 It returns the number of characters written, or
382 if an error occurred before the first write. No newline character is
383 written to the stream, unless the string actually contains one already.
387 .SH "SECURITY CONSIDERATIONS"
388 The implementation of the
390 functions is designed to do string handling in security-critical
391 programs. However, there may be bugs in the code somewhere. In
394 functions is quite complicated, and could do with some checking by
395 independent people who know what they're doing.
400 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob