Initial revision

1 files changed, 198 insertions, 0 deletions

diff --git a/libdyn/dyn.3m b/libdyn/dyn.3m
new file mode 100644
index 0000000..21ae70b
--- /dev/null
+++ b/libdyn/dyn.3m
@@ -0,0 +1,198 @@
+
+
+
+15 March 1990                                             DYN(3M)
+
+
+
+NAME
+     dyn - 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 func-
+     tion.  The library containing the functions described below
+     is called _l_i_b_d_y_n._a, and the necessary declarations to use
+     them are in <_d_y_n._h>.
+
+     A DynObject is actually a structure that contains an array
+     and a couple of integers to maintain necessary state infor-
+     mation.  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;
+
+     _R_e_q_u_i_r_e_s: _s_i_z_e and _i_n_c_r_e_m_e_n_t are greater than zero.
+
+     _E_f_f_e_c_t_s: Creates a new DynObject that will store elements of
+     size _s_i_z_e and will allocate memory in blocks large enough to
+     hold exactly _i_n_c_r_e_m_e_n_t elements.  For example, if you are
+     storing 8-byte double precision numbers and _i_n_c_r_e_m_e_n_t 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
+     _i_n_c_r_e_m_e_n_t is zero, a default value is used (currently 100).
+     This is the only time the programmer deals with a dynamic
+     object's memory allocation.
+
+     _R_e_t_u_r_n_s: DynCreate returns the new DynObject, or NULL if
+     there is insufficient memory.
+
+     int DynDestroy(obj)
+          DynObject obj;
+
+     _M_o_d_i_f_i_e_s: obj
+
+     _E_f_f_e_c_t_s: Frees all memory associated with _o_b_j.  The results
+     of calling any Dyn function on a destroyed object are unde-
+     fined (except for DynCreate, which resets the object).
+
+     _R_e_t_u_r_n_s: DynDestroy returns DYN_OK.
+
+
+
+
+
+                                                                1
+
+
+
+
+
+
+DYN(3M)                                             15 March 1990
+
+
+
+     int DynAdd(obj, el)
+          DynObject obj;
+          DynPtr el;
+
+     _M_o_d_i_f_i_e_s: obj
+
+     _E_f_f_e_c_t_s: Adds the element pointed to by _e_l to the object
+     _o_b_j, resizing the object if necessary.  The new element
+     becomes the last element in obj's array.
+
+     _R_e_t_u_r_n_s: 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;
+
+     _M_o_d_i_f_i_e_s: obj
+
+     _E_f_f_e_c_t_s: Inserts the array of _n_u_m elements, pointed to by
+     _e_l_s, into the object _o_b_j starting at the array location
+     _i_n_d_e_x, resizing the object if necessary.  Order is
+     preserved; 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".
+
+     _R_e_t_u_r_n_s: DynInsert returns DYN_BADINDEX if _i_n_d_e_x is not
+     between 0 and DynSize(obj); DYN_BADVALUE if _n_u_m is less than
+     1; DYN_NOMEM if there is insufficient memory.
+
+     int DynGet(obj, index)
+          DynObject obj;
+          int index;
+
+     _E_f_f_e_c_t_s: Returns the address of the element _i_n_d_e_x in the
+     array of _o_b_j.  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.
+
+     _R_e_t_u_r_n_s: DynGet returns NULL if _i_n_d_e_x is larger than the
+     number of elements in the array of less than zero.
+
+     int DynDelete(obj, index)
+          DynObject obj;
+          int index;
+
+     _M_o_d_i_f_i_e_s: obj
+
+
+
+
+
+2
+
+
+
+
+
+
+15 March 1990                                             DYN(3M)
+
+
+
+     _E_f_f_e_c_t_s: The element _i_n_d_e_x is deleted from the object _o_b_j.
+     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.
+
+     _R_e_t_u_r_n_s: DynDelete will return DYN_OK on success or
+     DYN_BADINDEX if the element _i_n_d_e_x does not exist in the
+     array or is less than zero.
+
+     int DynSize(obj)
+          DynObject obj;
+
+     _E_f_f_e_c_t_s: Returns the number of elements in the object _o_b_j.
+
+     int DynHigh(obj)
+          DynObject obj;
+
+     _E_f_f_e_c_t_s: Returns the index of the highest element in the
+     object _o_b_j.  In this version, DynHigh is macro that expands
+     to DynSize - 1.
+
+     int DynLow(obj)
+          DynObject obj;
+
+     _E_f_f_e_c_t_s: Returns the index of the lowest element in the
+     object _o_b_j.  In this version, DynLow is macro that expands
+     to 0.
+
+     int DynDebug(obj, state)
+          DynObject obj;
+          int state;
+
+     _M_o_d_i_f_i_e_s: obj
+
+     _E_f_f_e_c_t_s: Sets the debugging state of _o_b_j to _s_t_a_t_e and prints
+     a message on stderr saying what state debugging was set to.
+     Any non-zero value for _s_t_a_t_e turns debugging ``on''.  When
+     debugging is on, all Dyn functions will produce (hopefully
+     useful) output to stderr describing what is going on.
+
+     _R_e_t_u_r_n_s: DynDebug returns DYN_OK.
+
+AUTHOR
+     Barr3y Jaspan, Student Information Processing Board (SIPB)
+     and MIT-Project Athena, bjaspan@athena.mit.edu
+
+
+
+
+
+
+
+
+
+                                                                3
+
+
+