const virtual class util::Unit

sys::Obj
  util::Unit

@Serializable { simple=true }

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

• ids: each unit has one or more unique identifiers for the unit within the VM. Units are typically defined in the unit database "etc/sys/units.txt" or can be via by the define method. Every id assigned to a unit must be unique within the VM.
• name: the first identifier in the ids list is called the name and should be a descriptive summary of the unit using words separated by underbar such as "miles_per_hour".
• symbol: the last identifier in the ids list should be the abbreviated symbol; for example "kilogram" has the symbol "kg". In units with only one id, the symbol is the same as the name. Units with exponents should use Unicode superscript chars, not ASCII digits.
• 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

A unit identifier is limited to the following characters:

• any Unicode char over 128
• ASCII letters a - z and A - Z
• underbar _
• division sign /
• percent sign %
• dollar sign $

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

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

A

Int A()

Ampere (electric current) component of the unit dimension.

K

Int K()

Kelvin (thermodynamic temperature) component of the unit dimension.

cd

Int cd()

Candela (luminous intensity) component of the unit dimension.

convertTo

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("meter")
km := Unit("kilometer")
km.convertTo(3f, m)  =>  3000f

define

static Unit define(Str s)

Define a new Unit definition in the VM's unit database using the following string format:

unit   := <ids> [";" <dim> [";" <scale> [";" <offset>]]]
names  := <ids> ("," <id>)*
id     := <idChar>*
idChar := 'a'-'z' | 'A'-'Z' | '_' | '%' | '/' | any char > 128
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 format is incorrect or any identifiers are already defined then throw an exception.

definition

Str definition()

Return string format as specified by define.

dim

Str dim()

Return the string format of the dimension portion of definition

div

@Operator
Unit div(Unit b)

Match quotient of this divided by b against current database definitions. If an unambiguous match cannot be made then throw Err.

equals

virtual override Bool equals(Obj? that)

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

fromStr

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

Find a unit by one of its identifiers 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 "etc/sys/units.txt" are implicitly defined.

hash

virtual override Int hash()

Return toStr.hash.

ids

List<Str> ids()

Return the list of programatic identifiers for this unit. The first item is always name and the last is always symbol.

kg

Int kg()

Kilogram (mass) component of the unit dimension.

list

static List<Unit> list()

List all the units currently defined in the VM. Any units declared in "etc/sys/units.txt" are implicitly defined.

m

Int m()

Meter (length) component of the unit dimension.

mol

Int mol()

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

mult

@Operator
Unit mult(Unit that)

Match the product of this and b against current database definitions. If an unambiguous match cannot be made then throw Err.

name

Str name()

Return the primary name identifier of this unit. This is always the first item in ids.

offset

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.

quantities

static List<Str> quantities()

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

quantity

static List<Unit> quantity(Str quantity)

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

scale

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.

sec

Int sec()

Second (time) component of the unit dimension.

symbol

Str symbol()

Return the abbreviated symbol for this unit. This is always the last item in ids.

toStr

virtual override Str toStr()

Return symbol.