ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE DLists;

  (*******************************************************************

    Module  DLists     (Version 1.0)

      Copyright (c) 1993-2006 by Juerg Thoeny and ETH Zurich.

    Purpose   Handling of dynamic lists.

    Remarks   Every List has the following attributes:

              Size: The Size of the user's items.  The module
              takes care of the allocation and deallocation of
              the items in the list.

              Direction: The direction in which a given
              operation on the list will be performed.  The
              direction is either from the head to the tail
              or vice versa.

              Relation: The relation between two items in
              the form R(item1, item2) = BOOLEAN This
              relation is used by the operations AddItem and
              Sort.  AddItem inserts an new item before an
              existing item (direction) if the relation
              yields TRUE.

              Current Item: The current item is set by
              AddItem, SetCurrItem, InsertItem, and
              AdvanceItem.  If a current item is deleted it
              will be set to to the next one depending on the
              current direction.

              NOTE: AddItem and InsertItem will always
              allocate memory and store a copy the contents of
              the Item.  Therefore you should always use
              ADR(YourItem).  With GetItem you receive the
              pointer to your item so you should use pointer^
              to access your item.


    Programming

      o Design
        Juerg Thoeny              13/10/1993

      o Implementation
        Juerg Thoeny              13/10/1993


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  13/10/1993  JT

  *******************************************************************)


  FROM SYSTEM IMPORT
    ADDRESS;

  TYPE
    DListHandle;

    Relation = PROCEDURE(ADDRESS, ADDRESS) : BOOLEAN;
    Selector = PROCEDURE(ADDRESS) : BOOLEAN;
    ItemProc = PROCEDURE(ADDRESS);


  (*======================= Declaration ================================*)
  PROCEDURE NewDList       (    itemSize    : LONGINT;
                                fromHead    : BOOLEAN;
                            VAR dListHandle : DListHandle) : BOOLEAN;
  (* Creates a new DList.                                                            *)
  (* IN : itemSize : Size of the Items in the List                                   *)
  (*      fromHead : The direction, in which the operations will be applied          *)
  (*                 to the List. (i.e. from Head or Tail                            *)
  (* OUT : dListHandle : A handle to the new List                                    *)
  (* RETURNS : FALSE if an error ocoured.                                            *)

  PROCEDURE DeleteDList    (VAR dListHandle : DListHandle);
  (* Deletes a list and all containing Items.                                        *)
  (* IN : dListHandle : Handle to the list to be deleted                             *)

  PROCEDURE DListSize      (    dListHandle : DListHandle;
                            VAR numItems    : LONGINT)     : BOOLEAN;
  (* Calculates the number of elements in the List.                                  *)
  (* IN : dListHandle : Handle to the list                                           *)
  (* OUT : numItems : Number of Items in the List                                    *)
  (* RETURNS : FALSE if dListHandle is not valid                                     *)



  (*======================= Attributes ================================*)
  PROCEDURE SetDirection   (    dListHandle : DListHandle;
                                fromHead    : BOOLEAN);
  (* Changes the direction of the List.                                              *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      fromHead : The direction, in which the operations will be applied          *)
  (*                 to the List. (i.e. from Head or Tail                            *)

  PROCEDURE GetDirection   (    dListHandle : DListHandle;
                            VAR fromHead    : BOOLEAN)    : BOOLEAN;
  (* Retrieves the direction of the List.                                              *)
  (* IN : dListHandle : Handle to the list                                           *)
  (* OUT : fromHead : The direction, in which the operations will be applied         *)
  (*                  to the List. (i.e. from Head or Tail). IF GetDirection returns *)
  (*                  FALSE fromHead is set to TRUE                                  *)
  (* RETURNS : FALSE if dListHandle is not valid                                     *)

  PROCEDURE SetRelation    (    dListHandle : DListHandle;
                                relation    : Relation);
  (* The AddItem and SortDList Operations will use the relation to perform the       *)
  (* operations. AddItem will insert Items before item where                         *)
  (*             relation(item, newItem) yields TRUE                                 *)
  (* The default relation yields always FALSE                                        *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      relation : The new list relation                                           *)

  PROCEDURE GetRelation    (    dListHandle : DListHandle;
                            VAR relation    : Relation);
  (* Retrieves the current releation.                                                *)
  (* IN : dListHandle : Handle to the list                                           *)
  (* OUT : relation : The current list relation                                      *)


  PROCEDURE DeleteRelation (    dListHandle : DListHandle);
  (* Sets the default relation.                                                      *)
  (* IN : dListHandle : Handle to the list                                           *)




  (*======================= Item Adding and Removal ================================*)
  PROCEDURE AddItem        (    dListHandle : DListHandle;
                                item        : ADDRESS)     : BOOLEAN;
  (* Adds an Item to the List using the current direction and relation               *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      item : address of the useritem. The contence is copied to an allocated     *)
  (*             space. The contence is not touched.                                 *)
  (* RETURNS : FALSE if dListHandle is not valid or no memory available              *)

  PROCEDURE InsertItem     (    dListHandle : DListHandle;
                                item        : ADDRESS)     : BOOLEAN;
  (* Inserts an Item in the List after the current Item using the current direction  *)
  (* The current relation is not evaluated                                           *)
  (* If the list is empty, the item will be added to the list                        *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      item : address of the useritem. The contence is copied to an allocated     *)
  (*             space. The contence is not touched.                                 *)
  (* RETURNS : FALSE if dListHandle is not valid or no memory available              *)

  PROCEDURE DeleteFirstItem(    dListHandle : DListHandle) : BOOLEAN;
  (* Deletes the first Item in the List using the current direction                  *)
  (* IN : dListHandle : Handle to the list                                           *)
  (* RETURNS : FALSE if dListHandle is not valid or no items exists                  *)

  PROCEDURE DeleteCurrItem (    dListHandle : DListHandle) : BOOLEAN;
  (* Deletes the current Item in the List                                            *)
  (* IN : dListHandle : Handle to the list                                           *)
  (* RETURNS : FALSE if dListHandle is not valid or no items exists                  *)



  (*======================= Item access ================================*)
  PROCEDURE GetFirstItem   (    dListHandle : DListHandle;
                            VAR item        : ADDRESS)     : BOOLEAN;
  (* Retrieves the first Item in the List corresponding to the direction             *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      item : address of the useritem. The contence is not copied.                *)
  (* RETURNS : FALSE if dListHandle is not valid or no items exists                  *)

  PROCEDURE SetCurrItem    (    dListHandle : DListHandle;
                                fromCurrent : BOOLEAN;
                                selector    : Selector)    : BOOLEAN;
  (* Sets the current Item so that selector(item) = TRUE                             *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      fromCurrent : IF TRUE the lookup starts from the current item, IF FALSE    *)
  (*                    it starts from the begining                                  *)
  (*      selector : The selector, which will be used for this operation.            *)
  (* RETURNS : FALSE if dListHandle is not valid or no items with                    *)
  (*           selector(item) = TRUE exists                                          *)

  PROCEDURE GetCurrItem    (    dListHandle : DListHandle;
                            VAR item        : ADDRESS)     : BOOLEAN;
  (* Retrieves the current Item in the List                                          *)
  (* IN : dListHandle : Handle to the list                                           *)
  (* RETURNS : FALSE if dListHandle is not valid or no items exists                  *)

  PROCEDURE AdvanceItem    (    dListHandle : DListHandle;
                            VAR item        : ADDRESS)     : BOOLEAN;
  (* Advances the current item to the next using the current direction               *)
  (* and returns the new current Item                                                *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      item : address of the useritem. The contence is not copied.                *)
  (* RETURNS : FALSE if dListHandle is not valid or no next items exists             *)


  (*======================= List Processing ================================*)
  PROCEDURE DoForAll       (    dListHandle : DListHandle;
                                itemProc    : ItemProc);
  (* Calls the procedure itemProc for every item in the List.                        *)
  (* IN : dListHandle : Handle to the list                                           *)
  (*      item : the procedure which will be called for every item  .                *)

  PROCEDURE SortDList      (    dListHandle : DListHandle);
  (* Sorts the list using the current direction and the current relation             *)
  (* IN : dListHandle : Handle to the list                                           *)

END DLists.


  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]