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