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.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib