.\" -*-nroff-*-
.\"
.\" Manual for buffer extension
.\"
.\" (c) 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH growbuf 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @GROWBUF_SIZE
.\" @GROWBUF_EXTEND
.\" @GROWBUF_REPLACE
.\" @GROWBUF_RENEWV
.\" @GROWBUF_REPLACEV
.
.\"--------------------------------------------------------------------------
.SH NAME
growbuf \- extend buffers efficiently
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/growbuf.h>"
.PP
.ta \w'\fBvoid GROWBUF_SIZE('u
.BI "void GROWBUF_SIZE(" type ", " type " &" sz ", " type " " want ,
.BI "	" type " " init ", " type " " granule ");"
.PP
.ta \w'\fBvoid GROWBUF_EXTEND('u
.BI "\fBvoid GROWBUF_EXTEND(" type ", arena *" a ", " type " *&" buf ,
.BI "	" type " &" sz ", " type " " want ,
.BI "	" type " " init ", " type " " granule ");"
.ta \w'\fBvoid GROWBUF_REPLACE('u
.BI "\fBvoid GROWBUF_REPLACE(" type ", arena *" a ", " type " *&" buf ,
.BI "	" type " &" sz ", " type " " want ,
.BI "	" type " " init ", " type " " granule ");"
.PP
.ta \w'\fBvoid GROWBUF_RENEWV('u
.BI "\fBvoid GROWBUF_RENEWV(" type ", arena *" a ", " type " *&" buf ,
.BI "	" type " &" sz ", " type " " want ", " type " " init ");"
.ta \w'\fBvoid GROWBUF_REPLACEV('u
.BI "\fBvoid GROWBUF_REPLACEV(" type ", arena *" a ", " type " *&" buf ,
.BI "	" type " &" sz ", " type " " want ", " type " " init ");"
.fi
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B "<mLib/growbuf.h>"
header file defines macros useful for dynamically resizing buffers.
.PP
The situation envisaged is a buffer, at address
.IR buf ,
with space to hold
.I sz
objects each of size
.IR granule ;
but it has become necessary to store
.I want
objects in the buffer.
If the current size
.I sz
is zero, then the buffer pointer
.I buf
may be null;
otherwise, it is assumed to have been allocated from the arena
.IR a .
The size
.I init
is a suggested minimal nonzero size, again counting objects of size
.IR granule .
.PP
The
.B GROWBUF_SIZE
macro merely adjusts
.I sz
so that it is at least as large as
.IR want ;
it is
.I assumed
on entry that
.IR sz "\ <\ " want ;
nothing especially terrible will happen if this is not the case,
but unnecessary work will take place,
and
.I sz
will be left nonzero if it was previously zero,
even if
.IR want "\ =\ 0."
.B GROWBUF_SIZE
arranges to increase buffer sizes in a geometric progression
so as to minimize reallocation and copying overheads \(en
the number of reallocations will be
at most logarithmic in the final size
and each byte is copied an (amortized) constant number of times.
.PP
The
.B GROWBUF_EXTEND
macro will additionally resize the buffer,
preserving its contents,
and adjusting
.I buf
to point to its new location;
if
.I want
\(<=
.I sz
then nothing happens.
The
.B GROWBUF_REPLACE
macro is similar, except that it
.I discards
the existing buffer contents if the buffer needs to be adjusted.
.PP
The
.B GROWBUF_RENEWV
macro is the same as
.B GROWBUF_EXTEND
except that it implicitly uses
.BI "sizeof(*" buf )
as its
.IR granule ;
the
.B GROWBUF_REPLACEV
macro is similarly like
.BR GROWBUF_REPLACE .
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR arena (3),
.BR mLib (3).
.
.\"--------------------------------------------------------------------------
.SH AUTHOR
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------