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