ContextQMD
Back to Mathjs

Unit

docs/reference/classes/unit.md

15.2.09.6 KB
Original Source

<a name="Unit"></a>

Unit

<a name="new_Unit_new"></a>

new Unit([value], [name])

A unit can be constructed in the following ways:

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

Example usage:

js
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
ParamTypeDescription
[value]<code>number</code> | <code>BigNumber</code> | <code>Fraction</code> | <code>Complex</code> | <code>boolean</code>A value like 5.2
[name]<code>string</code>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.

<a name="Unit+valueOf"></a>

unit.valueOf ⇒ <code>string</code>

Returns the string representation of the unit.

Kind: instance property of <code>Unit</code>
<a name="Unit+clone"></a>

unit.clone() ⇒ <code>Unit</code>

create a copy of this unit

Kind: instance method of <code>Unit</code>
Returns: <code>Unit</code> - Returns a cloned version of the unit
<a name="Unit+_isDerived"></a>

unit._isDerived() ⇒ <code>boolean</code>

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

Kind: instance method of <code>Unit</code>
Returns: <code>boolean</code> - True if the unit is derived
<a name="Unit+hasBase"></a>

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 <code>Unit</code>

ParamType
base<code>BASE_UNITS</code> | <code>STRING</code> | <code>undefined</code>

<a name="Unit+equalBase"></a>

unit.equalBase(other) ⇒ <code>boolean</code>

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 <code>Unit</code>
Returns: <code>boolean</code> - true if equal base

ParamType
other<code>Unit</code>

<a name="Unit+equals"></a>

unit.equals(other) ⇒ <code>boolean</code>

Check if this unit equals another unit

Kind: instance method of <code>Unit</code>
Returns: <code>boolean</code> - true if both units are equal

ParamType
other<code>Unit</code>

<a name="Unit+multiply"></a>

unit.multiply(other) ⇒ <code>Unit</code>

Multiply this unit with another one

Kind: instance method of <code>Unit</code>
Returns: <code>Unit</code> - product of this unit and the other unit

ParamType
other<code>Unit</code>

<a name="Unit+divide"></a>

unit.divide(other) ⇒ <code>Unit</code>

Divide this unit by another one

Kind: instance method of <code>Unit</code>
Returns: <code>Unit</code> - result of dividing this unit by the other unit

ParamType
other<code>Unit</code>

<a name="Unit+pow"></a>

unit.pow(p) ⇒ <code>Unit</code>

Calculate the power of a unit

Kind: instance method of <code>Unit</code>
Returns: <code>Unit</code> - The result: this^p

ParamType
p<code>number</code> | <code>Fraction</code> | <code>BigNumber</code>

<a name="Unit+abs"></a>

unit.abs(x) ⇒ <code>Unit</code>

Calculate the absolute value of a unit

Kind: instance method of <code>Unit</code>
Returns: <code>Unit</code> - The result: |x|, absolute value of x

ParamType
x<code>number</code> | <code>Fraction</code> | <code>BigNumber</code>

<a name="Unit+to"></a>

unit.to(valuelessUnit) ⇒ <code>Unit</code>

Convert the unit to a specific unit name.

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

ParamTypeDescription
valuelessUnit<code>string</code> | <code>Unit</code>A unit without value. Can have prefix, like "cm"

<a name="Unit+toNumber"></a>

unit.toNumber(valuelessUnit) ⇒ <code>number</code>

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

Kind: instance method of <code>Unit</code>
Returns: <code>number</code> - Returns the unit value as number.

ParamTypeDescription
valuelessUnit<code>string</code> | <code>Unit</code>For example 'cm' or 'inch'

<a name="Unit+toNumeric"></a>

unit.toNumeric(valuelessUnit) ⇒ <code>number</code> | <code>BigNumber</code> | <code>Fraction</code>

Return the value of the unit in the original numeric type

Kind: instance method of <code>Unit</code>
Returns: <code>number</code> | <code>BigNumber</code> | <code>Fraction</code> - Returns the unit value

ParamTypeDescription
valuelessUnit<code>string</code> | <code>Unit</code>For example 'cm' or 'inch'

<a name="Unit+toString"></a>

unit.toString() ⇒ <code>string</code>

Get a string representation of the unit.

Kind: instance method of <code>Unit</code>
<a name="Unit+toJSON"></a>

unit.toJSON() ⇒ <code>Object</code>

Get a JSON representation of the unit

Kind: instance method of <code>Unit</code>
Returns: <code>Object</code> - Returns a JSON object structured as: {"mathjs": "Unit", "value": 2, "unit": "cm", "fixPrefix": false}
<a name="Unit+formatUnits"></a>

unit.formatUnits() ⇒ <code>string</code>

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

Kind: instance method of <code>Unit</code>
<a name="Unit+format"></a>

unit.format([options]) ⇒ <code>string</code>

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

Kind: instance method of <code>Unit</code>

ParamTypeDescription
[options]<code>Object</code> | <code>number</code> | <code>function</code>Formatting options. See lib/utils/number:format for a description of the available options.

<a name="Unit+toBest"></a>

unit.toBest(unitList, options) ⇒ <code>Unit</code>

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

Kind: instance method of <code>Unit</code> Returns: <code>Unit</code>

ParamTypeDescription
unitList<code>Array of strings</code> |Units strings array (optional).
options<code>Object</code> |Only "offset" available right now - better prefix calculation

<a name="Unit.parse"></a>

Unit.parse(str) ⇒ <code>Unit</code>

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 <code>Unit</code>
Returns: <code>Unit</code> - unit

ParamTypeDescription
str<code>string</code>A string like "5.2 inch", "4e2 cm/s^2"

<a name="Unit.isValuelessUnit"></a>

Unit.isValuelessUnit(name) ⇒ <code>boolean</code>

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

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

ParamTypeDescription
name<code>string</code>A string to be tested whether it is a value less unit. The unit can have prefix, like "cm"

<a name="Unit.fromJSON"></a>

Unit.fromJSON(json) ⇒ <code>Unit</code>

Instantiate a Unit from a JSON object

Kind: static method of <code>Unit</code>

ParamTypeDescription
json<code>Object</code>A JSON object structured as: {"mathjs": "Unit", "value": 2, "unit": "cm", "fixPrefix": false}