~mdw / mLib / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Add global unihash table; use universal hashing instead of CRC.
[mLib] / man / darray.3
diff --git a/man/darray.3 b/man/darray.3
index 76b0ced..db50fd1 100644 (file)
--- a/man/darray.3
+++ b/man/darray.3
@@ -19,7 +19,7 @@
 ..
 .ie t .ds o \(bu
 .el .ds o o
 ..
 .ie t .ds o \(bu
 .el .ds o o
-.TH darray 3 "21 October 1999" mLib
+.TH darray 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
 .SH "NAME"
 darray \- dense, dynamically resizing arrays
 .\" @DA_INIT
 .SH "NAME"
 darray \- dense, dynamically resizing arrays
 .\" @DA_INIT
@@ -29,6 +29,7 @@ darray \- dense, dynamically resizing arrays
 .\" @DA_ENSURE
 .\" @DA_SHUNT
 .\" @DA_TIDY
 .\" @DA_ENSURE
 .\" @DA_SHUNT
 .\" @DA_TIDY
+.\" @DA_RESET
 .\" @DA
 .\" @DA_LEN
 .\" @DA_SPARE
 .\" @DA
 .\" @DA_LEN
 .\" @DA_SPARE
@@ -38,6 +39,12 @@ darray \- dense, dynamically resizing arrays
 .\" @DA_UNSAFE_EXTEND
 .\" @DA_SLIDE
 .\" @DA_UNSAFE_SLIDE
 .\" @DA_UNSAFE_EXTEND
 .\" @DA_SLIDE
 .\" @DA_UNSAFE_SLIDE
+.\" @DA_SHRINK
+.\" @DA_UNSAFE_SHRINK
+.\" @DA_UNSLIDE
+.\" @DA_UNSAFE_UNSLIDE
+.\" @DA_FIRST
+.\" @DA_LAST
 .\" @DA_PUSH
 .\" @DA_POP
 .\" @DA_UNSHIFT
 .\" @DA_PUSH
 .\" @DA_POP
 .\" @DA_UNSHIFT
@@ -51,29 +58,38 @@ darray \- dense, dynamically resizing arrays
 .nf
 .B "#include <mLib/darray.h>"
 
 .nf
 .B "#include <mLib/darray.h>"
 
-.BI DA_DECL( atype ", " type );
-.IB atype " " a " = DA_INIT;"
-.BI "void DA_CREATE(" atype " *" a );
-.BI "void DA_DESTROY(" atype " *" a );
+.BI DA_DECL( type_v ", " type );
+.IB type_v " " a " = DA_INIT;"
+.BI "void DA_CREATE(" type_v " *" a );
+.BI "void DA_DESTROY(" type_v " *" a );
 
 
-.BI "void DA_ENSURE(" atype " *" a ", size_t " n );
-.BI "void DA_SHUNT(" atype " *" a ", size_t " n );
-.BI "void DA_TIDY(" atype " *" a );
+.BI "void DA_ENSURE(" type_v " *" a ", size_t " n );
+.BI "void DA_SHUNT(" type_v " *" a ", size_t " n );
+.BI "void DA_TIDY(" type_v " *" a );
+.BI "void DA_RESET(" type_v " *" a );
 
 
-.IB type " *DA(" atype " *" a );
-.BI "size_t DA_LEN(" atype " *" a );
-.BI "size_t DA_SPARE(" atype " *" a );
-.BI "size_t DA_OFFSET(" atype " *" a );
-.BI "void DA_INCLUDE(" atype " *" a ", size_t " i );
-.BI "void DA_EXTEND(" atype " *" a ", long " n );
-.BI "void DA_UNSAFE_EXTEND(" atype " *" a ", long " n );
-.BI "void DA_SLIDE(" atype " *" a ", long " n );
-.BI "void DA_UNSAFE_SLIDE(" atype " *" a ", long " n );
+.IB type " *DA(" type_v " *" a );
+.BI "size_t DA_LEN(" type_v " *" a );
+.BI "size_t DA_SPARE(" type_v " *" a );
+.BI "size_t DA_OFFSET(" type_v " *" a );
+.BI "void DA_INCLUDE(" type_v " *" a ", size_t " i );
 
 
-.BI "void DA_PUSH(" atype " *" a ", " type " " x );
-.IB type " DA_POP(" atype " *" a );
-.BI "void DA_UNSHIFT(" atype " *" a ", " type " " x );
-.IB type " DA_SHIFT(" atype " *" a );
+.BI "void DA_EXTEND(" type_v " *" a ", long " n );
+.BI "void DA_SHRINK(" type_v " *" a ", long " n );
+.BI "void DA_SLIDE(" type_v " *" a ", long " n );
+.BI "void DA_UNSLIDE(" type_v " *" a ", long " n );
+
+.BI "void DA_UNSAFE_EXTEND(" type_v " *" a ", long " n );
+.BI "void DA_UNSAFE_SHRINK(" type_v " *" a ", long " n );
+.BI "void DA_UNSAFE_SLIDE(" type_v " *" a ", long " n );
+.BI "void DA_UNSAFE_UNSLIDE(" type_v " *" a ", long " n );
+
+.IB type " DA_FIRST(" type_v " *" a );
+.IB type " DA_LAST(" type_v " *" a );
+.BI "void DA_PUSH(" type_v " *" a ", " type " " x );
+.IB type " DA_POP(" type_v " *" a );
+.BI "void DA_UNSHIFT(" type_v " *" a ", " type " " x );
+.IB type " DA_SHIFT(" type_v " *" a );
 
 .BI "void *da_ensure(da_base *" b ", void *" v ", size_t " sz ", size_t " n );
 .BI "void *da_shunt(da_base *" b ", void *" v ", size_t " sz ", size_t " n );
 
 .BI "void *da_ensure(da_base *" b ", void *" v ", size_t " sz ", size_t " n );
 .BI "void *da_shunt(da_base *" b ", void *" v ", size_t " sz ", size_t " n );
@@ -82,8 +98,8 @@ darray \- dense, dynamically resizing arrays
 .SH "DESCRIPTION"
 The
 .B <mLib/darray.h>
 .SH "DESCRIPTION"
 The
 .B <mLib/darray.h>
-declares a collection of types, macros and functions which implement
-dynamically resizing arrays.
+header file declares a collection of types, macros and functions which
+implement dynamically resizing arrays.
 .PP
 The macros described here may evaluate their arguments multiple times
 unless otherwise specified.
 .PP
 The macros described here may evaluate their arguments multiple times
 unless otherwise specified.
@@ -93,19 +109,31 @@ type declared using the
 .B DA_DECL
 macro.  Calling
 .VS
 .B DA_DECL
 macro.  Calling
 .VS
-.BI DA_DECL( atype ", " type );
+.BI DA_DECL( type_v ", " type );
 .VE
 Declares a new dynamic array type
 .VE
 Declares a new dynamic array type
-.I atype
+.I type_v
 whose elements have type
 .IR type .
 .PP
 whose elements have type
 .IR type .
 .PP
+It is conventional to form the name of an array type by appending
+.RB ` _v '
+to the base type name.  If the base type is a standard type, or is
+declared separately from the array, it's also conventional to declare a
+macro with the same name as the array type only in uppercase which may
+be used to prevent multiple declarations, e.g.,
+.VS
+#ifndef FOO_V
+#  define FOO_V
+   DA_DECL(foo_v, foo);
+#endif
+.VE
 The macro
 .B DA_INIT
 is a valid static initializer for all types of dynamic arrays.  For
 cases where this isn't appropriate, a dynamic array may be initialized
 using the macro
 The macro
 .B DA_INIT
 is a valid static initializer for all types of dynamic arrays.  For
 cases where this isn't appropriate, a dynamic array may be initialized
 using the macro
-.BR DA_INIT ,
+.BR DA_CREATE ,
 passing it the address of the array.
 .PP
 Arrays may be disposed of using the
 passing it the address of the array.
 .PP
 Arrays may be disposed of using the
@@ -140,6 +168,12 @@ The macro
 takes one argument: the address of a dynamic array.  It minimizes the
 amount of memory used by the array.  This is a useful function to call
 when the array's size has finally settled down.
 takes one argument: the address of a dynamic array.  It minimizes the
 amount of memory used by the array.  This is a useful function to call
 when the array's size has finally settled down.
+.PP
+The macro
+.B DA_RESET
+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
 .SS "Accessing array elements"
 If
 .I a
@@ -149,7 +183,7 @@ is the base address of the actual array.  The elements are stored
 contiguously starting at this address.  An element at index
 .I i
 may be referenced using the syntax
 contiguously starting at this address.  An element at index
 .I i
 may be referenced using the syntax
-.BI DA( a )[ i \fR.
+.BI DA( a )[ i ]\fR.
 .PP
 The number of elements in the array
 .I a
 .PP
 The number of elements in the array
 .I a
@@ -242,6 +276,20 @@ is thrown if
 The macro
 .B DA_UNSAFE_SLIDE
 does the same job, only without the error checking.
 The macro
 .B DA_UNSAFE_SLIDE
 does the same job, only without the error checking.
+.PP
+The macros
+.B DA_SHRINK
+and
+.B DA_UNSLIDE
+do the same things as
+.B DA_EXTEND
+and
+.B DA_SLIDE
+respectively, except that they interpret the sign of their second
+arguments in the opposite way.  This is useful if the argument is
+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)
 .SS "Stack operations"
 Dynamic arrays support Perl-like stack operations.  Given an array
 (pointer)
@@ -285,6 +333,13 @@ and
 can fail because the array is empty, in which case
 .B DAEXC_UFLOW
 is thrown.
 can fail because the array is empty, in which case
 .B DAEXC_UFLOW
 is thrown.
+.PP
+The operations
+.B DA_FIRST
+and
+.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
 .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
@@ -294,10 +349,10 @@ miss.
 .PP
 Dynamic arrays are structures with the format
 .VS
 .PP
 Dynamic arrays are structures with the format
 .VS
-.BI "typedef struct " atype " {"
+.BI "typedef struct " type_v " {"
 .B "  da_base b;"
 .BI "  " type " *v;"
 .B "  da_base b;"
 .BI "  " type " *v;"
-.BI "} " atype ";"
+.BI "} " type_v ";"
 .VE
 The pointer
 .B v
 .VE
 The pointer
 .B v
mLib utilities library