Class

MassUnit

MassUnit(options)

Create a new mass measurement instance.

Constructor

# new MassUnit(options)

Parameters:
Name Type Description
options Object

Options controlling the construction of this instance

unit string
amount number | string | undefined

View Source MassUnit.js, line 37

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:

View Source Measurement.js, line 196

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:

View Source Measurement.js, line 222

a new measurement in the given system, or the current measurement if it is already in the given system or could not be converted

Measurement

# 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:

View Source Measurement.js, line 291

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:

View Source Measurement.js, line 115

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:

View Source MassUnit.js, line 154

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:

View Source Measurement.js, line 150

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:

View Source Measurement.js, line 139

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:

View Source Measurement.js, line 107

name of the unit of measurement

string

# getUnit() → {string}

Return the normalized units used in this measurement.

Inherited From:

View Source Measurement.js, line 98

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:

View Source Measurement.js, line 452

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:

View Source Measurement.js, line 348

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:

View Source Measurement.js, line 173

a new instance that is converted to locale

Measurement

# newUnit(params) → {Measurement}

Return a new instance of this type of measurement.

Parameters:
Name Type Description
params Object

parameters to the constructor

View Source MassUnit.js, line 73

a measurement subclass instance

Measurement

# normalizeUnits(name) → {string}

Return the normalized name of the given units. If the units are not recognized, this method returns its parameter unmodified.

Examples:

  • "metres" gets normalized to "meter"
  • "ml" gets normalized to "milliliter"
  • "foobar" gets normalized to "foobar" (no change because it is not recognized)
  • Parameters:
    Name Type Description
    name string

    name of the units to normalize.

    Inherited From:

    View Source Measurement.js, line 88

    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:

    View Source Measurement.js, line 251

    a new instance that is scaled to the right level

    Measurement

    # 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

    View Source MassUnit.js, line 242

    the converted amount

    number | undefined