1 .TH DYN 3M "15 March 1990"
4 dyn \- the C Dynamic Object library
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
14 and the necessary declarations to use them are in
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.
25 DynObject DynCreate(size, increment)
33 are greater than zero.
36 Creates a new DynObject that will store elements of size
38 and will allocate memory in blocks large enough to hold exactly
40 elements. For example, if you are storing 8-byte double
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
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.
51 returns the new DynObject, or NULL if there is insufficient memory.
62 Frees all memory associated with
64 The results of calling any Dyn function on a destroyed object are
65 undefined (except for DynCreate, which resets the object).
81 Adds the element pointed to by
85 resizing the object if necessary.
86 The new element becomes the last element in obj's array.
90 returns DYN_OK on success or DYN_NOMEM if there is insufficient
94 int DynInsert(obj, index, els, num)
106 elements, pointed to by
110 starting at the array location
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".
118 returns DYN_BADINDEX if
121 .BR DynSize ( obj ) ;
124 is less than 1; DYN_NOMEM if there is insufficient memory.
127 int DynGet(obj, index)
133 Returns the address of the element
137 This pointer can be treated as a normal array of the type specified to
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.
147 is larger than the number of elements in the array of less than zero.
150 int DynDelete(obj, index)
161 is deleted from the object
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.
169 will return DYN_OK on success or DYN_BADINDEX if the element
171 does not exist in the array or is less than zero.
179 Returns the number of elements in the object
188 Returns the index of the highest element in the object
192 is macro that expands to
202 Returns the index of the lowest element in the object
206 is macro that expands to 0.
209 int DynDebug(obj, state)
218 Sets the debugging state of
222 and prints a message on stderr saying what state debugging was set to.
223 Any non-zero value for
225 turns debugging ``on''. When debugging is on, all Dyn functions will
226 produce (hopefully useful) output to stderr describing what is going on.
232 Barr3y Jaspan, Student Information Processing Board (SIPB) and
233 MIT-Project Athena, bjaspan@athena.mit.edu