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 */
106 arena *a; /* Pointer to arena */
111 member points to the actual character data in the string. The data may
112 or may not be null terminated, depending on what operations have
113 recently been performed on it. None of the
115 functions depend on the string being null-terminated; indeed, all of
116 them work fine on strings containing arbitrary binary data. You can
117 force null-termination by calling the
125 member describes the current size of the buffer. This reflects the
126 maximum possible length of string that can be represented in
128 without allocating a new buffer.
132 member describes the current length of the string. It is the number of
133 bytes in the string which are actually interesting. The length does
135 include a null-terminating byte, if there is one.
137 The following invariants are maintained by
139 and must hold when any function is called:
145 points to a block of memory of length
154 .BI sz " >= " len\fR.
156 Note that there is no equivalent of the standard C distinction between
157 the empty string (a pointer to an array of characters whose first
158 element is zero) and the nonexistent string (a null pointer). Any
162 is zero is an empty string.
166 member refers to the arena from which the string's buffer has been
167 allocated. Immediately after creation, this is set to be
168 .BR arena_stdlib (3);
169 you can set it to point to any other arena of your choice before the
171 .SS "Creation and destruction"
172 The caller is responsible for allocating the
174 structure. It can be initialized in any of the following ways:
178 as an initializer in the declaration of the object.
180 Passing its address to the
184 Passing its address to the (equivalent)
188 The initial value of a
192 The additional storage space for a string's contents may be reclaimed by
197 macro. After destruction, a string's value is reset to the empty
199 .I "it's still a valid"
201 However, once a string has been destroyed, it's safe to deallocate the
208 function empties a string
210 deallocating any memory. Therefore appending more characters is quick,
211 because the old buffer is still there and doesn't need to be allocated.
216 is equivalent to directly assigning
222 which does the same job as the
225 .SS "Extending a string"
226 All memory allocation for strings is done by the function
234 the function ensures that there are at least
236 unused bytes in the string's buffer. The current algorithm for
237 extending the buffer is fairly unsophisticated, but seems to work
238 relatively well \- see the source if you really want to know what it's
241 Extending a string never returns a failure result. Instead, if there
242 isn't enough memory for a longer string, the exception
246 for more information about
248 exception handling system.
250 Note that if an ensure operation needs to reallocate a string buffer,
251 any pointers you've taken into the string become invalid.
255 which does a quick inline check to see whether there's enough space in
256 a string's buffer. This saves a procedure call when no reallocation
257 needs to be done. The
259 macro is called in the same way as the
265 `trims' a string's buffer so that it's just large enough for the string
266 contents and a null terminating byte. This might raise an exception due
267 to lack of memory. (There are two possible ways this might happen.
268 Firstly, the underlying allocator might just be brain-damaged enough to
269 fail on reducing a block's size. Secondly, tidying an empty string with no
270 buffer allocated for it causes allocation of a buffer large enough for
271 the terminating null byte.)
272 .SS "Contributing data to a string"
273 There are a collection of functions which add data to a string. All of
274 these functions add their new data to the
276 of the string. This is good, because programs usually build strings
277 left-to-right. If you want to do something more clever, that's up to
280 Several of these functions have equivalent macros which do the main work
281 inline. (There still might need to be a function call if the buffer
282 needs to be extended.)
284 Any of these functions might extend the string, causing pointers into
285 the string buffer to be invalidated. If you don't want that to happen,
286 pre-ensure enough space before you start.
288 The simplest function is
290 which appends a single character
292 to the end of the string. It has a macro equivalent called
297 places a zero byte at the end of the string. It does
299 affect the string's length, so any other data added to the string will
300 overwrite the null terminator. This is useful if you want to pass your
301 string to one of the standard C library string-handling functions. The
308 writes a C-style null-terminated string to the end of a dynamic string.
309 A terminating zero byte is also written, as if
311 were called. The macro
317 works similarly to the standard
319 function. It accepts a
321 format string and an arbitrary number of arguments to format and writes
322 the resulting text to the end of a dynamic string, returning the number
323 of characters so written. A terminating zero byte is also appended.
324 The formatting is intended to be convenient and safe rather than
325 efficient, so don't expect blistering performance. Similarly, there may
326 be differences between the formatting done by
330 because the former has to do most of its work itself. In particular,
332 doesn't (and probably never will) understand the
334 positional parameter notation accepted by many Unix C libraries. There
335 is no macro equivalent of
340 provides access to the `guts' of
342 given a format string and a
344 pointer, it will format the arguments according to the format string,
351 appends the contents of one dynamic string to another. A null
352 terminator is also appended. The macro
358 puts an arbitrary block of memory, addressed by
362 bytes, at the end of a dynamic string. No terminating null is appended:
363 it's assumed that if you're playing with arbitrary chunks of memory then
364 you're probably not going to be using the resulting data as a normal
365 text string. The macro
371 reads a line from an input stream
373 and appends it to a string. If an error occurs, or end-of-file is
374 encountered, before any characters have been read, then
378 and does not extend the string. Otherwise, it reads until it encounters
379 a newline character, an error, or end-of-file, and returns the number of
380 characters read. If reading was terminated by a newline character, the
383 inserted in the buffer. A terminating null is appended, as by
385 .SS "Other functions"
388 function writes a string to an output stream
390 It returns the number of characters written, or
392 if an error occurred before the first write. No newline character is
393 written to the stream, unless the string actually contains one already.
397 .SH "SECURITY CONSIDERATIONS"
398 The implementation of the
400 functions is designed to do string handling in security-critical
401 programs. However, there may be bugs in the code somewhere. In
404 functions are quite complicated, and could do with some checking by
405 independent people who know what they're doing.
410 Mark Wooding, <mdw@nsict.org>
~mdw / mLib / blob