[@DEFINITION MODULE module;

(* Generic Double Ended Queue Template *)

(* ---------------------------------------------------------------------------

 * This template is expanded by the M 2 R 10? template engine utility. Expansion
 * can be invoked from within a compiling source file using the MAKE pragma:
 * <* MAKE = "m2te DEQ module:'Foo DEQ?' component:'Foo Record?'" *>
 * IMPORT Foo DEQ?;
 * ------------------------------------------------------------------------ *)

FROM Collections IMPORT Capacity, Status;

(* ---------------------------------------------------------------------------

 * Default queue size
 * ------------------------------------------------------------------------ *)

    defaultCapacity = 0;

(* ---------------------------------------------------------------------------

 * Maximum queue size
 * ------------------------------------------------------------------------ *)

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

(* ---------------------------------------------------------------------------

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

    invalidQueue = invalidCollection;
    queueEmpty = collectionEmpty;
    queueFull = collectionFull;

(* ---------------------------------------------------------------------------

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

    module = OPAQUE;

    Value Type? = component;

(* ---------------------------------------------------------------------------

 * Opaque handle type:  module.Iterator
 * ------------------------------------------------------------------------ *)

    Iterator = OPAQUE;

(* ---------------------------------------------------------------------------

 * function:  module.new ( status )
 * ---------------------------------------------------------------------------
 *
 * Creates  and returns a new queue object.  Returns  NIL  if the queue object
 * could not be created.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE new ( VAR status : Status ) : module;

(* ---------------------------------------------------------------------------

 * function:  module.prepend( queue, value, status )
 * ---------------------------------------------------------------------------
 *
 * Prepends  a new  entry <value>  at  the  head of <queue>.  The new entry is
 * added by reference,  no data is copied.  No entry is added if NIL is passed
 * in for <queue> or <value>.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE prepend ( queue : module; value : Value Type?; VAR status : Status );

(* ---------------------------------------------------------------------------

 * function:  module.append( queue, value, status )
 * ---------------------------------------------------------------------------
 *
 * Appends  a  new  entry <value>  at  the  tail of <queue>.  The new entry is
 * added by reference,  no data is copied.  No entry is added if NIL is passed
 * in for <queue> or <value>.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE append ( queue : module; value : Value Type?; VAR status : Status );

(* ---------------------------------------------------------------------------

 * function:  module.firstEntry( queue, status )
 * ---------------------------------------------------------------------------
 *
 * Removes  the first entry  from the head of <queue>  and returns it.  If the
 * queue is empty or NIL is passed in for <queue>,  then NIL is returned.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE firstEntry ( queue : module; VAR status : Status ) : Value Type?;

(* ---------------------------------------------------------------------------

 * function:  module.lastEntry( queue, status )
 * ---------------------------------------------------------------------------
 *
 * Removes  the last entry  from the tail of <queue>  and  returns it.  If the
 * queue is empty or NIL is passed in for <queue>,  then NIL is returned.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE lastEntry ( queue : module; VAR status : Status ) : Value Type?;

(* ---------------------------------------------------------------------------

 * function:  module.capacity( queue )
 * ---------------------------------------------------------------------------
 *
 * Returns the total capacity of queue <queue>,  returns zero if NIL is passed
 * in for <queue>. *)

PROCEDURE capacity ( queue : module ) : Capacity;

(* ---------------------------------------------------------------------------

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

PROCEDURE entryCount ( queue : module ) : Capacity;

(* ---------------------------------------------------------------------------

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

PROCEDURE isResizable ( queue : module ) : BOOLEAN;

(* ---------------------------------------------------------------------------

 * function:  module.newIterator ( queue, status )
 * ---------------------------------------------------------------------------
 *
 * Creates and returns  a new iterator object  for iterating entries  in queue
 * <queue>.  Returns NIL if <queue> is NIL or empty.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE newIterator ( queue : module; VAR status : Status ) : Iterator;

(* ---------------------------------------------------------------------------

 * function:  module.iterateNext( queue )
 * ---------------------------------------------------------------------------
 *
 * The  first  call  to this function  returns the  first  entry  of the queue
 * associated with <iterator>.  Subsequent calls return the queue's respective
 * successor entries.  Returns  NIL  if  any preceding call  returned the last
 * entry of the queue or if NIL is passed in for <iterator>.
 *
 * The status of the operation is passed back in <status>. *)

PROCEDURE iterateNext ( iterator : Iterator; VAR statusStatus ) : Value Type?;

(* ---------------------------------------------------------------------------

 * function:  module.disposeIterator ( iterator )
 * ---------------------------------------------------------------------------
 *
 * Disposes of iterator object <iterator> and returns NIL. *)

PROCEDURE disposeIterator ( VAR iterator : Iterator ) : Iterator;

(* ---------------------------------------------------------------------------

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

PROCEDURE dispose ( VAR queue : module ) : module;

END module.@]