2 .TH growbuf 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
8 growbuf \- extend buffers efficiently
12 .B "#include <mLib/growbuf.h>"
14 .BI "GROWBUF_SIZE(size_t " sz ", size_t " want ", " \c
15 .BI "size_t " init ", size_t " granule ");"
17 .ds mT \fBGROWBUF_EXTEND(
18 .BI "\*(mTarena *" a ", " type " *" buf ", size_t " sz ", size_t " want ","
19 .BI "\h'\w'\*(mT'u'size_t " init ", size_t " granule ");"
20 .ds mT \fBGROWBUF_REPLACE(
21 .BI "\*(mTarena *" a ", " type " *" buf ", size_t " sz ", size_t " want ","
22 .BI "\h'\w'\*(mT'u'size_t " init ", size_t " granule ");"
28 header file defines macros useful for dynamically resizing buffers.
30 The situation envisaged is a buffer, at address
36 but it has become necessary to store
38 objects in the buffer.
41 is zero, then the buffer pointer
44 otherwise, it is assumed to have been allocated from the arena
48 is a suggested minimal nonzero size, again counting objects of size
55 so that it is at least as large as
61 nothing especially terrible will happen if this is not the case,
62 but unnecessary work will take place,
65 will be left nonzero if it was previously zero,
69 arranges to increase buffer sizes in a geometric progression
70 so as to minimize reallocation and copying overheads \(en
71 the number of reallocations will be
72 at most logarithmic in the final size
73 and each byte is copied an (amortized) constant number of times.
77 macro will additionally resize the buffer,
78 preserving its contents,
81 to point to its new location;
89 macro is similar, except that it
91 the existing buffer contents if the buffer needs to be adjusted.
98 Mark Wooding, <mdw@distorted.org.uk>