.\" -*-nroff-*-
.de VS
.sp 1
-.RS 5
+.RS
.nf
.ft B
..
..
.ie t .ds o \(bu
.el .ds o o
-.TH dstr 3 "8 May 1999" "mLib"
+.TH dstr 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
dstr \- a simple dynamic string type
.\" @dstr_create
.\" @dstr_destroy
.\" @dstr_putline
.\" @dstr_write
.\"
+.\" @DSTR_INIT
.\" @DCREATE
.\" @DDESTROY
.\" @DRESET
.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 "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 DPUTM(dstr *" d ", const void *" p ", size_t " sz );
.BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
.fi
-.SH SUMMARY
+.SH DESCRIPTION
The header
.B dstr.h
declares a type for representing dynamically extending strings, and a
Many of the functions which act on dynamic strings have macro
equivalents. These equivalent macros may evaluate their arguments
multiple times.
-.SH "UNDERLYING TYPE"
+.SS "Underlying type"
A
.B dstr
object is a small structure with the following members:
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
is a null pointer.
.hP \*o
At all times,
-.BI sz " >= " len\fR.
+.BR sz " \(>= " len.
.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
is zero is an empty string.
-.SH "CREATION AND DESTRUCTION"
+.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 in any of the following ways:
+structure. It can be initialized:
.hP \*o
-Using the macro
+using the macro
.B DSTR_INIT
-as an initializer in the declaration of the object.
+as an initializer in the declaration of the object,
.hP \*o
-Passing its address to the
+passing its address to the
.B dstr_create
-function.
+function, or
.hP \*o
-Passing its address to the (equivalent)
+passing its address to the (equivalent)
.B DCREATE
macro.
.PP
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
which does the same job as the
.B dstr_reset
function.
-.SH "EXTENDING A STRING"
+.SS "Extending a string"
All memory allocation for strings is done by the function
.BR dstr_ensure .
Given a pointer
`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.)
-.SH "CONTRIBUTING DATA TO A STRING"
+.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
.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 dstr_vputf
provides access to the `guts' of
.BR dstr_putf :
-given a format string and a
-.B va_list
-pointer, it will format the arguments according to the format string,
-just as
+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.
+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
encountered, before any characters have been read, then
.B dstr_putline
returns the value
-.BR EOF.
-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
+.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 .
-.SH "OTHER FUNCTIONS"
+.SS "Other functions"
The
.B dstr_write
function writes a string to an output stream
.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
particular, the
.B dstr_putf
-functions is quite complicated, and could do with some checking by
+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),
~mdw / mLib / blobdiff