|
|
|
|
||
|
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.
|
||
|
|
|