Overview

Guide Lifecycle Services Translations Auxiliary Exceptions Roadmap Blog

API

AppError Collection Component Document Event EventCancelError Field Local Log MediaType Path Secure SecureError Timer Type Tyr Unit Units UnitConversionError UnitDegree UnitFactor UnitSystem UnitType UserError

Tyreant

Overview

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:

  1. in the components property and as
  2. 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/s2 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/s2 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 m2 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/s2 will map to "acceleration"); otherwise a units type will be generated for the combination of units (i.e. m333 will get a custom unit type -- that it would share with ft333 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".