Fan

 

const class

sys::Unit

sys::Obj
  sys::Unit

Unit models a unit of measurement. Units are represented as:

  • name: identifier for the unit within the VM. Units are typically defined in the unit database "lib/units.fog" or can be defined by the fromStr method
  • symbol: the abbreviated symbol - for example "kilogram" has the symbol "kg"
  • dimension: defines the ratio of the seven SI base units: m, kg, sec, A, K, mol, and cd
  • scale/factor: defines the normalization equations for unit conversion

Units with equal dimensions are considered to the measure the same physical quantity. This is not always true, but good enough for practice. Conversions with the convertTo method are expressed with the following equations:

unit       = dimension * scale + offset
toNormal   = scalar * scale + offset
fromNormal = (scalar - offset) / scale
toUnit     = fromUnit.fromNormal( toUnit.toNormal(sclar) )

As a simple, pragmatic solution for modeling Units, there are some units which don't fit this model including logarithm and angular units. Units which don't cleanly fit this model should be represented as dimensionless (all ratios set to zero).

Fan's model for units of measurement and the unit database are derived from the OASIS oBIX specification.

Slots

ASource

Int A()

Ampere (electric current) component of the unit dimension.

KSource

Int K()

Kelvin (thermodynamic temperature) component of the unit dimension.

cdSource

Int cd()

Candela (luminous intensity) component of the unit dimension.

convertToSource

Float convertTo(Float scalar, Unit unit)

Convert a scalar value from this unit to the given unit. If the units do not have the same dimension then throw Err. For example, to convert 3km to meters:

m  := Unit.find("meter")
km := Unit.find("kilometer")
km.convertTo(3f, m)  =>  3000f
equalsSource

override Bool equals(Obj? that)

Overrides sys::Obj.equals

Two units are equal if they have reference equality because all units are interned during definition.

findSource

static Unit? find(Str s, Bool checked := true)

Find a unit by its name if it has been defined in this VM. If the unit isn't defined yet and checked is false then return null, otherwise throw Err. Any units declared in "lib/units.fog" are implicitly defined.

fromStrSource

static Unit? fromStr(Str s, Bool checked := true)

Parse the string format of a Unit instance. If invalid format and checked is false return null, otherwise throw ParseErr. The string format of a unit is:

unit   := <name> [";" <symbol> [";" <dim> [";" <scale> [";" <offset>]]]]
name   := <str>
symbol := <str>
dim    := <ratio> ["*" <ratio>]*   // no whitespace allowed
ratio  := <base> <exp>
base   := "kg" | "m" | "sec" | "K" | "A" | "mol" | "cd"
exp    := <int>
scale  := <float>
offset := <float>

If the unit is not defined yet, this method defines the unit for the VM. If a compatible unit is already defined by the name then it is returned. If an incompatible unit is already defined by the name then Err is thrown.

hashSource

override Int hash()

Overrides sys::Obj.hash

Return toStr.hash.

kgSource

Int kg()

Kilogram (mass) component of the unit dimension.

listSource

static Unit[] list()

List all the units currently defined in the VM. Any units declared in "lib/units.fog" are implicitly defined.

mSource

Int m()

Meter (length) component of the unit dimension.

molSource

Int mol()

Mole (amount of substance) component of the unit dimension.

nameSource

Str name()

Return the identifier of this unit.

offsetSource

Float offset()

Return the offset factor used to convert this unit "from normal". See class header for normalization and conversion equations. Offset is used most commonly with temperature units. The offset for normalized unit is always zero.

quantitiesSource

static Str[] quantities()

List the quantity names used to organize the unit database in "lib/units.fog". Quantities are merely a convenient mechanism to organize the unit database - there is no guarantee that they include all current VM definitions.

quantitySource

static Unit[] quantity(Str quantity)

Get the units organized under a specific quantity name in the unit database "lib/units.fog". Quantities are merely a convenient mechanism to organize the unit database - there is no guarantee that they include all current VM definitions.

scaleSource

Float scale()

Return the scale factor used to convert this unit "from normal". For example the scale factor for kilometer is 1000 because it is defined as a 1000 meters where meter is the normalized unit for length. See class header for normalization and conversion equations. The scale factor the normalized unit is always one.

secSource

Int sec()

Second (time) component of the unit dimension.

symbolSource

Str symbol()

Return the abbreviated symbol for this unit. If the symbol was not defined then return name.

toStrSource

override Str toStr()

Overrides sys::Obj.toStr

Return the string format of this unit. See fromStr for the format.