.\" -*-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 darray 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-darray \- dense, dynamically resizing arrays
+.\"
+.\" Manual for dynamically growing arrays
+.\"
+.\" (c) 1999--2001, 2005, 2009, 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 darray 3mLib "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @DA_INIT
.\" @DA_DECL
.\" @DA_CREATE
.\" @da_ensure
.\" @da_shunt
.\" @da_tidy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+darray \- dense, dynamically resizing arrays
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/darray.h>"
.PP
.BI "void *da_shunt(da_base *" b ", void *" v ", size_t " sz ", size_t " n );
.BI "void *da_tidy(da_base *" b ", void *" v ", size_t " sz );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The
.B <mLib/darray.h>
header file declares a collection of types, macros and functions which
.PP
The macros described here may evaluate their arguments multiple times
unless otherwise specified.
+.
.SS "Creation and destruction"
Each element type must have its own array
type declared using the
Arrays may be disposed of using the
.B DA_DESTROY
macro, which again takes the address of the array.
+.
.SS "Storage allocation"
.PP
Space for new array elements may be reserved using the
accepts the address of an array. It reduces the length of the array to
zero. No storage is deallocated. Resetting arrays might not be a good
idea if the objects in the array are dynamically allocated.
+.
.SS "Accessing array elements"
If
.I a
unsigned (e.g., if it's based on
.BR DA_LEN ).
There are unsafe versions of both these macros too.
+.
.SS "Stack operations"
Dynamic arrays support Perl-like stack operations. Given an array
(pointer)
.B DA_LAST
are lvalues referring to the first and last elements in the array
respectively. They are unsafe if the array is empty.
+.
.SS "Low-level details"
This section describes low-level details of the dynamic array
implementation. You should try to avoid making use of this information
.TP
.B da_tidy
Reallocate the array to use the smallest amount of memory possible.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR exc (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------