const class sys::Unit

sys::Obj
  sys::Unit

@Serializable { simple=true }

Source

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.

A

Int A()

Source

Ampere (electric current) component of the unit dimension.

K

Int K()

Source

Kelvin (thermodynamic temperature) component of the unit dimension.

cd

Int cd()

Source

Candela (luminous intensity) component of the unit dimension.

convertTo

Float convertTo(Float scalar, Unit unit)

Source

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)

Source

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

Source

Return string format as specified by define.

dim

Str dim()

Source

Return the string format of the dimension portion of definition

div

@Operator
Unit div(Unit b)

Source

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)

Source

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)

Source

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

Source

Return toStr.hash.

ids

Str[] ids()

Source

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

kg

Int kg()

Source

Kilogram (mass) component of the unit dimension.

list

static Unit[] list()

Source

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

m

Int m()

Source

Meter (length) component of the unit dimension.

mol

Int mol()

Source

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

mult

@Operator
Unit mult(Unit that)

Source

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

name

Str name()

Source

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

offset

Float offset()

Source

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 Str[] quantities()

Source

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 Unit[] quantity(Str quantity)

Source

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

Source

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

Int sec()

Source

Second (time) component of the unit dimension.

symbol

Str symbol()

Source

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

toStr

virtual override Str toStr()

Source

Return symbol.