3 .\" Manual for dynamic strings
5 .\" (c) 1999--2003, 2005, 2007, 2009, 2013, 2014, 2023, 2024
6 .\" Straylight/Edgeware
9 .\"----- Licensing notice ---------------------------------------------------
11 .\" This file is part of the mLib utilities library.
13 .\" mLib is free software: you can redistribute it and/or modify it under
14 .\" the terms of the GNU Library General Public License as published by
15 .\" the Free Software Foundation; either version 2 of the License, or (at
16 .\" your option) any later version.
18 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
19 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
20 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
21 .\" License for more details.
23 .\" You should have received a copy of the GNU Library General Public
24 .\" License along with mLib. If not, write to the Free Software
25 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
28 .\"--------------------------------------------------------------------------
29 .so ../defs.man \" @@@PRE@@@
31 .\"--------------------------------------------------------------------------
32 .TH dstr 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
62 .\"--------------------------------------------------------------------------
64 dstr \- a simple dynamic string type
66 .\"--------------------------------------------------------------------------
70 .B "#include <mLib/dstr.h>"
72 .B "typedef struct { ...\& } dstr;"
73 .B "#define DSTR_INIT ..."
75 .BI "void dstr_create(dstr *" d );
76 .BI "void dstr_destroy(dstr *" d );
77 .BI "void dstr_reset(dstr *" d );
79 .BI "void dstr_ensure(dstr *" d ", size_t " sz );
80 .BI "void dstr_tidy(dstr *" d );
82 .BI "void dstr_putc(dstr *" d ", int " ch );
83 .BI "void dstr_putz(dstr *" d );
84 .BI "void dstr_puts(dstr *" d ", const char *" s );
85 .BI "int dstr_vputf(dstr *" d ", va_list *" ap );
86 .BI "int dstr_putf(dstr *" d ", ...);"
87 .BI "void dstr_putd(dstr *" d ", const dstr *" p );
88 .BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
89 .BI "int dstr_putline(dstr *" d ", FILE *" fp );
90 .BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
92 .BI "void DCREATE(dstr *" d );
93 .BI "void DDESTROY(dstr *" d );
94 .BI "void DRESET(dstr *" d );
95 .BI "void DENSURE(dstr *" d ", size_t " sz );
96 .BI "void DPUTC(dstr *" c ", char " ch );
97 .BI "void DPUTZ(dstr *" d );
98 .BI "void DPUTS(dstr *" d ", const char *" s );
99 .BI "void DPUTD(dstr *" d ", const dstr *" p );
100 .BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
101 .BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
104 .\"--------------------------------------------------------------------------
109 declares a type for representing dynamically extending strings, and a
110 small collection of useful operations on them. None of the operations
111 returns a failure result on an out-of-memory condition; instead, the
116 Many of the functions which act on dynamic strings have macro
117 equivalents. These equivalent macros may evaluate their arguments
120 .SS "Underlying type"
123 object is a small structure with the following members.
126 member points to the actual character data in the string. The data may
127 or may not be null terminated, depending on what operations have
128 recently been performed on it. None of the
130 functions depend on the string being null-terminated; indeed, all of
131 them work fine on strings containing arbitrary binary data. You can
132 force null-termination by calling the
140 member describes the current size of the buffer. This reflects the
141 maximum possible length of string that can be represented in
143 without allocating a new buffer.
147 member describes the current length of the string. It is the number of
148 bytes in the string which are actually interesting. The length does
150 include a null-terminating byte, if there is one.
152 The following invariants are maintained by
154 and must hold when any function is called:
160 points to a block of memory of length
171 Note that there is no equivalent of the standard C distinction between
172 the empty string (a pointer to an array of characters whose first
173 element is zero) and the nonexistent string (a null pointer). Any
177 is zero is an empty string.
181 member refers to the arena from which the string's buffer has been
182 allocated. Immediately after creation, this is set to be
183 .BR arena_stdlib (3);
184 you can set it to point to any other arena of your choice before the
187 .SS "Creation and destruction"
188 The caller is responsible for allocating the
190 structure. It can be initialized:
194 as an initializer in the declaration of the object,
196 passing its address to the
200 passing its address to the (equivalent)
204 The initial value of a
208 The additional storage space for a string's contents may be reclaimed by
213 macro. After destruction, a string's value is reset to the empty
215 .I "it's still a valid"
217 However, once a string has been destroyed, it's safe to deallocate the
224 function empties a string
226 deallocating any memory. Therefore appending more characters is quick,
227 because the old buffer is still there and doesn't need to be allocated.
232 is equivalent to directly assigning
238 which does the same job as the
242 .SS "Extending a string"
243 All memory allocation for strings is done by the function
251 the function ensures that there are at least
253 unused bytes in the string's buffer. The current algorithm for
254 extending the buffer is fairly unsophisticated, but seems to work
255 relatively well \- see the source if you really want to know what it's
258 Extending a string never returns a failure result. Instead, if there
259 isn't enough memory for a longer string, the exception
263 for more information about
265 exception handling system.
267 Note that if an ensure operation needs to reallocate a string buffer,
268 any pointers you've taken into the string become invalid.
272 which does a quick inline check to see whether there's enough space in
273 a string's buffer. This saves a procedure call when no reallocation
274 needs to be done. The
276 macro is called in the same way as the
282 `trims' a string's buffer so that it's just large enough for the string
283 contents and a null terminating byte. This might raise an exception due
284 to lack of memory. (There are two possible ways this might happen.
285 Firstly, the underlying allocator might just be brain-damaged enough to
286 fail on reducing a block's size. Secondly, tidying an empty string with no
287 buffer allocated for it causes allocation of a buffer large enough for
288 the terminating null byte.)
290 .SS "Contributing data to a string"
291 There are a collection of functions which add data to a string. All of
292 these functions add their new data to the
294 of the string. This is good, because programs usually build strings
295 left-to-right. If you want to do something more clever, that's up to
298 Several of these functions have equivalent macros which do the main work
299 inline. (There still might need to be a function call if the buffer
300 needs to be extended.)
302 Any of these functions might extend the string, causing pointers into
303 the string buffer to be invalidated. If you don't want that to happen,
304 pre-ensure enough space before you start.
306 The simplest function is
308 which appends a single character
310 to the end of the string. It has a macro equivalent called
315 places a zero byte at the end of the string. It does
317 affect the string's length, so any other data added to the string will
318 overwrite the null terminator. This is useful if you want to pass your
319 string to one of the standard C library string-handling functions. The
326 writes a C-style null-terminated string to the end of a dynamic string.
327 A terminating zero byte is also written, as if
329 were called. The macro
335 works similarly to the standard
337 function. It accepts a
339 format string and an arbitrary number of arguments to format and writes
340 the resulting text to the end of a dynamic string, returning the number
341 of characters so written. A terminating zero byte is also appended.
342 There is no macro equivalent of
347 provides access to the `guts' of
349 given a format string and a pointer to a
351 it will format the arguments according to the format string, just as
353 does. (Note: that's a
357 so that it gets updated properly on exit.)
363 functions are implemented using
365 The output operations table is exposed as
367 the functions expect the output pointer to be the address of the output
372 appends the contents of one dynamic string to another. A null
373 terminator is also appended. The macro
379 puts an arbitrary block of memory, addressed by
383 bytes, at the end of a dynamic string. No terminating null is appended:
384 it's assumed that if you're playing with arbitrary chunks of memory then
385 you're probably not going to be using the resulting data as a normal
386 text string. The macro
392 reads a line from an input stream
394 and appends it to a string. If an error occurs, or end-of-file is
395 encountered, before any characters have been read, then
399 and does not extend the string. Otherwise, it reads until it encounters
400 a newline character, an error, or end-of-file, and returns the number of
401 characters read. If reading was terminated by a newline character, the
404 inserted in the buffer. A terminating null is appended, as by
407 .SS "Other functions"
410 function writes a string to an output stream
412 It returns the number of characters written, or
414 if an error occurred before the first write. No newline character is
415 written to the stream, unless the string actually contains one already.
420 .\"--------------------------------------------------------------------------
421 .SH "SECURITY CONSIDERATIONS"
423 The implementation of the
425 functions is designed to do string handling in security-critical
426 programs. However, there may be bugs in the code somewhere. In
429 functions are quite complicated, and could do with some checking by
430 independent people who know what they're doing.
432 .\"--------------------------------------------------------------------------
439 .\"--------------------------------------------------------------------------
442 Mark Wooding, <mdw@distorted.org.uk>
444 .\"----- That's all, folks --------------------------------------------------
~mdw / mLib / blob