zephyr/libdyn/dyn.3

   1 .TH DYN 3M "15 March 1990"
   2
   3 .SH NAME
   4 dyn \- the C Dynamic Object library
   5
   6 .SH DESCRIPTION
   7
   8 A C Dynamic Object is an array that takes care of resizing
   9 itself as you add and delete elements from it.  It can be of any type
  10 for which sizeof is defined and for which an address of a variable of
  11 that type can be passed to a function.  The library containing the
  12 functions described below is called
  13 .IR libdyn.a ,
  14 and the necessary declarations to use them are in
  15 .RI < dyn.h >.
  16 .PP
  17 A DynObject is actually a structure that contains an array and a
  18 couple of integers to maintain necessary state information.  When a
  19 Dyn function is said to operate on "the object" or "the array", it is
  20 operating on the array stored in the structure while at the same time
  21 updating internal state information.
  22
  23 .SH LIST OF FUNCTIONS
  24 .nf
  25 DynObject DynCreate(size, increment)
  26         int size, increment;
  27 .fi
  28 .PP
  29 .IR Requires :
  30 .I size
  31 and
  32 .I increment
  33 are greater than zero.
  34 .PP
  35 .IR Effects :
  36 Creates a new DynObject that will store elements of size
  37 .I size
  38 and will allocate memory in blocks large enough to hold exactly
  39 .I increment
  40 elements.  For example, if you are storing 8-byte double
  41 precision numbers and
  42 .I increment
  43 is 5, each 5th element you add to the object will cause it to request
  44 40 more bytes (8 * 5) from the operating system.  If
  45 .I increment
  46 is zero, a default value is used (currently 100).  This is the only
  47 time the programmer deals with a dynamic object's memory allocation.
  48 .PP
  49 .IR Returns :
  50 .B DynCreate
  51 returns the new DynObject, or NULL if there is insufficient memory.
  52 .PP
  53 .nf
  54 int DynDestroy(obj)
  55         DynObject obj;
  56 .fi
  57 .PP
  58 .IR Modifies :
  59 obj
  60 .PP
  61 .IR Effects :
  62 Frees all memory associated with
  63 .IR obj .
  64 The results of calling any Dyn function on a destroyed object are
  65 undefined (except for DynCreate, which resets the object).
  66 .PP
  67 .IR Returns :
  68 .B DynDestroy
  69 returns DYN_OK.
  70 .PP
  71 .nf
  72 int DynAdd(obj, el)
  73         DynObject obj;
  74         DynPtr el;
  75 .fi
  76 .PP
  77 .IR Modifies :
  78 obj
  79 .PP
  80 .IR Effects :
  81 Adds the element pointed to by
  82 .I el
  83 to the object
  84 .IR obj ,
  85 resizing the object if necessary.
  86 The new element becomes the last element in obj's array.
  87 .PP
  88 .IR Returns :
  89 .B DynAdd
  90 returns DYN_OK on success or DYN_NOMEM if there is insufficient
  91 memory.
  92 .PP
  93 .nf
  94 int DynInsert(obj, index, els, num)
  95         DynObject obj;
  96         DynPtr els;
  97         int index, num;
  98 .fi
  99 .PP
 100 .IR Modifies :
 101 obj
 102 .PP
 103 .IR Effects :
 104 Inserts the array of
 105 .I num
 106 elements, pointed to by
 107 .IR els,
 108 into the object
 109 .I obj
 110 starting at the array location
 111 .IR index ,
 112 resizing the object if necessary.  Order is preserved; if you have the
 113 array "1 2 3 4 5" and insert "10 11 12" at the third position, you
 114 will have the array "1 2 10 11 12 3 4 5".
 115 .PP
 116 .IR Returns :
 117 .B DynInsert
 118 returns DYN_BADINDEX if
 119 .I index
 120 is not between 0 and
 121 .BR DynSize ( obj ) ;
 122 DYN_BADVALUE if
 123 .I num
 124 is less than 1; DYN_NOMEM if there is insufficient memory.
 125 .PP
 126 .nf
 127 int DynGet(obj, index)
 128         DynObject obj;
 129         int index;
 130 .fi
 131 .PP
 132 .IR Effects :
 133 Returns the address of the element
 134 .I index
 135 in the array of
 136 .IR obj .
 137 This pointer can be treated as a normal array of the type specified to
 138 .BR DynCreate .
 139 The order of elements in this array is the order in which they were
 140 added to the object.  The returned pointer is guaranteed to be valid
 141 only until obj is modified.
 142 .PP
 143 .IR Returns :
 144 .B DynGet
 145 returns NULL if
 146 .I index
 147 is larger than the number of elements in the array of less than zero.
 148 .PP
 149 .nf
 150 int DynDelete(obj, index)
 151         DynObject obj;
 152         int index;
 153 .fi
 154 .PP
 155 .IR Modifies :
 156 obj
 157 .PP
 158 .IR Effects :
 159 The element
 160 .I index
 161 is deleted from the object
 162 .IR obj .
 163 Note that the element is actually removed permanently from the array.
 164 If you have the array "1 2 3 4 5" and delete the third element, you
 165 will have the array "1 2 4 5".  The order of elements in not affected.
 166 .PP
 167 .IR Returns :
 168 .B DynDelete
 169 will return DYN_OK on success or DYN_BADINDEX if the element
 170 .I index
 171 does not exist in the array or is less than zero.
 172 .PP
 173 .nf
 174 int DynSize(obj)
 175         DynObject obj;
 176 .fi
 177 .PP
 178 .IR Effects :
 179 Returns the number of elements in the object
 180 .IR obj .
 181 .PP
 182 .nf
 183 int DynHigh(obj)
 184         DynObject obj;
 185 .fi
 186 .PP
 187 .IR Effects :
 188 Returns the index of the highest element in the object
 189 .IR obj .
 190 In this version,
 191 .B DynHigh
 192 is macro that expands to
 193 .B DynSize
 194 - 1.
 195 .PP
 196 .nf
 197 int DynLow(obj)
 198         DynObject obj;
 199 .fi
 200 .PP
 201 .IR Effects :
 202 Returns the index of the lowest element in the object
 203 .IR obj .
 204 In this version,
 205 .B DynLow
 206 is macro that expands to 0.
 207 .PP
 208 .nf
 209 int DynDebug(obj, state)
 210         DynObject obj;
 211         int state;
 212 .fi
 213 .PP
 214 .IR Modifies :
 215 obj
 216 .PP
 217 .IR Effects :
 218 Sets the debugging state of
 219 .I obj
 220 to
 221 .I state
 222 and prints a message on stderr saying what state debugging was set to.
 223 Any non-zero value for
 224 .I state
 225 turns debugging ``on''.  When debugging is on, all Dyn functions will
 226 produce (hopefully useful) output to stderr describing what is going on.
 227 .PP
 228 .IR Returns :
 229 .B DynDebug
 230 returns DYN_OK.
 231 .SH AUTHOR
 232 Barr3y Jaspan, Student Information Processing Board (SIPB) and
 233 MIT-Project Athena, bjaspan@athena.mit.edu