Class ilib.Measurement

Create a measurement instance. The measurement is immutable once it is created, but can be converted to other measurements later.

The options may contain any of the following properties:

amount - either a numeric amount for this measurement given as a number of the specified units, or another ilib.Measurement instance to convert to the requested units. If converting to new units, the type of measure between the other instance's units and the current units must be the same. That is, you can only convert one unit of mass to another. You cannot convert a unit of mass into a unit of length.
unit - units of this measurement. Use the static call ilib.Measurement.getAvailableUnits to find out what units this version of ilib supports. If the given unit is not a base unit, the amount will be normalized to the number of base units and stored as that number of base units. For example, if an instance is constructed with 1 kg, this will be converted automatically into 1000 g, as grams are the base unit and kg is merely a commonly used scale of grams.

Here are some examples of converting a length into new units. The first method is via the constructor by passing the old measurement in as the amount property.

var measurement1 = new ilib.Measurement({
  amount: 5,
  units: "kilometers"
});
var measurement2 = new ilib.Measurement({
  amount: measurement1,
  units: "miles"
});

The value in measurement2 will end up being about 3.125 miles. The second method will be using the convert method.

var measurement1 = new ilib.Measurement({
  amount: 5,
  units: "kilometers"
});
var measurement2 = measurement1.convert("miles");
});

The value in measurement2 will again end up being about 3.125 miles.
Defined in: ilib-dyn-full.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	ilib.Measurement(options)

Method Summary
Method Attributes	Method Name and Description
	convert(to) Return a new measurement instance that is converted to a new measurement unit.
	getAmount() Return the numeric amount of this measurement.
<static>	ilib.Measurement.getAvailableUnits() Return a list of all possible units that this version of ilib supports.
	getMeasure() Return the type of this measurement.
	getOriginalUnit() Return the units originally used to construct this measurement before it was normalized.
	getUnit() Return the normalized units used in this measurement.
	localize(locale) 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.
	normalizeUnits(name) Return the normalized name of the given units.
	scale(measurementsystem) Scale the measurement unit to an acceptable level.

Class Detail

ilib.Measurement(options)

Parameters:
{Object} options: options that control the construction of this instance

Method Detail

{ilib.Measurement|undefined} convert(to)

Return a new measurement instance that is converted to a new measurement unit. Measurements can only be converted to measurements of the same type.

Parameters:
{string} to: The name of the units to convert to

Returns:: {ilib.Measurement|undefined} the converted measurement or undefined if the requested units are for a different measurement type

{number} getAmount()

Return the numeric amount of this measurement.

Returns:: {number} the numeric amount of this measurement

<static> {Array.<string>} ilib.Measurement.getAvailableUnits()

Return a list of all possible units that this version of ilib supports. Typically, the units are given as their full names in English. Unit names are case-insensitive.

Returns:: {Array.<string>} an array of strings containing names of units available

{string} getMeasure()

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 ilib.Measurement.getAvailableUnits to find out what units this version of ilib supports.

Returns:: {string} the name of the type of this measurement

{string} getOriginalUnit()

Return the units originally used to construct this measurement before it was normalized.

Returns:: {string} name of the unit of measurement

{string} getUnit()

Return the normalized units used in this measurement.

Returns:: {string} name of the unit of measurement

{ilib.Measurement} localize(locale)

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:
{string} locale: current locale string

Returns:: {ilib.Measurement} a new instance that is converted to locale

{string} normalizeUnits(name)

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:
{string} name: name of the units to normalize.

Returns:: {string} normalized name of the units

{ilib.Measurement} scale(measurementsystem)

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:
{string=} measurementsystem: system to use (uscustomary|imperial|metric), or undefined if the system can be inferred from the current measure

Returns:: {ilib.Measurement} a new instance that is scaled to the right level

Classes

Class ilib.Measurement