new UnitValue(value, units)
A class representing a numeric value with associated units.
Includes static helpers for maths and parsing strings of values with units.
Note that the math functions (add, subtract, divide, multiply) have
both static and instance versions for flexibility.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
number | The numeric value to represent. |
units |
string | The units of the value. |
- Source:
Example
const uv = new UnitValue(10, "px");Members
units :string
The units of the UnitValue
Type:
- string
- Source:
value :number
The numeric value of the UnitValue
Type:
- number
- Source:
Methods
(static) add(v1, v2, unitsopt) → {UnitValue}
Adds the values of v1 and v2,
returning a new UnitValue.
Units can be specified for the output UnitValue, or they will be inferred if possible from the source values
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v1 |
number | Number | string | String | UnitValue | The first value to add. |
|
v2 |
number | Number | string | String | UnitValue | The second value to add. |
|
units |
string |
<optional> |
The units to use on the output UnitValue. Units are required if none of the values have units associated with them. If the values already have units and units are additionally specified, the specified units will override those of the original values. |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Add the values of two strings with different units specifying the units to use
const sum = UnitValue.add("2px", "0.5em", "rem"); // sum.toString() = "2.5rem"
// NOTE no conversion takes place, we are just doing math with the values and then appending a unit.(static) divide(v1, v2, unitsopt) → {UnitValue}
Divides the value of v1 by that of v2,
returning a new UnitValue.
Units can be specified for the output UnitValue, or they will be inferred if possible from the source values
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v1 |
number | Number | string | String | UnitValue | The value to be divided. |
|
v2 |
number | Number | string | String | UnitValue | The value to divide by. |
|
units |
string |
<optional> |
The units to use on the output UnitValue. Units are required if none of the values have units associated with them. If the values already have units and units are additionally specified, the specified units will override those of the original values. |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Divide a unitless number value by a UnitValue and infer the units from the second value.
const uv = new UnitValue(2, "px");
const result = UnitValue.divide(10, uv); // result.toString() = "5px"(static) multiply(v1, v2, unitsopt) → {UnitValue}
Multiply the values of v1 and v2 together,
returning a new UnitValue.
Units can be specified for the output UnitValue, or they will be inferred if possible from the source values
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v1 |
number | Number | string | String | UnitValue | The first value to multiply. |
|
v2 |
number | Number | string | String | UnitValue | The second value to multiply. |
|
units |
string |
<optional> |
The units to use on the output UnitValue. Units are required if none of the values have units associated with them. If the values already have units and units are additionally specified, the specified units will override those of the original values. |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Multiply a unitless number value with a unitless string value and specify the units for the output.
const result = UnitValue.multiply(10, "5", "ml"); // result.toString() = "50ml"(static) parse(v, unitsopt) → {UnitValue}
Parse a value and return a UnitValue, optionally overriding the units.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v |
number | Number | string | String | UnitValue | The value |
|
units |
string |
<optional> |
The units. Units are required if If |
- Source:
Returns:
A UnitValue initialised with the results of parsing the value.
- Type
- UnitValue
Examples
Parsing a combined string to a UnitValue
const uv = UnitValue.parse("10px");
// uv = { value: 10, units: "px" }
// uv.toString() = "10px"Parsing a number value to a UnitValue with specified units
const uv = UnitValue.parse(1.6, "em");
// uv = { value: 1.6, units: "em" }
// uv.toString() = "1.6em"Parsing an existing UnitValue and overriding the units
// This is probably an uncommon usage,
// but is valid as a side effect of how UnitValue.parse is used internally
const uv = UnitValue.parse(new UnitValue(10, "px"), "%");
// uv = { value: 10, units: "%" }
// uv.toString() = "10%"(static) parseString(s) → {UnitValue}
Parses a string (not String) to a UnitValue.
The string must contain a value and units,
in the format: <number><units>
where:
- number is required
- number is an
intor afloat - number doesn't support Scientific Notation e.g.
1E2 - units is required
- units is an arbitrary
string - units doesn't start with a number or a
. <number>and<units>are optionally separated by a single whitespace character
Used internally by UnitValue.parse but can be used directly with valid input.
Parameters:
| Name | Type | Description |
|---|---|---|
s |
string | The string to parse |
- Source:
Returns:
A UnitValue initialised with the results of parsing the string.
- Type
- UnitValue
Example
const uv = UnitValue.parseString("10px");
// uv = { value: 10, units: "px" }
// uv.toString() = "10px"(static) subtract(v1, v2, unitsopt) → {UnitValue}
Subtracts the value of v2 from that of v1,
returning a new UnitValue.
Units can be specified for the output UnitValue, or they will be inferred if possible from the source values
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v1 |
number | Number | string | String | UnitValue | The value to subtract from. |
|
v2 |
number | Number | string | String | UnitValue | The value to subtract. |
|
units |
string |
<optional> |
The units to use on the output UnitValue. Units are required if none of the values have units associated with them. If the values already have units and units are additionally specified, the specified units will override those of the original values. |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Find the difference between a string and a UnitValue with matching units
const uv = new UnitValue(2, "px");
const diff = UnitValue.subtract("10px", uv); // diff.toString() = "8px"add(v, unitsopt) → {UnitValue}
Adds the value v to the value of this UnitValue,
returning a new UnitValue.
Units can be specified for the output UnitValue.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v |
number | Number | string | String | UnitValue | The value to add. |
|
units |
string |
<optional> |
The units to use on the output UnitValue |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Add the values of two UnitValues with different units specifying the units to use
const uv1 = new UnitValue(2, "px");
const uv2 = new UnitValue(0.5, "em");
const sum = uv1.add(uv2, "rem"); // sum.toString() = "2.5rem"
// NOTE no conversion takes place, we are just doing math with the values and then appending a unit.divide(v, unitsopt) → {UnitValue}
Divides the value of this UnitValue by the value v,
returning a new UnitValue.
Units can be specified for the output UnitValue.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v |
number | Number | string | String | UnitValue | The value to divide by. |
|
units |
string |
<optional> |
The units to use on the output UnitValue |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Converting milliseconds to seconds with overriding units and a unitless divisor
const ms = new UnitValue(1000, "ms");
const s = ms.divide(1000, "s");multiply(v, unitsopt) → {UnitValue}
Multiplies the value of this UnitValue by the value v,
returning a new UnitValue.
Units can be specified for the output UnitValue.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v |
number | Number | string | String | UnitValue | The value to multiply by. |
|
units |
string |
<optional> |
The units to use on the output UnitValue |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Converting seconds to milliseconds with overriding units and a unitless multiplier
const s = new UnitValue(1, "s");
const ms = s.multiply(1000, "ms");subtract(v, unitsopt) → {UnitValue}
Subtracts the value v from the value of this UnitValue,
returning a new UnitValue.
Units can be specified for the output UnitValue.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
v |
number | Number | string | String | UnitValue | The value to subtract. |
|
units |
string |
<optional> |
The units to use on the output UnitValue |
- Source:
Returns:
A new UnitValue.
- Type
- UnitValue
Example
Find the difference between two UnitValues with matching units
const uv1 = new UnitValue(10, "px");
const uv2 = new UnitValue(2, "px");
const diff = uv1.subtract(uv2); // diff.toString() = "8px"toArray() → {Array}
Returns the UnitValue's value and units as consecutive items in an array.
This matches the behaviour of external:parse-unit
- Source:
Returns:
An array with 2 elements: the value and units of the UnitValue.
- Type
- Array
Example
The external:parse-unit example using UnitValue
// prints [50, "gold"]
console.log(UnitValue.parseString("50gold").toArray());toString() → {string}
Returns a string representation of the UnitValue
in the format <number><value>
- Source:
Returns:
The string representation of the UnitValue.
- Type
- string
Example
const uv = new UnitValue(2, "rem");
// uv.toString() = "2rem"valueOf() → {number}
Implementing a custom UnitValue#valueOf means we can use regular javascript math against the value, but discard the units.
Unlikely to be used directly, this is used by the javascript engine when inferring that the type should be a number, for example in math operations.
- Source:
Returns:
The numeric value held by the UnitValue.
- Type
- number
Example
UnitValue#valueOf is called by the javascript engine to allow the `+` operator to work normally on the object
const uv = new UnitValue(10, "px");
const result = uv + 5; // result = 15