From bcb999855c5f4ba7084c71fadbc30026792d892d Mon Sep 17 00:00:00 2001
From: mdw <mdw>
Date: Fri, 5 Nov 1999 14:33:14 +0000
Subject: [PATCH] Argument naming changes.  Describe naming conventions for
 array types.

---
 man/darray.3 | 70 +++++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 41 insertions(+), 29 deletions(-)

diff --git a/man/darray.3 b/man/darray.3
index 548299b..c5d9366 100644
--- a/man/darray.3
+++ b/man/darray.3
@@ -56,36 +56,36 @@ darray \- dense, dynamically resizing arrays
 .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_RESET(" 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 );
+.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_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_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(" 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_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 );
 
-.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_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 );
@@ -105,13 +105,25 @@ type declared using the
 .B DA_DECL
 macro.  Calling
 .VS
-.BI DA_DECL( atype ", " type );
+.BI DA_DECL( type_v ", " type );
 .VE
 Declares a new dynamic array type
-.I atype
+.I type_v
 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
@@ -325,10 +337,10 @@ miss.
 .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;"
-.BI "} " atype ";"
+.BI "} " type_v ";"
 .VE
 The pointer
 .B v
-- 
2.11.0