DEFINITION MODULE DiscrSpaces;
(*******************************************************************
Module DiscrSpaces (Version 1.0)
Copyright (c) 1998-2006 by Dimitrios Gyalistras, Andreas Fischlin
and ETH Zurich.
Purpose Management of discrete spaces spanned by
user-defined basis vectors (dimensions).
Remarks --
Programming
o Design
Dimitrios Gyalistras 15/04/1998
Andreas Fischlin 15/04/1998
o Implementation
Dimitrios Gyalistras 15/04/1998
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 DG
*******************************************************************)
FROM SYSTEM IMPORT ADDRESS;
IMPORT DMLanguage;
(**************************************)
(*##### General declarations #####*)
(**************************************)
CONST
DiscrSpacesOffset = DMLanguage.userBase + 720;
allOk = DMLanguage.allOk;
discreteSpaceNotKnown = DiscrSpacesOffset + 1;
discreteSpaceNotAvailable = DiscrSpacesOffset + 2;
atLeastOneDimEleRequired = DiscrSpacesOffset + 3;
atLeastOneDimRequired = DiscrSpacesOffset + 4;
dimensionDoesNotExist = DiscrSpacesOffset + 5;
dimensionUsedMoreThanOnce = DiscrSpacesOffset + 6;
illegalTuple = DiscrSpacesOffset + 7;
(*
For further error codes returned by this module see
module TableLists.
*)
TYPE
DiscreteSpace;
Dimension;
DiscreteSpaceAttribute = ADDRESS;
DimensionAttribute = ADDRESS;
DiscreteSpaceRemoveHandler = PROCEDURE( DiscreteSpaceAttribute );
DimensionRemoveHandler = PROCEDURE( DimensionAttribute );
VAR
unknownDiscreteSpace : DiscreteSpace; (* read only *)
unknownDimension : Dimension; (* read only *)
CONST
identDelim = "|"; (* delimiter used to separate identifiers in a list *)
(****************************)
(*##### Dimensions #####*)
(****************************)
(*----------------------------------------*)
(*===== Management of Dimensions =====*)
(*----------------------------------------*)
PROCEDURE CreateDimension( VAR dim : Dimension;
dimId : ARRAY OF CHAR;
eleIds : ARRAY OF CHAR;
VAR resCode : INTEGER );
(*
This routine creates a dimension with identifier
dimId, e.g. "TreeSpecies", and elements as listed
in eleIds (e.g., eleIds = "fir|oak|..."). Within a
given dimension each element must be unique, but
the same element can be used in several dimensions.
You may create any number of dimensions which can
then be used to define discrete spaces.
*)
PROCEDURE DimensionExists( dimId : ARRAY OF CHAR ): BOOLEAN;
PROCEDURE GetDimensionId( dim : Dimension;
VAR dimId : ARRAY OF CHAR );
PROCEDURE NumDimensionEles( VAR dimId : ARRAY OF CHAR ): INTEGER;
PROCEDURE GetFirstDimension( VAR dimId : ARRAY OF CHAR );
PROCEDURE GetPrevDimension ( curDimId : ARRAY OF CHAR;
VAR dimId : ARRAY OF CHAR );
PROCEDURE GetNextDimension ( curDimId : ARRAY OF CHAR;
VAR dimId : ARRAY OF CHAR );
PROCEDURE GetLastDimension ( VAR dimId : ARRAY OF CHAR );
(*
Makes it possible to access all currently
instantiated dimensions in the sequence they have
been declared by CreateDimension. Procedures
return the empty string if dimension dimId does
not exist.
*)
PROCEDURE DiscardDimension( VAR dim: Dimension );
(*
Discards dimension dim. Note, removal of a
dimension will cause removal also of all
discrete spaces that depend from it.
*)
PROCEDURE AddDimensionRemoveHandler ( dimId : ARRAY OF CHAR;
rmh : DimensionRemoveHandler );
PROCEDURE VoidDimensionRemoveHandler( dimId : ARRAY OF CHAR;
rmh : DimensionRemoveHandler );
(*
Adds (voids) a (previously added) remove handler rmh
to (from) the dimension dimId. The remove handler
rmh is called when an dimension ceases to exist,
i.e. when DiscardDimension is called; this occurrs
at a moment when the dimension's data are still
intact and all routines (except DiscardDimension)
from this module are still fully functional.
*)
(*------------------------------------------------------*)
(*===== Retrieval of information on Dimensions =====*)
(*------------------------------------------------------*)
PROCEDURE GetDimensionEleIds( dimId : ARRAY OF CHAR;
VAR eleIds : ARRAY OF CHAR );
(*
Returns in eleIds the identifiers of all elements of
dimension dimId.
*)
PROCEDURE DimensionDim( dimId: ARRAY OF CHAR ): INTEGER;
(*
Returns the number of elements in dimension dimId.
*)
PROCEDURE DimEleOrd( dimId : ARRAY OF CHAR;
eleId : ARRAY OF CHAR ): INTEGER;
(*
Returns the order of element eleId in dimension
dimId (order of first element = 0). This is the
inverse of GetDimEle.
*)
PROCEDURE GetDimEle( dimId : ARRAY OF CHAR;
eleOrd : INTEGER;
VAR eleId : ARRAY OF CHAR );
(*
Returns the identifier eleId of element with order
eleOrd within dimension dimId. This is the
inverse of DimEleOrd.
*)
PROCEDURE AttachDimensionAttr( dimId : ARRAY OF CHAR;
da : DimensionAttribute );
PROCEDURE DimensionAttr ( dimId : ARRAY OF CHAR ): DimensionAttribute;
(*
Attaches respectively returns the previously
attached attribute da to the dimension dimId. An
attribute is typically a pointer to a client data
structure associated with the dimension.
*)
(*********************************)
(*##### Discrete Spaces #####*)
(*********************************)
(*---------------------------------------------*)
(*===== Management of Discrete Spaces =====*)
(*---------------------------------------------*)
PROCEDURE CreateDiscreteSpace( VAR spc : DiscreteSpace;
spcId : ARRAY OF CHAR;
dimIds : ARRAY OF CHAR;
VAR resCode : INTEGER );
(*
This routine creates a discrete space with
identifier spcId. The space is spanned by a list of
dimensions specified in parameter dimIds. For
example, if you have previously defined the two
dimensions "TreeSpecies" (with elements "fir" and
"oak") and "Age" (with elements "young" and "old"),
respectively, calling the above procedure with
dimIds = "Age|TreeSpecies" will define a
2-dimensional discrete space which contains all
possible combinations for "Age" and "TreeSpecies",
i.e. the tuples (young,fir), (old,fir), (young,oak)
and (old,oak). Note, the same dimension may be used
only once in one and the same discrete space.
*)
PROCEDURE DiscreteSpaceExists( spcId : ARRAY OF CHAR ): BOOLEAN;
PROCEDURE GetDiscreteSpaceId( spc : DiscreteSpace;
VAR spcId : ARRAY OF CHAR );
PROCEDURE NumDiscreteSpaceDims( VAR spcId : ARRAY OF CHAR ): INTEGER;
PROCEDURE GetFirstDiscreteSpace( VAR spcId : ARRAY OF CHAR );
PROCEDURE GetPrevDiscreteSpace ( curSpcId : ARRAY OF CHAR;
VAR spcId : ARRAY OF CHAR );
PROCEDURE GetNextDiscreteSpace ( curSpcId : ARRAY OF CHAR;
VAR spcId : ARRAY OF CHAR );
PROCEDURE GetLastDiscreteSpace ( VAR spcId : ARRAY OF CHAR );
(*
Makes it possible to access all currently
instantiated discrete spaces in the sequence they
have been declared by CreateDiscreteSpace.
Procedures return the empty string if discrete space
spcId does not exist.
*)
PROCEDURE DiscardDiscreteSpace( VAR spc : DiscreteSpace );
(*
Discards the discrete space spc.
*)
PROCEDURE AddDiscreteSpaceRemoveHandler ( spcId : ARRAY OF CHAR;
rmh : DiscreteSpaceRemoveHandler );
PROCEDURE VoidDiscreteSpaceRemoveHandler( spcId : ARRAY OF CHAR;
rmh : DiscreteSpaceRemoveHandler );
(*
Adds (voids) a (previously added) remove handler rmh to
(from) the discrete space spcId. The remove handler rmh is
called when a discrete space ceases to exist, i.e. when
DiscardDiscreteSpace is called; this occurrs at a moment
when the discrete space's data are still intact and all
routines (except DiscardDiscreteSpace) from this module are
still fully functional.
*)
(*-----------------------------------------------------------*)
(*===== Retrieval of information on Discrete Spaces =====*)
(*-----------------------------------------------------------*)
PROCEDURE GetDiscreteSpaceDimIds( spcId : ARRAY OF CHAR;
VAR dimIds : ARRAY OF CHAR );
(*
Returns in dimIds the identifiers of all dimensions
defining the discrete space spcId.
*)
PROCEDURE DiscreteSpaceDim( spcId: ARRAY OF CHAR ): INTEGER;
(*
Returns the number of dimensions spanning the
discrete space spcId.
*)
PROCEDURE DimOrd( spcId : ARRAY OF CHAR;
dimId : ARRAY OF CHAR ): INTEGER;
(*
Inverse of GetDim: returns the order of dimension
dimId in discrete space spcId (first dimension = 0).
*)
PROCEDURE GetDim( spcId : ARRAY OF CHAR;
dimOrd : INTEGER;
VAR dimId : ARRAY OF CHAR );
(*
Inverse of DimOrd: returns the identifier dimId of
dimension with order dimOrd within discrete space
spcId.
*)
PROCEDURE AttachDiscreteSpaceAttr( spcId : ARRAY OF CHAR;
da : DiscreteSpaceAttribute );
PROCEDURE DiscreteSpaceAttr ( spcId : ARRAY OF CHAR ): DiscreteSpaceAttribute;
(*
Attaches respectively returns the previously
attached attribute da to the discrete space spcId.
An attribute is typically a pointer to a client data
structure associated with the discrete space.
*)
(**************************************)
(*##### Management of tuples #####*)
(**************************************)
PROCEDURE IsLegalTuple( spcId : ARRAY OF CHAR;
idTuple : ARRAY OF CHAR ): BOOLEAN;
(*
Every point in a discrete space is described by a
N-tuple of dimElements which is specified by a list
of N identifiers separated by the special character
identDelim, e.g. "old|fir". This procedure returns
TRUE if idTuple is a valid tuple for the discrete
space spcId.
*)
PROCEDURE GetFirstTuple( spcId : ARRAY OF CHAR;
VAR idTuple : ARRAY OF CHAR );
PROCEDURE GetNextTuple ( spcId : ARRAY OF CHAR;
VAR idTuple : ARRAY OF CHAR );
(*
These procedures serve subsequently retrieving in
variable idTuple all tuples that occur in discrete
space spcId. Retrieved are, however, only the tuples
which have not been forbidden by means of procedure
ForbidTuple exported below.
*)
PROCEDURE ForbidTuple ( spc : DiscreteSpace;
idTuple : ARRAY OF CHAR;
VAR resCode : INTEGER );
PROCEDURE AllowTuple ( spc : DiscreteSpace;
idTuple : ARRAY OF CHAR;
VAR resCode : INTEGER );
(*
By default, all tuples within a discrete space can be
retrieved with the aid of GetFirstTuple/ GetNextTuple.
The above procedures serve to forbid resectively
re-allow retrieving a tuple idTuple in the discrete
space spc.
*)
PROCEDURE TupleAllowed( spcId : ARRAY OF CHAR;
idTuple : ARRAY OF CHAR ): BOOLEAN;
(*
Returns TRUE if a given tuple can be retrieved by
means of procedures GetFirstTuple/GetNextTuple in
discrete space spcId.
*)
PROCEDURE IdToOrd( spcId : ARRAY OF CHAR;
idTuple : ARRAY OF CHAR;
VAR ordTuple : ARRAY OF INTEGER );
PROCEDURE OrdToId( spcId : ARRAY OF CHAR;
ordTuple : ARRAY OF INTEGER;
VAR idTuple : ARRAY OF CHAR );
(*
A tuple from a discrete space can be represented as an
array of N ordinal values for the elements of the
dimensions spanning the space. The above procedures
allow you to switch between the identifier and ordinal
representations of tuples.
*)
PROCEDURE GetNthSubString( VAR(*speed-up*) string : ARRAY OF CHAR;
n : INTEGER;
VAR subs : ARRAY OF CHAR);
(*
Returns in subs the n'th substring found in string,
assuming substrings are separated by "|" (identDelim).
This string handling routine is provided for your
convenience only.
*)
END DiscrSpaces.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib