--- /dev/null
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.de hP
+.IP
+.ft B
+\h'-\w'\\$1\ 'u'\\$1\ \c
+.ft P
+..
+.ie t .ds o \(bu
+.el .ds o o
+.TH dstr 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+dstr \- a simple dynamic string type
+.\" @dstr_create
+.\" @dstr_destroy
+.\" @dstr_reset
+.\" @dstr_ensure
+.\" @dstr_tidy
+.\"
+.\" @dstr_putc
+.\" @dstr_putz
+.\" @dstr_puts
+.\" @dstr_putf
+.\" @dstr_putd
+.\" @dstr_putm
+.\" @dstr_putline
+.\" @dstr_write
+.\"
+.\" @DSTR_INIT
+.\" @DCREATE
+.\" @DDESTROY
+.\" @DRESET
+.\" @DENSURE
+.\" @DPUTC
+.\" @DPUTZ
+.\" @DPUTS
+.\" @DPUTD
+.\" @DPUTM
+.\" @DWRITE
+.\"
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/dstr.h>"
+
+.BI "void dstr_create(dstr *" d );
+.BI "void dstr_destroy(dstr *" d );
+.BI "void dstr_reset(dstr *" d );
+
+.BI "void dstr_ensure(dstr *" d ", size_t " sz );
+.BI "void dstr_tidy(dstr *" d );
+
+.BI "void dstr_putc(dstr *" d ", char " 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 );
+
+.BI "dstr " d " = DSTR_INIT;"
+.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:
+.VS
+typedef struct dstr {
+ char *buf; /* Pointer to string buffer */
+ size_t sz; /* Size of the buffer */
+ size_t len; /* Length of the string */
+ arena *a; /* Pointer to arena */
+} dstr;
+.VE
+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.
+The formatting is intended to be convenient and safe rather than
+efficient, so don't expect blistering performance. Similarly, there may
+be differences between the formatting done by
+.B dstr_putf
+and
+.BR sprintf (3)
+because the former has to do most of its work itself. In particular,
+.B dstr_putf
+doesn't (and probably never will) understand the
+.RB ` n$ '
+positional parameter notation accepted by many Unix C libraries. 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 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 mLib (3).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / mLib / blobdiff