DYN(3M)DYN(3M)NAMEdyn - the C Dynamic Object library
DESCRIPTION
A C Dynamic Object is an array that takes care of resizing
itself as you add and delete elements from it. It can be
of any type for which sizeof is defined and for which an
address of a variable of that type can be passed to a
function. The library containing the functions described
below is called libdyn.a, and the necessary declarations
to use them are in <dyn.h>.
A DynObject is actually a structure that contains an array
and a couple of integers to maintain necessary state
information. When a Dyn function is said to operate on
"the object" or "the array", it is operating on the array
stored in the structure while at the same time updating
internal state information.
LIST OF FUNCTIONS
DynObject DynCreate(size, increment)
int size, increment;
Requires: size and increment are greater than zero.
Effects: Creates a new DynObject that will store elements
of size size and will allocate memory in blocks large
enough to hold exactly increment elements. For example,
if you are storing 8-byte double precision numbers and
increment is 5, each 5th element you add to the object
will cause it to request 40 more bytes (8 * 5) from the
operating system. If increment is zero, a default value
is used (currently 100). This is the only time the pro-
grammer deals with a dynamic object's memory allocation.
Returns: DynCreate returns the new DynObject, or NULL if
there is insufficient memory.
int DynDestroy(obj)
DynObject obj;
Modifies: obj
Effects: Frees all memory associated with obj. The
results of calling any Dyn function on a destroyed object
are undefined (except for DynCreate, which resets the
object).
Returns: DynDestroy returns DYN_OK.
int DynAdd(obj, el)
DynObject obj;
DynPtr el;
Modifies: obj
Effects: Adds the element pointed to by el to the object
obj, resizing the object if necessary. The new element
becomes the last element in obj's array.
Returns: DynAdd returns DYN_OK on success or DYN_NOMEM if
there is insufficient memory.
int DynInsert(obj, index, els, num)
DynObject obj;
DynPtr els;
int index, num;
Modifies: obj
Effects: Inserts the array of num elements, pointed to by
els, into the object obj starting at the array location
index, resizing the object if necessary. Order is pre-
served; if you have the array "1 2 3 4 5" and insert "10
11 12" at the third position, you will have the array "1 2
10 11 12 3 4 5".
Returns: DynInsert returns DYN_BADINDEX if index is not
between 0 and DynSize(obj); DYN_BADVALUE if num is less
than 1; DYN_NOMEM if there is insufficient memory.
int DynGet(obj, index)
DynObject obj;
int index;
Effects: Returns the address of the element index in the
array of obj. This pointer can be treated as a normal
array of the type specified to DynCreate. The order of
elements in this array is the order in which they were
added to the object. The returned pointer is guaranteed
to be valid only until obj is modified.
Returns: DynGet returns NULL if index is larger than the
number of elements in the array of less than zero.
int DynDelete(obj, index)
DynObject obj;
int index;
Modifies: obj
Effects: The element index is deleted from the object obj.
Note that the element is actually removed permanently from
the array. If you have the array "1 2 3 4 5" and delete
the third element, you will have the array "1 2 4 5". The
order of elements in not affected.
Returns: DynDelete will return DYN_OK on success or
DYN_BADINDEX if the element index does not exist in the
array or is less than zero.
int DynSize(obj)
DynObject obj;
Effects: Returns the number of elements in the object obj.
int DynHigh(obj)
DynObject obj;
Effects: Returns the index of the highest element in the
object obj. In this version, DynHigh is macro that
expands to DynSize - 1.
int DynLow(obj)
DynObject obj;
Effects: Returns the index of the lowest element in the
object obj. In this version, DynLow is macro that expands
to 0.
int DynDebug(obj, state)
DynObject obj;
int state;
Modifies: obj
Effects: Sets the debugging state of obj to state and
prints a message on stderr saying what state debugging was
set to. Any non-zero value for state turns debugging
``on''. When debugging is on, all Dyn functions will pro-
duce (hopefully useful) output describing what is going on
on stderr.
Returns: DynDebug returns DYN_OK.
AUTHOR
Barr3y Jaspan, Student Information Processing Board (SIPB)
and MIT-Project Athena, bjaspan@athena.mit.edu
15 March 1990 DYN(3M)