# new MassUnit(options)
Parameters:
| Name | Type | Description |
|---|---|---|
options |
Object
|
Options controlling the construction of this instance |
unit |
string
|
|
amount |
number
|
string
|
undefined
|
Extends
Methods
# convert(to) → {number|undefined}
Return the amount of the current measurement when converted to the given measurement unit. Measurements can only be converted to other measurements of the same type.
Parameters:
| Name | Type | Description |
|---|---|---|
to |
string
|
the name of the units to convert this measurement to |
- Inherited From:
the amount corresponding to the requested unit
number
|
undefined
# convertSystem(measurementSystem) → {Measurement}
Return a new measurement instance that is converted to a different measurement system. Measurements can only be converted to other measurements of the same type.
Parameters:
| Name | Type | Description |
|---|---|---|
measurementSystem |
string
|
the name of the system to convert to |
- Inherited From:
a new measurement in the given system, or the current measurement if it is already in the given system or could not be converted
# expand(measurementsystemopt, unitsopt, constrain, scaleopt) → {Array.<Measurement>}
Expand the current measurement such that any fractions of the current unit are represented in terms of smaller units in the same system instead of fractions of the current unit. For example, "6.25 feet" may be represented as "6 feet 4 inches" instead. The return value is an array of measurements which are progressively smaller until the smallest unit in the system is reached or until there is a whole number of any unit along the way.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
measurementsystem |
string
|
<optional> |
system to use (uscustomary|imperial|metric), or undefined if the system can be inferred from the current measure |
units |
Array.<string>
|
<optional> |
object containing a mapping between the measurement system and an array of units to use to restrict the expansion to |
constrain |
function
|
a function that constrains a number according to the display options |
|
scale |
boolean
|
<optional> |
if true, rescale all of the units so that the largest unit is the largest one with a non-fractional number. If false, then the current unit stays the largest unit. |
- Inherited From:
an array of new measurements in order from the current units to the smallest units in the system which together are the same measurement as this one
Array.<Measurement>
# getAmount() → {number}
Return the numeric amount of this measurement.
- Inherited From:
the numeric amount of this measurement
number
# getMeasure() → {string}
Return the type of this measurement. Examples are "mass", "length", "speed", etc. Measurements can only be converted to measurements of the same type.
The type of the units is determined automatically from the units. For example, the unit "grams" is type "mass". Use the static call Measurement.getAvailableUnits to find out what units this version of ilib supports.
- Overrides:
the name of the type of this measurement
string
# getMeasurementSystem() → {string}
Return the name of the measurement system that the current unit is a part of.
- Inherited From:
the name of the measurement system for the units of this measurement
string
# getMeasures() → {Array.<string>}
Return an array of all units that this measurement types supports.
- Inherited From:
an array of all units that this measurement types supports
Array.<string>
# getOriginalUnit() → {string}
Return the units originally used to construct this measurement before it was normalized.
- Inherited From:
name of the unit of measurement
string
# getUnit() → {string}
Return the normalized units used in this measurement.
- Inherited From:
name of the unit of measurement
string
# getUnitIdCaseInsensitive(unit) → {string|undefined}
Return the normalized units identifier for the given unit, searching case-insensitively. This has the risk that things may match erroneously because many short form unit strings are case-sensitive. This should method be used as a last resort if no case-sensitive match is found amongst all the different types of measurements.
Parameters:
| Name | Type | Description |
|---|---|---|
unit |
string
|
the unit to find |
- Inherited From:
the normalized identifier for the given unit, or undefined if there is no such unit in this type of measurement
string
|
undefined
# list(measures, ratios, constrain, scaleopt) → {Array.<{unit: String, amount: Number}>}
Convert the current measurement to a list of measures and amounts. This method will autoScale the current measurement to the largest measure in the given measures list such that the amount of that measure is still greater than or equal to 1. From there, it will truncate that measure to a whole number and then it will calculate the remainder in terms of each of the smaller measures in the given list.
For example, if a person's height is given as 70.5 inches, and the list of measures is ["mile", "foot", "inch"], then it will scale the amount to 5 feet, 10.5 inches. The amount is not big enough to have any whole miles, so that measure is not used. The first measure will be "foot" because it is the first one in the measure list where the there is an amount of them that is greater than or equal to 1. The return value in this example would be:
[
{
"unit": "foot",
"amount": 5
},
{
"unit": "inch",
"amount": 10.5
}
]
Note that all measures except the smallest will be returned as whole numbers. The smallest measure will contain any possible fractional remainder.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
measures |
Array.<string>
|
undefined
|
array of measure names to convert this measure to |
|
ratios |
Object
|
the conversion ratios table for the measurement type |
|
constrain |
function
|
a function that constrains a number according to the display options |
|
scale |
boolean
|
<optional> |
if true, rescale all of the units so that the largest unit is the largest one with a non-fractional number. If false, then the current unit stays the largest unit. |
- Inherited From:
the conversion of the current measurement into an array of unit names and their amounts
Array.<{unit: String, amount: Number}>
# localize(locale) → {Measurement}
Localize the measurement to the commonly used measurement in that locale. For example If a user's locale is "en-US" and the measurement is given as "60 kmh", the formatted number should be automatically converted to the most appropriate measure in the other system, in this case, mph. The formatted result should appear as "37.3 mph".
Parameters:
| Name | Type | Description |
|---|---|---|
locale |
string
|
current locale string |
- Inherited From:
a new instance that is converted to locale
# newUnit(params) → {Measurement}
Return a new instance of this type of measurement.
Parameters:
| Name | Type | Description |
|---|---|---|
params |
Object
|
parameters to the constructor |
a measurement subclass instance
# normalizeUnits(name) → {string}
Return the normalized name of the given units. If the units are not recognized, this method returns its parameter unmodified.
Examples:
Parameters:
| Name | Type | Description |
|---|---|---|
name |
string
|
name of the units to normalize. |
- Inherited From:
normalized name of the units
string
# scale(measurementsystemopt, unitsopt) → {Measurement}
Scale the measurement unit to an acceptable level. The scaling happens so that the integer part of the amount is as small as possible without being below zero. This will result in the largest units that can represent this measurement without fractions. Measurements can only be scaled to other measurements of the same type.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
measurementsystem |
string
|
<optional> |
the name of the system to scale to |
units |
Object
|
<optional> |
mapping from the measurement system to the units to use for this scaling. If this is not defined, this measurement type will use the set of units that it knows about for the given measurement system |
- Inherited From:
a new instance that is scaled to the right level
# static convert(to, from, mass) → {number|undefined}
Convert a mass to another measure.
Parameters:
| Name | Type | Description |
|---|---|---|
to |
string
|
unit to convert to |
from |
string
|
unit to convert from |
mass |
number
|
amount to be convert |
the converted amount
number
|
undefined