type
Unit
@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
andA
-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.
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 |
dim |
Return the string format of the dimension portion of |
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 |
ids |
Return the list of programatic 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 |
Slot Details
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
define
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
dim
Str dim()
Return the string format of the dimension portion of definition
div
equals
fromStr
hash
virtual override Int hash()
Return toStr.hash
.
ids
kg
Int kg()
Kilogram (mass) component of the unit dimension.
list
static 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
name
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 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
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.