@@@ much mess, mostly manpages

[mLib] / struct / dstr.3.in

.\" -*-nroff-*-
.\"
.\" Manual for dynamic strings
.\"
.\" (c) 1999--2003, 2005, 2007, 2009, 2013, 2014, 2023, 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 dstr 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @dstr_create
.\" @dstr_destroy
.\" @dstr_reset
.\" @dstr_ensure
.\" @dstr_tidy
.
.\" @dstr_putc
.\" @dstr_putz
.\" @dstr_puts
.\" @dstr_putf
.\" @dstr_vputf
.\" @dstr_printops
.\" @dstr_putd
.\" @dstr_putm
.\" @dstr_putline
.\" @dstr_write
.
.\" @DSTR_INIT
.\" @DCREATE
.\" @DDESTROY
.\" @DRESET
.\" @DENSURE
.\" @DPUTC
.\" @DPUTZ
.\" @DPUTS
.\" @DPUTD
.\" @DPUTM
.\" @DWRITE
.
.\"--------------------------------------------------------------------------
.SH NAME
dstr \- a simple dynamic string type
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/dstr.h>"
.PP
.B "typedef struct { ...\& } dstr;"
.B "#define DSTR_INIT ..."
.PP
.BI "void dstr_create(dstr *" d );
.BI "void dstr_destroy(dstr *" d );
.BI "void dstr_reset(dstr *" d );
.PP
.BI "void dstr_ensure(dstr *" d ", size_t " sz );
.BI "void dstr_tidy(dstr *" d );
.PP
.BI "void dstr_putc(dstr *" d ", int " ch );
.BI "void dstr_putz(dstr *" d );
.BI "void dstr_puts(dstr *" d ", const char *" s );
.BI "int dstr_vputf(dstr *" d ", va_list *" ap );
.BI "int dstr_putf(dstr *" d ", ...);"
.BI "void dstr_putd(dstr *" d ", const dstr *" p );
.BI "void dstr_putm(dstr *" d ", const void *" p ", size_t " sz );
.BI "int dstr_putline(dstr *" d ", FILE *" fp );
.BI "size_t dstr_write(const dstr *" d ", FILE *" fp );
.PP
.BI "void DCREATE(dstr *" d );
.BI "void DDESTROY(dstr *" d );
.BI "void DRESET(dstr *" d );
.BI "void DENSURE(dstr *" d ", size_t " sz );
.BI "void DPUTC(dstr *" c ", char " ch );
.BI "void DPUTZ(dstr *" d );
.BI "void DPUTS(dstr *" d ", const char *" s );
.BI "void DPUTD(dstr *" d ", const dstr *" p );
.BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
.BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
.fi
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The header
.B dstr.h
declares a type for representing dynamically extending strings, and a
small collection of useful operations on them.  None of the operations
returns a failure result on an out-of-memory condition; instead, the
exception
.B EXC_NOMEM
is raised.
.PP
Many of the functions which act on dynamic strings have macro
equivalents.  These equivalent macros may evaluate their arguments
multiple times.
.
.SS "Underlying type"
A
.B dstr
object is a small structure with the following members.
The
.B buf
member points to the actual character data in the string.  The data may
or may not be null terminated, depending on what operations have
recently been performed on it.  None of the
.B dstr
functions depend on the string being null-terminated; indeed, all of
them work fine on strings containing arbitrary binary data.  You can
force null-termination by calling the
.B dstr_putz
function, or the
.B DPUTZ
macro.
.PP
The
.B sz
member describes the current size of the buffer.  This reflects the
maximum possible length of string that can be represented in
.B buf
without allocating a new buffer.
.PP
The
.B len
member describes the current length of the string.  It is the number of
bytes in the string which are actually interesting.  The length does
.I not
include a null-terminating byte, if there is one.
.PP
The following invariants are maintained by
.B dstr
and must hold when any function is called:
.hP \*o
If
.B sz
is nonzero, then
.B buf
points to a block of memory of length
.BR sz .
If
.B sz
is zero, then
.B buf
is a null pointer.
.hP \*o
At all times,
.BR sz " \(>= " len.
.PP
Note that there is no equivalent of the standard C distinction between
the empty string (a pointer to an array of characters whose first
element is zero) and the nonexistent string (a null pointer).  Any
.B dstr
whose
.B len
is zero is an empty string.
.PP
The
.I a
member refers to the arena from which the string's buffer has been
allocated.  Immediately after creation, this is set to be
.BR arena_stdlib (3);
you can set it to point to any other arena of your choice before the
buffer is allocated.
.
.SS "Creation and destruction"
The caller is responsible for allocating the
.B dstr
structure.  It can be initialized:
.hP \*o
using the macro
.B DSTR_INIT
as an initializer in the declaration of the object,
.hP \*o
passing its address to the
.B dstr_create
function, or
.hP \*o
passing its address to the (equivalent)
.B DCREATE
macro.
.PP
The initial value of a
.B dstr
is the empty string.
.PP
The additional storage space for a string's contents may be reclaimed by
passing it to the
.B dstr_destroy
function, or the
.B DDESTROY
macro.  After destruction, a string's value is reset to the empty
string:
.I "it's still a valid"
.BR dstr .
However, once a string has been destroyed, it's safe to deallocate the
underlying
.B dstr
object.
.PP
The
.B dstr_reset
function empties a string
.I without
deallocating any memory.  Therefore appending more characters is quick,
because the old buffer is still there and doesn't need to be allocated.
Calling
.VS
dstr_reset(d);
.VE
is equivalent to directly assigning
.VS
d->len = 0;
.VE
There's also a macro
.B DRESET
which does the same job as the
.B dstr_reset
function.
.
.SS "Extending a string"
All memory allocation for strings is done by the function
.BR dstr_ensure .
Given a pointer
.I d
to a
.B dstr
and a size
.IR sz ,
the function ensures that there are at least
.I sz
unused bytes in the string's buffer.  The current algorithm for
extending the buffer is fairly unsophisticated, but seems to work
relatively well \- see the source if you really want to know what it's
doing.
.PP
Extending a string never returns a failure result.  Instead, if there
isn't enough memory for a longer string, the exception
.B EXC_NOMEM
is raised.  See
.BR exc (3)
for more information about
.BR mLib 's
exception handling system.
.PP
Note that if an ensure operation needs to reallocate a string buffer,
any pointers you've taken into the string become invalid.
.PP
There's a macro
.B DENSURE
which does a quick inline check to see whether there's enough space in
a string's buffer.  This saves a procedure call when no reallocation
needs to be done.  The
.B DENSURE
macro is called in the same way as the
.B dstr_ensure
function.
.PP
The function
.B dstr_tidy
`trims' a string's buffer so that it's just large enough for the string
contents and a null terminating byte.  This might raise an exception due
to lack of memory.  (There are two possible ways this might happen.
Firstly, the underlying allocator might just be brain-damaged enough to
fail on reducing a block's size.  Secondly, tidying an empty string with no
buffer allocated for it causes allocation of a buffer large enough for
the terminating null byte.)
.
.SS "Contributing data to a string"
There are a collection of functions which add data to a string.  All of
these functions add their new data to the
.I end
of the string.  This is good, because programs usually build strings
left-to-right.  If you want to do something more clever, that's up to
you.
.PP
Several of these functions have equivalent macros which do the main work
inline.  (There still might need to be a function call if the buffer
needs to be extended.)
.PP
Any of these functions might extend the string, causing pointers into
the string buffer to be invalidated.  If you don't want that to happen,
pre-ensure enough space before you start.
.PP
The simplest function is
.B dstr_putc
which appends a single character
.I ch
to the end of the string.  It has a macro equivalent called
.BR DPUTC .
.PP
The function
.B dstr_putz
places a zero byte at the end of the string.  It does
.I not
affect the string's length, so any other data added to the string will
overwrite the null terminator.  This is useful if you want to pass your
string to one of the standard C library string-handling functions.  The
macro
.B DPUTZ
does the same thing.
.PP
The function
.B dstr_puts
writes a C-style null-terminated string to the end of a dynamic string.
A terminating zero byte is also written, as if
.B dstr_putz
were called.  The macro
.B DPUTS
does the same job.
.PP
The function
.B dstr_putf
works similarly to the standard
.BR sprintf (3)
function.  It accepts a
.BR print (3)-style
format string and an arbitrary number of arguments to format and writes
the resulting text to the end of a dynamic string, returning the number
of characters so written.  A terminating zero byte is also appended.
There is no macro equivalent of
.BR dstr_putf .
.PP
The function
.B dstr_vputf
provides access to the `guts' of
.BR dstr_putf :
given a format string and a pointer to a
.BR va_list
it will format the arguments according to the format string, just as
.B dstr_putf
does.  (Note: that's a
.BR "va_list *" ,
not a plain
.BR va_list ,
so that it gets updated properly on exit.)
.PP
The
.B dstr_putf
and
.B dstr_vputf
functions are implemented using
.BR gprintf (3).
The output operations table is exposed as
.BR dstr_printops ;
the functions expect the output pointer to be the address of the output
.BR dstr 
.PP
The function
.B dstr_putd
appends the contents of one dynamic string to another.  A null
terminator is also appended.  The macro
.B DPUTD
does the same thing.
.PP
The function
.B dstr_putm
puts an arbitrary block of memory, addressed by
.IR p ,
with length
.I sz
bytes, at the end of a dynamic string.  No terminating null is appended:
it's assumed that if you're playing with arbitrary chunks of memory then
you're probably not going to be using the resulting data as a normal
text string.  The macro
.B DPUTM
works the same way.
.PP
The function
.B dstr_putline
reads a line from an input stream
.I fp
and appends it to a string.  If an error occurs, or end-of-file is
encountered, before any characters have been read, then
.B dstr_putline
returns the value
.B EOF
and does not extend the string.  Otherwise, it reads until it encounters
a newline character, an error, or end-of-file, and returns the number of
characters read.  If reading was terminated by a newline character, the
newline character is
.I not
inserted in the buffer.  A terminating null is appended, as by
.BR dstr_putz .
.
.SS "Other functions"
The
.B dstr_write
function writes a string to an output stream
.IR fp .
It returns the number of characters written, or
.B 0
if an error occurred before the first write.  No newline character is
written to the stream, unless the string actually contains one already.
The macro
.B DWRITE
is equivalent.
.
.\"--------------------------------------------------------------------------
.SH "SECURITY CONSIDERATIONS"
.
The implementation of the
.B dstr
functions is designed to do string handling in security-critical
programs.  However, there may be bugs in the code somewhere.  In
particular, the
.B dstr_putf
functions are quite complicated, and could do with some checking by
independent people who know what they're doing.
.
.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
.
.BR exc (3),
.BR gprintf (3),
.BR mLib (3).
.
.\"--------------------------------------------------------------------------
.SH AUTHOR
.
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------