1 Introduction
The new language org.iets3.core.expr.typetags.phyunits was created as a replacement for
org.iets3.core.expr.typetags.units
,
org.iets3.core.expr.typetags.units.quantity
and its helper modules
org.iets3.core.expr.typetags.units.si
and
org.iets3.core.expr.typetags.units.interpreter
. The standard library of this language is called
org.iets3.core.expr.typetags.phyunits.si
. Both languages can be used separately and there is no automatic migration. Only console scripts exist (MigrateToNewUnitsLanguage and MigrateUnitConceptRefsAndSiReferences). Some manual migration is still needed. To go back to the old concepts, extension methods can be used (e.g. newUnit.tolOldUnitx()). They are located in the plugin solution of
org.iets3.core.expr.typetags.units
and need to be imported.
The following references are helpful to understand the design decisions that where made in this language:
2 Concepts
2.1 Quantity
A quantity is a term that describes how much or how many of something there is. Quantities can be compared (equals, less, more) or assigned a numerical value multiple of a unit of measurement. The term can be customized through the extension point PhysUnitLangConfig ⧉. They have a symbol and an optional name. Another similar term that we have to differentiate with is measure. A measure is a way of expressing a quantity using a unit or a standard. For example, the quantity of water in a glass can be measured by using a unit of volume, such as milliliters or liters. This term is not used in this language.
Quantities as well as Section Units support multiplication, division, and exponents with integers or fractions in their specification. There are intentions to simplify them and convert between different operations. All operations are implemented as operations of a mathematical group. Exponents in specifications are automatically sorted in ascending order for positive exponents and descending order for negative exponents. This behavior can be overwritten through the extension point.
Figure 2.1-A: Example: Quantity Declarations ⧉
In the inspector, the same formula can be read with SI base quantities. The specification can also be edited in
terms of quantity symbols instead of names.
Figure 2.1-B: Example: Inspector of a Derived Quantity ⧉
2.2 Units
A physical unit is a standardized value that is used to measure and compare physical quantities. For example, the meter is a unit of length, and the kilogram is a unit of mass. length and mass are the quantities.
Units must have a symbol name and can also have an optional unit name. The must reference a quantity that can be automatically derived via an intention.
They support different scaling methods: no-scaling, metric scaling (= metric prefixes), and binary scaling (= binary prefixes), and have their type derived from the referenced quantity:
Figure 2.2-A: Example: Unit Declarations ⧉
There is special handling for kilogram because it is a base unit with a metric prefix.
Units can also be derived by adding the derived keyword and adding a specification for the unit:
Figure 2.2-B: Example: Derived Units ⧉
The SI unit equivalents are shown in the inspector:
Figure 2.2-C: Example: Inspector of a Derived Unit ⧉
The type of the unit is derived from the quantity specification and the unit specification is checked against the quantity specification:
Figure 2.2-D: Incompatible Units
2.3 Conversion Rules
Conversion rules define how the convert expressions (convertand convertTo) should execute the conversion between 2 referenced units. They reference a source and a target unit that each can have an optional prefix. The valexpression refers to the converted value itself. The return type can be specified as well:
Figure 2.3-A: Example: Conversion Rule from Kilogram to Centigram ⧉
2.4 Conversion Expressions
They reference a target unit and have an expression with a unit reference attached to it as the source. The unit references that now also contain the prefixes are converted to the prefix-less version:
Figure 2.4-A: Example: Scaling Meters to Other Prefixes ⧉
This information is also visible in the inspector:
Figure 2.4-B: Example: The Inspector of a Convert Expression ⧉
This also works for expressions with binary prefixes:
Figure 2.4-C: Example: Scaling Expressions with Binary Prefixes ⧉
2.4.1 Implicit Conversions
When no convert expression is used, implicit conversions between different prefixes are executed automatically by the interpreter. This can be deactivated through an extension point or by surrounding the expression with a noConvert expression:
Figure 2.4.1-A: Example: Implicit Conversions ⧉
Integer literals sometimes use BigIntegers for the conversion which can result in overflows or 0 as the result.
The editor will show a warning in those cases. The fourth assert item shows this issue. In such cases, cast the expression to use floating point numbers or use floating point literals.
Existing rules can be marked with the implicit keyword to provide custom implicit conversion rules. The visible implicit rule with the highest priority in the current scope will be chosen. The automatically generated implicit rules have a priority of 0. The priority can be set in the inspector of the rule:
Figure 2.4.1-B: Example: Implicit Conversion Rule ⧉
Figure 2.4.1-C: Example: Implicit Property Visible in the Inspector of a Conversion Rule ⧉
2.4.2 Eager Conversion Rules
Eager conversion rules have the keyword eager at the start of the rule. In those rules, the val still has the original unit attached to it.
Figure 2.4.2-A: Example: Eager Conversion Rule ⧉
3 Standard Library
The standard library is conform to the international standard for SI base and derived units as well as units that are often used with SI units. For a few cases, Unicode symbols are used which means that in those cases the code completion menu has to be used.
3.1 Units Of Digital Information
There is also some additional support for units of digital information because they use binary prefixes instead of decimal prefixes.
3.1.1 Example
1Kbyte = 1000 byte but 1kib = 1024 b
Translated into English: 1 kilobyte equals 1000 bytes and 1 kibibyte (binary kilobyte) equals 1024 binary bytes.
Also part of the standard library is now a class StandardUnitHelper ⧉ for checking if a unit is a SI unit, the "unitless" unit and so on.