type

Unit

src @Serializable { simple=true } const class Unit : Obj

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

constructors

fromStr	Find a unit by one of its identifiers if it has been defined in this VM.

methods

A	Ampere (electric current) component of the unit dimension.
K	Kelvin (thermodynamic temperature) component of the unit dimension.
cd	Candela (luminous intensity) component of the unit dimension.
convertTo	Convert a scalar value from this unit to the given unit.
define	Define a new Unit definition in the VM's unit database using the following string format
definition	Return string format as specified by `define`.
dim	Return the string format of the dimension portion of `definition`
div	Match quotient of this divided by b against current database definitions.
equals	Two units are equal if they have reference equality because all units are interned during definition.
hash	Return `toStr.hash`.
ids	Return the list of programmatic identifiers for this unit.
kg	Kilogram (mass) component of the unit dimension.
list	List all the units currently defined in the VM.
m	Meter (length) component of the unit dimension.
mol	Mole (amount of substance) component of the unit dimension.
mult	Match the product of this and b against current database definitions.
name	Return the primary name identifier of this unit.
offset	Return the offset factor used to convert this unit "from normal".
quantities	List the quantity names used to organize the unit database in "etc/sys/units.txt".
quantity	Get the units organized under a specific quantity name in the unit database "etc/sys/units.txt".
scale	Return the scale factor used to convert this unit "from normal".
sec	Second (time) component of the unit dimension.
symbol	Return the abbreviated symbol for this unit.
toStr	Return `symbol`.

Slot Details

A

src Int A()

Ampere (electric current) component of the unit dimension.

K

src Int K()

Kelvin (thermodynamic temperature) component of the unit dimension.

cd

src Int cd()

Candela (luminous intensity) component of the unit dimension.

convertTo

src 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

src 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

src Str definition()

Return string format as specified by define.

dim

src Str dim()

Return the string format of the dimension portion of definition

div

src @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

src virtual override Bool equals(Obj? that)

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

fromStr

src 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

src virtual override Int hash()

Return toStr.hash.

ids

src Str[] ids()

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

kg

src Int kg()

Kilogram (mass) component of the unit dimension.

list

src static Unit[] list()

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

m

src Int m()

Meter (length) component of the unit dimension.

mol

src Int mol()

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

mult

src @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

src Str name()

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

offset

src 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

src static 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

src static 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

src 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 for the normalized unit is always one.

sec

src Int sec()

Second (time) component of the unit dimension.

symbol

src Str symbol()

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

toStr

src virtual override Str toStr()

Return symbol.