.\" -*-nroff-*-
.de VS
.sp 1
-.RS 5
+.RS
.nf
.ft B
..
.RE
.sp 1
..
-.de HP
+.de hP
.IP
.ft B
\h'-\w'\\$1\ 'u'\\$1\ \c
..
.ie t .ds o \(bu
.el .ds o o
-.TH dstr 3mLib "8 May 1999" "mLib"
+.TH dstr 3 "8 May 1999" "mLib"
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
+.\"
+.\" @DCREATE
+.\" @DDESTROY
+.\" @DRESET
+.\" @DENSURE
+.\" @DPUTC
+.\" @DPUTZ
+.\" @DPUTS
+.\" @DPUTD
+.\" @DPUTM
+.\" @DWRITE
+.\"
.SH SYNOPSIS
.nf
.B "#include <mLib/dstr.h>"
.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 "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 "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 );
The following invariants are maintained by
.B dstr
and must hold when any function is called:
-.HP \*o
+.hP \*o
If
.B sz
is nonzero, then
is zero, then
.B buf
is a null pointer.
-.HP \*o
+.hP \*o
At all times,
.BI sz " >= " len\fR.
.PP
-Note that there is no equaivalent of the standard C distinction between
+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 nonexistant string (a null pointer). Any
+element is zero) and the nonexistent string (a null pointer). Any
.B dstr
whose
.B len
The caller is responsible for allocating the
.B dstr
structure. It can be initialized in any of the following ways:
-.HP \*o
+.hP \*o
Using the macro
.B DSTR_INIT
as an initializer in the declaration of the object.
-.HP \*o
+.hP \*o
Passing its address to the
.B dstr_create
function.
-.HP \*o
+.hP \*o
Passing its address to the (equivalent)
.B DCREATE
macro.
function empties a string
.I without
deallocating any memory. Therefore appending more characters is quick,
-beause the old buffer is still there and doesn't need to be allocated.
+because the old buffer is still there and doesn't need to be allocated.
Calling
.VS
dstr_reset(d);
.VE
-is equivalent to directly assinging
+is equivalent to directly assigning
.VS
d->len = 0;
.VE
isn't enough memory for a longer string, the exception
.B EXC_NOMEM
is raised. See
-.BR exc (3mLib)
+.BR exc (3)
for more information about
.BR mLib 's
exception handling system.
`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 braindamaged enough to
+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.)
.B dstr_putf
doesn't (and probably never will) understand the
.RB ` n$ '
-positional paramter notation accepted by many Unix C libraries. There
+positional parameter notation accepted by many Unix C libraries. There
is no macro equivalent of
.BR dstr_putf .
.PP
.B DWRITE
is equivalent.
.SH "SECURITY CONSIDERATIONS"
-The implemenetation of the
+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
.B dstr_putf
functions is 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@nsict.org>