.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:
whose
.B len
is zero is an empty string.
-.SH "CREATION AND DESTRUCTION"
+.SS "Creation and destruction"
The caller is responsible for allocating the
.B dstr
structure. It can be initialized in any of the following ways:
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
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
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