New array adjustment macros for unsigned arguments.

[mLib] / man / darray.3

diff --git a/man/darray.3 b/man/darray.3
index 76b0cedcc1f1b3f7d5c3c61344a0defcc3d43f7f..548299b589ec9902f364d54a8a8e20b91b1baef3 100644 (file)
--- a/man/darray.3
+++ b/man/darray.3
@@ -29,6 +29,7 @@ darray \- dense, dynamically resizing arrays
 .\" @DA_ENSURE
 .\" @DA_SHUNT
 .\" @DA_TIDY
+.\" @DA_RESET
 .\" @DA
 .\" @DA_LEN
 .\" @DA_SPARE
@@ -38,6 +39,10 @@ darray \- dense, dynamically resizing arrays
 .\" @DA_UNSAFE_EXTEND
 .\" @DA_SLIDE
 .\" @DA_UNSAFE_SLIDE
+.\" @DA_SHRINK
+.\" @DA_UNSAFE_SHRINK
+.\" @DA_UNSLIDE
+.\" @DA_UNSAFE_UNSLIDE
 .\" @DA_PUSH
 .\" @DA_POP
 .\" @DA_UNSHIFT
@@ -59,16 +64,23 @@ darray \- dense, dynamically resizing arrays
 .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_RESET(" atype " *" 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_SHRINK(" atype " *" a ", long " n );
 .BI "void DA_SLIDE(" atype " *" a ", long " n );
+.BI "void DA_UNSLIDE(" atype " *" a ", long " n );
+
+.BI "void DA_UNSAFE_EXTEND(" atype " *" a ", long " n );
+.BI "void DA_UNSAFE_SHRINK(" atype " *" a ", long " n );
 .BI "void DA_UNSAFE_SLIDE(" atype " *" a ", long " n );
+.BI "void DA_UNSAFE_UNSLIDE(" atype " *" a ", long " n );
 
 .BI "void DA_PUSH(" atype " *" a ", " type " " x );
 .IB type " DA_POP(" atype " *" a );
@@ -140,6 +152,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.
+.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
@@ -242,6 +260,19 @@ is thrown if
 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 unsafed versions of both these macros too.
 .SS "Stack operations"
 Dynamic arrays support Perl-like stack operations.  Given an array
 (pointer)