# Units

A __Units__ represents a set of units (it can also represent a single unit).

__Units__ is the primary interface for using units within Tyranid (you do not usually need to interact
directly with the other __Unit*__ classes but might want to occassionally).

__Units__ are *immutable* and globally shared.

See __Field.in__ for how to associate units to fields.

Also see the Units Guide for more explanation and examples and __Unit__ for a list of
built-in units.

## static

parse(text: string): Units
This method is used to create new __Units__ instances.

__Tyr.U__ is aliased to this method. For example:

```
const U = Tyr.U;
```*// U() can be used as a function:*
kg = Units.parse('kg/s');
kg = U('kg/s');
*// U() can also be used as a tagged template string:*
kg = Units.parse`kg/s`;
kg = U`kg/s`;

## instance

*symbol*: number
__Units__ instances store their components in two ways:

- in the
__components__ property and as - each unit symbol stored
with its associated degree.

These "*symbol*: *degree*" properties are the only enumerable properties on __Units__ instances. This means that if you output the __Units__ instance associated
with **m/s**^{2} you will get:

{
m: 1,
s: -2
}

add(value: number, addUnits: Units, addValue: number): number
This adds two values from two units. The units do not need to be the same, but they need to be compatible.
If the units are not compatible, a __UnitConversionError__ will be thrown.

For example, __U`in`.add(1, U`ft`, 1)__ returns __13__.

components: UnitDegree[]
This contains the components for this Units. For example, **m/s**^{2} has two components: **meters** with degree 1 and **seconds** with degree -2.

convert(value: number, to: Units): number
This converts values from this units to the target units. If the units are not compatible, a __UnitConversionError__ will be thrown.

For example, __U`ft`.convert(1, U`in`)__ returns __12__.

divide(by: Units): Units
This divides this instance of units by the __by__ units and returns a new __Units__ type. Values are not passed in because values can be simply divided
together normally.

For example, __U`m`.divide(U`s2`)__ yields __U`m/s2`__.

invert(): Units
This returns the the *inversion* of this set of units.

For example, __U`ft`.invert()__ yields __U`ft-1`__ while __U`m/s`.invert()__ yields __U`s/m`__.

isCompatibleWith(units: Units): boolean
This examines the two sets of units and if they are the same type (i.e. they can be added and subtracted) this method will return true.

For example, **ft** is compatible with **m**, but not **m**^{2} or **s**.

multiply(by: Units): Units
This multiplies this instance of units by the __by__ units and returns a new __Units__ type. Values are not passed in because values can be simply multiplied
together normally.

For example, __U`m`.multiply(U`s`)__ yields __U`m*s`__.

normal(): Units
This returns the the *normalized* units for this set of units. The "normalized unit" is determined by the UnitType.normal
property.

For example, __U`ft/ton`.normal()__ yields __U`m/kg`__.

sid: string
This is the primary key for units. __sid__ stands for "string ID".

subtract(value: number, subUnits: Units, subValue: number): number
This subtracts __subValue__ from __value__. The units do not need to be the same, but they need to be compatible.
If the units are not compatible, a __UnitConversionError__ will be thrown.

For example, __U`in`.subtract(14, U`ft`, 1)__ returns __2__.

type: UnitType
This contains the type for this __Units__ instance. If the units for this instance are recognized they will map to pre-defined type with a name (i.e. **m/s**^{2}
will map to "acceleration"); otherwise a units type will be generated for the combination of units (i.e. **m**^{333} will get a custom unit type -- that it
would share with **ft**^{333} if that units was created).

toString(): string
This returns a simplified display of the units. For example, __U('m-2W1s-1r-1')__ returns __"W/r1s1m2"__.