Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
Scales

NAME

SYNOPSIS

TYPE Family = POINTER TO FamilyRec;
TYPE FamilyRec = RECORD (Disciplines.ObjectRec) END;
TYPE Scale = POINTER TO ScaleRec;
TYPE ScaleRec = RECORD (Disciplines.ObjectRec) END;
CONST unitNameLength = 32;
TYPE Unit = POINTER TO UnitRec;
TYPE UnitRec = RECORD (Disciplines.ObjectRec) END;
TYPE UnitName = ARRAY unitNameLength OF CHAR;
CONST absolute = 1; relative = 2; (* measure types *)
TYPE Measure = POINTER TO MeasureRec;
TYPE MeasureRec = RECORD (Operations.OperandRec) END;
TYPE Value = LONGINT;



TYPE CreateProc = PROCEDURE (scale: Scale; VAR measure: Measure; abs: BOOLEAN);
TYPE GetValueProc = PROCEDURE (measure: Measure; unit: Unit; VAR value: Value);
TYPE SetValueProc = PROCEDURE (measure: Measure; unit: Unit; value: Value);
TYPE AssignProc = PROCEDURE (target: Measure; source: Measure);
CONST add = Operations.add; sub = Operations.sub;
TYPE Operation = SHORTINT; (* add or sub *)
TYPE OperatorProc = PROCEDURE (op: Operation; op1, op2, result: Measure);
TYPE CompareProc = PROCEDURE (op1, op2: Measure) : INTEGER;
TYPE ConvertProc = PROCEDURE (from, to: Measure);
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
   RECORD
      (Objects.ObjectRec)
      create: CreateProc;
      getvalue: GetValueProc;
      setvalue: SetValueProc;
      assign: AssignProc;
      op: OperatorProc;
      compare: CompareProc;
      scaleToReference: ConvertProc;
      referenceToScale: ConvertProc;
   END;



VAR invalidOperation: Events.EventType;
VAR incompatibleScales: Events.EventType;
VAR badCombination: Events.EventType;



PROCEDURE InitFamily(family: Family; reference: Scale);
PROCEDURE Init(scale: Scale; family: Family; if: Interface);
PROCEDURE InitUnit(scale: Scale; unit: Unit; name: UnitName);
PROCEDURE CreateMeasure(scale: Scale; VAR measure: Measure; type: SHORTINT);
PROCEDURE CreateAbsMeasure(scale: Scale; VAR measure: Measure);
PROCEDURE CreateRelMeasure(scale: Scale; VAR measure: Measure);
PROCEDURE ConvertMeasure(scale: Scale; VAR measure: Measure);



PROCEDURE GetReference(family: Family; VAR reference: Scale);
PROCEDURE GetFamily(scale: Scale; VAR family: Family);
PROCEDURE GetScaleOfUnit(unit: Unit; VAR scale: Scale);
PROCEDURE GetScale(measure: Measure; VAR scale: Scale);



PROCEDURE TraverseUnits(scale: Scale);
PROCEDURE NextUnit(scale: Scale; VAR unit: Unit) : BOOLEAN;
PROCEDURE GetName(unit: Unit; VAR name: UnitName);
PROCEDURE GetValue(measure: Measure; unit: Unit; VAR value: Value);
PROCEDURE SetValue(measure: Measure; unit: Unit; value: Value);



PROCEDURE IsAbsolute(measure: Measure) : BOOLEAN;
PROCEDURE IsRelative(measure: Measure) : BOOLEAN;
PROCEDURE MeasureType(measure: Measure) : SHORTINT;

DESCRIPTION

A scale is defined by a set of units for measuring, e.g. a scale for dates could consist of the units day, month and year. A measure is defined by a set of values for each of the units. Values are of type Value.

Scales distinguishes between absolute and relative measures. An absolute measure describes a point within the set of measures while a relative measure describes the difference between two points of the set of measures. Let m1 and m2 be absolute measures for the points p1 and p2. Then we can define the differences (relative measures) between m1 and m2:

d  := m	 - m
 1     1    2

d  := m	 - m
 2     2    1

m  - d	= m
 1    1	   2

m  + d	= m
 1    2	   2

In many cases there exist alternative unit systems for similar scales. A family of scales is defined by a reference scale and a set of additional scales where every scaling system knows how to convert its measures to the reference system and back.

Init initializes a newly created scale and associates it with the given family and uses if as interface. family may be NIL if scale does not belong to a family or if scale should become a reference scale.

The interface procedures are expected to meet the specifications following:

create: PROCEDURE(scale: Scale; VAR measure: Measure; abs: BOOLEAN);

create a new measure of the given scale and initialize it with an implementation dependant zero value. The measure type (absolute or relative) is determined by abs. measure needs not to be passed to Operations.Init. Note that Measure is an extension of PersistentObjects.Object. Thus, PersistentObjects.Init has to be called immediately after creation.

getvalue: PROCEDURE(measure: Measure; unit: Unit; VAR value: Value);

store the value of the given unit of the given measure into value.

setvalue: PROCEDURE(measure: Measure; unit: Unit; value: Value);

set the value of the given unit of the given measure to value.

assign: PROCEDURE(target: Measure; source: Measure);

copy the value of source to target; target is of the appropiate type and already initialized.

op: PROCEDURE(op: Operation; op1, op2, result: Measure);

execute the given operator (add or sub) for the given operands op1 and op2 and store the result in the already initialized result. op1, op2 and result are guaranteed to belong to the same scale. result is guaranteed to be not equal to op1 or op2.

compare: PROCEDURE(op1, op2: Measure) : INTEGER;

compare the given operands and return an integer value less than zero if op1 is less than op2, or equal to zero if op1 equals op2, or greater than zero if op1 is greater than op2.

scaleToReference: PROCEDURE(from, to: Measure);

convert the given measure from to the reference scale and return it in to (which is already created and initialized).

referenceToScale: PROCEDURE(from, to: Measure);

convert the given measure of the reference scale to the own scale and return it in to (which is already created and initialized).

InitFamily initializes a family and takes reference as reference scale. reference must not belong to another family.

InitUnit adds a unit to the scaling system scale. name should be a short descriptive name of the unit, e.g. "day", "month" or "year" for dates.

CreateAbsMeasure creates and initializes measure to the origin of the given scaling system. CreateRelMeasure creates and initializes measure to zero. CreateMeasure creates and initializes measure for the given type (either absolute or relative). ConvertMeasure converts measure to the given scale which must belong to the same family as the original scale of measure.

GetReference returns the reference scale of the given family. GetFamily returns the family of the given scale which may be NIL. GetScaleOfUnit or GetScale return the scale of the given unit or measure respectively.

TraverseUnits starts a traverse through the set of units of a scale. NextUnit returns TRUE on success and stores the next unit of the given scale into unit. FALSE is returned at the end of the traverse.

GetName returns the name of the given unit.

GetValue and SetValue allow to get and set values of measures for a given unit.

IsAbsolute and IsRelative allow to distinguish between absolute and relative measures. MeasureType returns the measure type (either absolute or relative).

Additionally, the addition, subtraction, comparison and assignment operations of Operations may be used. The resulting measure type (absolute or relative) of addition and subtraction operations is shown by following tables:

Add	|  absolute|  relative	    Sub	    |  absolute|  relative
________|__________|___________	   _________|__________|__________
absolute|__invalid_|__absolute_	   _absolute|__relative|__absolute
relative|  absolute|  relative	    relative|  invalid |  relative

DIAGNOSTICS

invalidOperation

indicates a try to execute an invalid operation for the given measure types, e.g. addition of two absolute values.

incompatibleScales

the scales of the operands do not belong to the same family.

badCombination

this event is raised by SetValue or GetValue if the given measure and unit do not belong to the same scaling system.

SEE ALSO

Assertions

error handling

Operations

addition, subtraction, comparison and assignment of measures

PersistentObjects

interface for persistent objects

Oberon || Library || Module Index || Search Engine || Definition || Module