SRETCHY BUFFERS - expanding buffer routines
---------------

The stretchy buffer library is designed to allow an easy interface to
buffers that "grow" to fit data as it is stuffed into them. Since the
various object attributes may be of varying sizes, some form of clean
interface with a modicum of memory-leak control wa necessary.

Stretchy buffers will quietly resize themselves to fit data as it is
put into them with
sbuf_put()
and may make some attempt to downsize the backing buffer when it is
reset. Typically a routine that is reading a bunch of variable-sized
lines will allocate a single Sbuf at the beginning of the function,
and fill it, reset it, fill it, and reset it as needed. Buffer size
statistics are gathered, and are used to cause re-allocation of
statistically larger than average buffers.

Stretchy buffers can be dynamically allocated with
Sbuf *sbuf_new()
and freed with
void sbuf_free()
which respectively allocate and free stretchy buffers. Statically declared
stretchy buffers can be used, but need to be initialized first with
void sbuf_initstatic()
which normalizes internal pointers, and
void sbuf_freestatic()
which deallocates the dynamic parts of a static stretchy buffer.

Stretchy buffers grow in fairly small increments to avoid memory wastage,
but do block their growth reasonably efficiently. If your system has a
remotely reasonable implementation of a memory allocator, the stretchy
buffers will prove to be very efficient, easy-to-use tools.

Stretchy buffers handle errors rather inelegantly - by marking themselves
as bad - and permitting more data to be placed into them, which is then
neatly discarded.

mjr. '91