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

DEFINITION MODULE TableHandler;

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

    Module  TableHandler     (Version 1.0)

      Copyright (c) 1987-2006 by Olivier Roth, Andreas Fischlin, Frank
      Thommen and ETH Zurich.

    Purpose   Tabulate strings in alphabetically sorted order.

    Remarks   Based on a module from N. Wirth, "Programming
              in Modula-2", Springer, 1983 (2nd ed.).


    Programming

      o Design
        Olivier Roth              19/01/1987
        Andreas Fischlin          15/08/1988

      o Implementation
        Olivier Roth              19/01/1987
        Andreas Fischlin          15/08/1988
        Frank Thommen             18/03/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:  05/05/1998  AF

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


  FROM SYSTEM IMPORT ADDRESS;
  FROM DMStrings IMPORT String;


  TYPE
    Table;
    TableItem = Table;
    RealPtr = POINTER TO REAL;
    ProcPtr = POINTER TO ADDRESS;
    ItemProc = PROCEDURE ( TableItem );


  VAR
    notExistingTable: Table;     (* read only for initialization *)
    notExistingItem: TableItem;  (* read only for initialization *)
    errcode     : CARDINAL;
    (* 0   -> no error occured
       1   -> table (=notExistingTable) involved in operation
       2   -> table full
       3   -> procedure execution denied (called during traversing tree)
       4   -> attempt to record with a t in branch instead of the same t
              as used while calling InitTable
       5   -> garbage collection failed because of too long identifiers
              (current limit 1024 characters)
       6   -> table item has already been previously recorded (only
              returned by routine RecordRealAndGetStr)
    *)


  PROCEDURE InitTable( VAR t: Table );
    (* initializes table t (no effect when traversing) *)

  PROCEDURE DeleteTable( VAR t: Table );
    (* deletes table t and frees allocated memory (no effect when
       traversing). *)

  PROCEDURE TableExists(t: Table): BOOLEAN;
    (* returns TRUE if table t exists. *)


  PROCEDURE RecordReal(t: Table; VAR id: ARRAY OF CHAR; VAR r: REAL; attr: ADDRESS);
    (* enter id,r,attr in table t (overrides old r if id already in table!);
       no effect when traversing *)

  PROCEDURE RecordProc(t: Table; VAR id: ARRAY OF CHAR; p: ProcPtr; attr: ADDRESS);
    (* enter id,p,attr in table t (overrides old p if id already in table!);
       no effect when traversing *)

  PROCEDURE RecordRealAndGetStr(t: Table; VAR id: ARRAY OF CHAR; VAR r: REAL; attr: ADDRESS;
                                VAR str: String);
    (* same as RecordReal, but returns the recorded string reference associated
       with identifier id, making an subsequent, possibly costly call to
       procedure FindStr unnecessary. There is another important difference:
       In case the identifier id has already been recorded previously, that
       entry won't be changed (str is still returned fully) and errcode
       is set to the value 6.  This behavior may be exploited to enhance
       efficiency, because it can make a preceeding call such as FindReal
       superfluous.  The latter is necessary in a context where a
       duplicate recording is forbidden and the first entry ought to be
       protected from overwriting.  Fails while traversing *)

  PROCEDURE DeleteItem(VAR t: Table; VAR id: ARRAY OF CHAR);
    (* removes string id from table; no effect when traversing.
       IMPLEMENTATION RESTRICTION: Deleting does not simply delete
       items, but may change addresses of recorded, still valid items.
       Thus, you MUST NOT remember the values of items (TableItem) by
       means of procedure FindTableItem (see below) or while traversing
       trees (see below TraverseTree), or you might get completely
       unpredictable results.  *)


  PROCEDURE FindRealPtr(t: Table; VAR id: ARRAY OF CHAR): RealPtr;
    (* returns the RealPtr associated with string id in table t.
       returns NIL if not found; fails while traversing. *)

  PROCEDURE FindReal(t: Table; VAR id: ARRAY OF CHAR): REAL;
    (* returns the real value associated with string id in table t.
       returns NaN if not found; fails while traversing. *)


  PROCEDURE FindProcPtr(t: Table; VAR id: ARRAY OF CHAR): ProcPtr;
    (* returns the ProcPtr associated with string id in table t.
       returns NIL if not found; fails while traversing. *)


  PROCEDURE FindAttribute(t: Table; VAR id: ARRAY OF CHAR): ADDRESS;
    (* returns the attribute associated with string id in table t,
       returns NIL if not found; fails while traversing. *)

  PROCEDURE FindRealPtrAndAttr(t: Table; VAR id: ARRAY OF CHAR;
                               VAR rp: RealPtr): ADDRESS;
    (* returns the RealPtr plus attribute associated with string id
       in table t, returns NIL if not found; fails while traversing. *)

  PROCEDURE FindStr (t: Table; VAR id: ARRAY OF CHAR): String;
    (* returns the String reference associated with identifier id
       in table t, returns notAllocatedStr from DMStrings if not found;
       NOTE: In contrast to the TableItem at which an entry into a table
       is recorded, you may remember the string reference, it won't
       change, even if you delete items in the table (see also comment
       of procedure DeleteItem above or FindTableItem below).
       Fails while traversing.  *)


  PROCEDURE FindTableItem (t: Table; VAR id: ARRAY OF CHAR): TableItem;
    (* Returns the TableItem at which string id is currently
       stored in table t; returns NIL if id is not in table t.
       WARNING/IMPLEMENTATION RESTRICTION: Don't remember the
       returned value, since any restructuring of t, e.g.  by
       recording or deleting items in the table may change all
       TableItem values.  They are only useful temporarily,
       typically to call immediately afterwards one of the
       procedures requiring a TableItem as argument (see
       below). Fails while traversing. *)


  (* The following procedures are usefull in combination with
     procedure TraverseTree, and FindTableItem: *)

  PROCEDURE ShowItemString( item: TableItem; VAR id: ARRAY OF CHAR);
    (* gets the string stored in the actual table item.
       ! assumes that item is correct! *)

  PROCEDURE ItemValue  ( item: TableItem ): REAL;
  PROCEDURE ItemRealPtr( item: TableItem ): RealPtr;
  PROCEDURE ItemProcPtr( item: TableItem ): ProcPtr;
  PROCEDURE ItemAttr   ( item: TableItem ): ADDRESS;
  PROCEDURE ItemStr    ( item: TableItem ): String;
    (* returns respectively the value, procPtr or attr stored with
       the actual table item.
       ! assumes that item is correct! *)

  PROCEDURE TraverseTree( startAt: TableItem; doWithItem: ItemProc );
    (* traverses (sub-)tree starting with item startAt and
    performs procedure doWithItem for every item found *)


END TableHandler.