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 describing what is going on on
233
Barr3y Jaspan, Student Information Processing Board (SIPB) and
234
MIT-Project Athena, bjaspan@athena.mit.edu