src/UnitsAPI/UnitsAPI.cdl

   1 -- Created on: 1995-11-15
   2 -- Created by: Jean-Louis Frenkel <rmi@pernox>
   3 -- Copyright (c) 1995-1999 Matra Datavision
   4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
   5 --
   6 -- The content of this file is subject to the Open CASCADE Technology Public
   7 -- License Version 6.5 (the "License"). You may not use the content of this file
   8 -- except in compliance with the License. Please obtain a copy of the License
   9 -- at http://www.opencascade.org and read it completely before using this file.
  10 --
  11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
  12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
  13 --
  14 -- The Original Code and all software distributed under the License is
  15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
  16 -- Initial Developer hereby disclaims all such warranties, including without
  17 -- limitation, any warranties of merchantability, fitness for a particular
  18 -- purpose or non-infringement. Please see the License for the specific terms
  19 -- and conditions governing the rights and limitations under the License.
  20
  21 -- Modified:    Gerard GRAS <gg@photox> Tue Feb 25
  22 --              Add local system methodes
  23 -- Modified     Mon Apr  7 16:52:40 1997 by Patrick BOSINCO
  24 --            Add Dimensions access methods
  25 --              GG 05/02/01 MECALOG
  26 --              Add Check() method.
  27
  28
  29 package UnitsAPI
  30
  31 ---Purpose: The UnitsAPI global functions are used to
  32 -- convert a value from any unit into another unit.
  33 -- Principles
  34 -- Conversion is executed among three unit systems:
  35 -- -   the SI System
  36 -- -   the user's Local System
  37 -- -   the user's Current System.
  38 -- The SI System is the standard international unit
  39 -- system. It is indicated by SI in the synopses of
  40 -- the UnitsAPI functions.
  41 -- The MDTV System corresponds to the SI
  42 -- international standard but the length unit and all
  43 -- its derivatives use millimeters instead of the meters.
  44 -- Both systems are proposed by Open CASCADE;
  45 -- the SI System is the standard option. By
  46 -- selecting one of these two systems, the user
  47 -- defines his Local System through the
  48 -- SetLocalSystem function. The Local System is
  49 -- indicated by LS in the synopses of the UnitsAPI functions.
  50 -- The user's Local System units can be modified in
  51 -- the working environment. The user defines his
  52 -- Current System by modifying its units through
  53 -- the SetCurrentUnit function. The Current
  54 -- System is indicated by Current in the synopses
  55 -- of the UnitsAPI functions.
  56
  57 uses Resource,Units
  58
  59 is
  60
  61     enumeration SystemUnits is DEFAULT,SI,MDTV end;
  62 ---Purpose: Identifies unit systems which may be defined as a
  63 -- basis system in the user's session:
  64 -- -   UnitsAPI_DEFAULT : default system (this is the SI system)
  65 -- -   UnitsAPI_SI : the SI unit system
  66 -- -   UnitsAPI_MDTV : the MDTV unit system; it
  67 --   is equivalent to the SI unit system but the
  68 --   length unit and all its derivatives use
  69 --   millimeters instead of meters.
  70 -- Use the function SetLocalSystem to set up one
  71 -- of these unit systems as working environment.
  72
  73     CurrentToLS(aData: Real from Standard; aQuantity: CString from Standard)
  74     returns Real from Standard;
  75     ---Purpose: Converts the current unit value to the local system units value.
  76     --  Example: CurrentToLS(1.,"LENGTH") returns 1000. if the current length unit
  77     --          is meter and LocalSystem is MDTV.
  78
  79     CurrentToSI(aData: Real from Standard; aQuantity: CString from Standard)
  80     returns Real from Standard;
  81     ---Purpose: Converts the current unit value to the SI system units value.
  82     --  Example: CurrentToSI(1.,"LENGTH") returns 0.001 if current length unit
  83     --          is millimeter.
  84
  85     CurrentFromLS(aData: Real from Standard; aQuantity: CString from Standard)
  86     returns Real from Standard;
  87     ---Purpose: Converts the local system units value to the current unit value.
  88     --  Example: CurrentFromLS(1000.,"LENGTH") returns 1. if current length unit
  89     --          is meter and LocalSystem is MDTV.
  90
  91     CurrentFromSI(aData: Real from Standard; aQuantity: CString from Standard)
  92     returns Real from Standard;
  93     ---Purpose: Converts the SI system units value to the current unit value.
  94     --  Example: CurrentFromSI(0.001,"LENGTH") returns 1 if current length unit
  95     --          is millimeter.
  96
  97     AnyToLS(aData: Real from Standard; aUnit: CString from Standard)
  98     returns Real from Standard;
  99     ---Purpose: Converts the local unit value to the local system units value.
 100     --  Example: AnyToLS(1.,"in.") returns 25.4 if the LocalSystem is MDTV.
 101
 102     AnyToLS(aData: Real from Standard; aUnit: CString from Standard;
 103             aDim : out Dimensions from Units)
 104     returns Real from Standard;
 105     ---Purpose: Converts the local unit value to the local system units value.
 106     --          and gives the associated dimension of the unit
 107
 108     AnyToSI(aData: Real from Standard; aUnit: CString from Standard)
 109     returns Real from Standard;
 110     ---Purpose: Converts the local unit value to the SI system units value.
 111     --  Example: AnyToSI(1.,"in.") returns 0.0254
 112
 113     AnyToSI(aData: Real from Standard; aUnit: CString from Standard;
 114             aDim : out Dimensions from Units)
 115     returns Real from Standard;
 116     ---Purpose: Converts the local unit value to the SI system units value.
 117     --          and gives the associated dimension of the unit
 118
 119     AnyFromLS(aData: Real from Standard; aUnit: CString from Standard)
 120     returns Real from Standard;
 121     ---Purpose: Converts the local system units value to the local unit value.
 122     --  Example: AnyFromLS(25.4,"in.") returns 1. if the LocalSystem is MDTV.
 123 -- Note: aUnit is also used to identify the type of physical quantity to convert.
 124
 125     AnyFromSI(aData: Real from Standard; aUnit: CString from Standard)
 126     returns Real from Standard;
 127     ---Purpose: Converts the SI system units value to the local unit value.
 128     --  Example: AnyFromSI(0.0254,"in.") returns 0.001
 129 -- Note: aUnit is also used to identify the type of physical quantity to convert.
 130
 131     CurrentToAny(aData: Real from Standard; aQuantity: CString from Standard;
 132                  aUnit: CString from Standard)
 133     returns Real from Standard;
 134     ---Purpose: Converts the aData value expressed in the
 135 -- current unit for the working environment, as
 136 -- defined for the physical quantity aQuantity by the
 137 -- last call to the SetCurrentUnit function, into the unit aUnit.
 138
 139     CurrentFromAny(aData: Real from Standard; aQuantity: CString from Standard;
 140                    aUnit: CString from Standard)
 141     returns Real from Standard;
 142     ---Purpose: Converts the aData value expressed in the unit
 143 -- aUnit, into the current unit for the working
 144 -- environment, as defined for the physical quantity
 145 -- aQuantity by the last call to the SetCurrentUnit function.
 146
 147     AnyToAny(aData: Real from Standard; aUnit1: CString from Standard;
 148     aUnit2: CString from Standard)
 149     returns Real from Standard;
 150     ---Purpose: Converts the local unit value to another local unit value.
 151     --  Example: AnyToAny(0.0254,"in.","millimeter") returns 1. ;
 152
 153     LSToSI(aData: Real from Standard; aQuantity: CString from Standard)
 154     returns Real from Standard;
 155     ---Purpose: Converts the local system units value to the SI system unit value.
 156     --  Example: LSToSI(1.,"LENGTH") returns 0.001 if the local system
 157     --          length unit is millimeter.
 158
 159     SIToLS(aData: Real from Standard; aQuantity: CString from Standard)
 160     returns Real from Standard;
 161     ---Purpose: Converts the SI system unit value to the local system units value.
 162     --  Example: SIToLS(1.,"LENGTH") returns 1000. if the local system
 163     --          length unit is millimeter.
 164
 165     SetLocalSystem(aSystemUnit: SystemUnits = UnitsAPI_SI);
 166     ---Purpose: Sets the local system units.
 167     --  Example: SetLocalSystem(UnitsAPI_MDTV)
 168
 169     LocalSystem returns SystemUnits;
 170     ---Purpose: Returns the current local system units.
 171
 172     SetCurrentUnit(aQuantity: CString from Standard; aUnit: CString from Standard);
 173     ---Purpose: Sets the current unit dimension <aUnit> to the unit quantity <aQuantity>.
 174     --  Example: SetCurrentUnit("LENGTH","millimeter")
 175
 176     CurrentUnit(aQuantity:CString from Standard)
 177     returns CString from Standard;
 178     ---Purpose: Returns the current unit dimension <aUnit> from the unit quantity <aQuantity>.
 179
 180     Save;
 181     ---Purpose: saves the units in the file .CurrentUnits of the directory pointed by the
 182     --          CSF_CurrentUnitsUserDefaults environment variable.
 183
 184     Reload;
 185
 186     CheckLoading(aSystemUnit: SystemUnits) is private;
 187
 188     Dimensions(aQuantity : CString from Standard)
 189     returns Dimensions from Units
 190     raises NoSuchObject from Standard;
 191     ---Purpose: return the dimension associated to the quantity
 192     ---Example: Dimensions("LENGTH")
 193
 194     DimensionLess returns Dimensions from Units;
 195     DimensionMass returns Dimensions from Units;
 196     DimensionLength returns Dimensions from Units;
 197     DimensionTime returns Dimensions from Units;
 198     DimensionElectricCurrent returns Dimensions from Units;
 199     DimensionThermodynamicTemperature returns Dimensions from Units;
 200     DimensionAmountOfSubstance returns Dimensions from Units;
 201     DimensionLuminousIntensity returns Dimensions from Units;
 202     DimensionPlaneAngle returns Dimensions from Units;
 203     DimensionSolidAngle returns Dimensions from Units;
 204     ---Purpose: Returns the basic dimensions.
 205
 206     Check( aQuantity: CString from Standard;
 207            aUnit: CString from Standard)
 208     returns Boolean from Standard;
 209     ---Purpose: Checks the coherence between the quantity <aQuantity>
 210     --          and the unit <aUnits> in the current system and
 211     --          returns FALSE when it's WRONG.
 212
 213 end UnitsAPI;