mathjs/docs/reference/classes/unit.md

Unit

• new Unit([value], [name])
• instance
  • .valueOf ⇒ string
  • .clone() ⇒ Unit
  • ._isDerived() ⇒ boolean
  • .hasBase(base)
  • .equalBase(other) ⇒ boolean
  • .equals(other) ⇒ boolean
  • .multiply(other) ⇒ Unit
  • .divide(other) ⇒ Unit
  • .pow(p) ⇒ Unit
  • .abs(x) ⇒ Unit
  • .to(valuelessUnit) ⇒ Unit
  • .toNumber(valuelessUnit) ⇒ number
  • .toNumeric(valuelessUnit) ⇒ number | BigNumber | Fraction
  • .toString() ⇒ string
  • .toJSON() ⇒ Object
  • .formatUnits() ⇒ string
  • .format([options]) ⇒ string
  • .toBest(unitList, options) ⇒ Unit
• static
  • .parse(str) ⇒ Unit
  • .isValuelessUnit(name) ⇒ boolean
  • .fromJSON(json) ⇒ Unit

new Unit([value], [name])

A unit can be constructed in the following ways:

const a = new Unit(value, name)
const b = new Unit(null, name)
const c = Unit.parse(str)

Example usage:

const a = new Unit(5, 'cm')               // 50 mm
const b = Unit.parse('23 kg')             // 23 kg
const c = math.in(a, new Unit(null, 'm')  // 0.05 m
const d = new Unit(9.81, "m/s^2")         // 9.81 m/s^2

Param	Type	Description
[value]	number | BigNumber | Fraction | Complex | boolean	A value like 5.2
[name]	string	A unit name like "cm" or "inch", or a derived unit of the form: "u1[^ex1] [u2[^ex2] ...] [/ u3[^ex3] [u4[^ex4]]]", such as "kg m^2/s^2", where each unit appearing after the forward slash is taken to be in the denominator. "kg m^2 s^-2" is a synonym and is also acceptable. Any of the units can include a prefix.

unit.valueOf ⇒ string

Returns the string representation of the unit.

Kind: instance property of Unit

unit.clone() ⇒ Unit

create a copy of this unit

Kind: instance method of Unit
Returns: Unit - Returns a cloned version of the unit

unit._isDerived() ⇒ boolean

Return whether the unit is derived (such as m/s, or cm^2, but not N)

Kind: instance method of Unit
Returns: boolean - True if the unit is derived

unit.hasBase(base)

check if this unit has given base unit If this unit is a derived unit, this will ALWAYS return false, since by definition base units are not derived.

Kind: instance method of Unit

Param	Type
base	BASE_UNITS | STRING | undefined

unit.equalBase(other) ⇒ boolean

Check if this unit has a base or bases equal to another base or bases For derived units, the exponent on each base also must match

Kind: instance method of Unit
Returns: boolean - true if equal base

Param	Type
other	Unit

unit.equals(other) ⇒ boolean

Check if this unit equals another unit

Kind: instance method of Unit
Returns: boolean - true if both units are equal

Param	Type
other	Unit

unit.multiply(other) ⇒ Unit

Multiply this unit with another one

Kind: instance method of Unit
Returns: Unit - product of this unit and the other unit

Param	Type
other	Unit

unit.divide(other) ⇒ Unit

Divide this unit by another one

Kind: instance method of Unit
Returns: Unit - result of dividing this unit by the other unit

Param	Type
other	Unit

unit.pow(p) ⇒ Unit

Calculate the power of a unit

Kind: instance method of Unit
Returns: Unit - The result: this^p

Param	Type
p	number | Fraction | BigNumber

unit.abs(x) ⇒ Unit

Calculate the absolute value of a unit

Kind: instance method of Unit
Returns: Unit - The result: |x|, absolute value of x

Param	Type
x	number | Fraction | BigNumber

unit.to(valuelessUnit) ⇒ Unit

Convert the unit to a specific unit name.

Kind: instance method of Unit
Returns: Unit - Returns a clone of the unit with a fixed prefix and unit.

Param	Type	Description
valuelessUnit	string | Unit	A unit without value. Can have prefix, like "cm"

unit.toNumber(valuelessUnit) ⇒ number

Return the value of the unit when represented with given valueless unit

Kind: instance method of Unit
Returns: number - Returns the unit value as number.

Param	Type	Description
valuelessUnit	string | Unit	For example 'cm' or 'inch'

unit.toNumeric(valuelessUnit) ⇒ number | BigNumber | Fraction

Return the value of the unit in the original numeric type

Kind: instance method of Unit
Returns: number | BigNumber | Fraction - Returns the unit value

Param	Type	Description
valuelessUnit	string | Unit	For example 'cm' or 'inch'

unit.toString() ⇒ string

Get a string representation of the unit.

Kind: instance method of Unit

unit.toJSON() ⇒ Object

Get a JSON representation of the unit

Kind: instance method of Unit
Returns: Object - Returns a JSON object structured as: {"mathjs": "Unit", "value": 2, "unit": "cm", "fixPrefix": false}

unit.formatUnits() ⇒ string

Get a string representation of the units of this Unit, without the value.

Kind: instance method of Unit

unit.format([options]) ⇒ string

Get a string representation of the Unit, with optional formatting options.

Kind: instance method of Unit

Param	Type	Description
[options]	Object | number | function	Formatting options. See lib/utils/number:format for a description of the available options.

unit.toBest(unitList, options) ⇒ Unit

Converts a unit to the most appropriate display unit with optional unitList and options.

Kind: instance method of Unit Returns: Unit

Param	Type	Description
unitList	Array of strings |	Units strings array (optional).
options	Object |	Only "offset" available right now - better prefix calculation

Unit.parse(str) ⇒ Unit

Parse a string into a unit. The value of the unit is parsed as number, BigNumber, or Fraction depending on the math.js config setting number.

Throws an exception if the provided string does not contain a valid unit or cannot be parsed.

Kind: static method of Unit
Returns: Unit - unit

Param	Type	Description
str	string	A string like "5.2 inch", "4e2 cm/s^2"

Unit.isValuelessUnit(name) ⇒ boolean

Test if the given expression is a unit. The unit can have a prefix but cannot have a value.

Kind: static method of Unit
Returns: boolean - true if the given string is a unit

Param	Type	Description
name	string	A string to be tested whether it is a value less unit. The unit can have prefix, like "cm"

Unit.fromJSON(json) ⇒ Unit

Instantiate a Unit from a JSON object

Kind: static method of Unit

Param	Type	Description
json	Object	A JSON object structured as: {"mathjs": "Unit", "value": 2, "unit": "cm", "fixPrefix": false}