DEFINITION MODULE @@module@@;

(* Generic Dynamic Array Template *)

(* ---------------------------------------------------------------------------
 * This template is expanded by the M2R10 template engine utility. Expansion
 * can be invoked from within a compiling source file using the MAKE pragma:
 * <* MAKE = "m2te DynamicArray module:'FooArray' component:'FooRecord'" *>
 * IMPORT FooArray;
 * ------------------------------------------------------------------------ *)


FROM Collections IMPORT Capacity, Status;


CONST

(* ---------------------------------------------------------------------------
 * Default array size
 * ------------------------------------------------------------------------ *)

    defaultCapacity = 256;  (* 256 entries *)


(* ---------------------------------------------------------------------------
 * Maximum array size
 * ------------------------------------------------------------------------ *)

    maximumCapacity = 1024*1024*1024;  (* more than 1 billion entries *)


(* ---------------------------------------------------------------------------
 * Synonyms for status codes
 * ------------------------------------------------------------------------ *)

    invalidArray = invalidCollection;
    arrayFull = collectionFull;


TYPE

(* ---------------------------------------------------------------------------
 * Opaque handle type:  @@module@@
 * ------------------------------------------------------------------------ *)

    @@module@@ = OPAQUE;

    ValueType = @@component@@;

    IndexType = ALIAS OF CARDINAL32;


(* ---------------------------------------------------------------------------
 * function:  @@module@@.new( initialSize, status )
 * ---------------------------------------------------------------------------
 *
 * Creates and returns a new @@module@@ object  with an initial capacity of
 * <initialSize>.  If  zero  is passed in  for <initialSize>,  then  the array
 * will be created with an initial capacity of @@module@@.defaultStackSize.
 * The function fails if a value greater than @@module@@.maximumStackSize
 * is  passed in for <initialSize> or if memory could not be allocated.
 *
 * The initial capacity of an array is the number of entries that can be
 * stored in the array without enlargement.
 *
 * The status of the operation  is passed back in <status>. *)

PROCEDURE new ( initialSize : Capacity; VAR status : Status ) : @@module@@;


(* ---------------------------------------------------------------------------
 * function:  @@module@@.storeEntry( array, index, value, status )
 * ---------------------------------------------------------------------------
 *
 * Stores <value>  in <array>  at <index>.  If <index> is  out of range of the
 * current capacity of <array>,  then <array>  will be  enlarged  accordingly.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE storeEntry ( array  : @@module@@;
                       index  : IndexType;
                       value  : ValueType;
                   VAR status : Status );


(* ---------------------------------------------------------------------------
 * function:  @@module@@.valueAtIndex( array, index, status )
 * ---------------------------------------------------------------------------
 *
 * Returns the value stored in <array> at <index>.  If <index> is out of range
 * of the current capacity of <array> then NIL is returned.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE valueForKey ( tree   : @@module@@;
                        index  : IndexType;
                    VAR status : Status ) : ValueType;


(* ---------------------------------------------------------------------------
 * function:  @@module@@.capacity( array )
 * ---------------------------------------------------------------------------
 *
 * Returns the current capacity of <stack>.  The current capacity is the total
 * number of allocated entries.  Returns zero if NIL is passed in for <stack>.
 *)
PROCEDURE capacity ( VAR array : @@module@@ ) : Capacity;


(* ---------------------------------------------------------------------------
 * function:  @@module@@.entryCount( stack )
 * ---------------------------------------------------------------------------
 *
 * Returns  the  number of entries  stored in array <array>,  returns  zero if
 * NIL is passed in for <array>. *)

PROCEDURE entryCount ( VAR array : @@module@@ ) : Capacity;


(* ---------------------------------------------------------------------------
 * function:  @@module@@.isResizable( array )
 * ---------------------------------------------------------------------------
 *
 * Returns TRUE  if the  capacity of <array> can change after <array> has been
 * instatiated,  returns FALSE otherwise. *)

PROCEDURE isResizable ( array : @@module@@ ) : BOOLEAN;


(* ---------------------------------------------------------------------------
 * function:  @@module@@.dispose( array )
 * ---------------------------------------------------------------------------
 *
 * Disposes of array object <array> and returns NIL. *)

PROCEDURE dispose ( VAR array : @@module@@ ) : @@module@@;


END @@module@@.