Units Module Reference

Related documents

• MVCS index

Table of contents

• Introduction
• Unit strings
  • Constants
• Exported identifiers and functions
  • Conversion functions
  • Constants
  • units
• units properties
  • defaultUnits
• units methods
  • addConversion()
  • convert()
  • fmtAbbrev()
  • getCurrentUnits()
  • isUnitString()
  • setAbbrev()
  • toCurrentUnits()

Introduction

The units module contains the units object and set of specific conversion functions.

The units object coordinates unit conversion for state variables. It provides a central way of naming units, providing unit abbreviations, and converting between dynanically specified units.

units is available for import from common/mvcs/exports.js.

Unit strings

Units are specified in string. The strings are usually related to the unit abbreviation for convenience, but are not identical (e.g., 'kg' vs 'kg.'). Unit strings may be added dynamically but many are built in. By default, the abbreviation is the unit string followed by a '.'.

The following list is the pre-defined units strings alaong with their abbreviations.

Distance

• 'cm' - centimeters
• 'm' - meters
• 'km' - kilometers
• 'in' - inches
• 'ft' - feet
• 'sm' - statute miles
• 'nm' - nautical miles

Fuel efficiency

• 'nmpl' - nautical miles per liter
• 'nmpg' - nautical miles per gallon

Pressure

• 'hpa' - hectopascals
• 'inhg' - inches of Mercury

Speed

• 'mps' - meters per second
• 'mph' - miles per hour
• 'km' - kilometers
• 'kt' - knots

Temperature

• 'dC' - °C (abbreviation: °C)
• 'dF' - °F (abbreviation: °F)

Time

• 'sec' - seconds
• 'min' - minutes
• 'hr' - hours

Volume

• 'l' - liters
• 'gal' - gallons

Weight

• 'kg' - kilograms
• 'lb' - pounds

Constants

Distance

• FTPERNM
  Feet per nautical mile
• MPERNM
  Meters per nautical mile
• FTPERSM
  Feet per statute mile
• FTPERM
  Feet per meter
• INPERCM
  Inches per centimeter

Volume

• GALPERL
  Gallons per liter

Weight

• LBPERKG
  Pounds per kilogram

Exported identifiers and functions

All exported values are available from common/units.js.

Conversion functions

The units module provides a set of conversion functions that provide a simpler interface to popular conversions. Conversion functions all take a single numeric argument and return a numeric value.

Angle

• degToRad(angle)
  Convert angle in degrees to angle in radians.

• pctToRad(pct)
  Convert angle in percent (opposite/adjacent) to angle in radians.

• radToDeg(rad)
  Convert angle in radians to angle in degrees.

Distance

• cmToIn(cm)
  Convert inches in centimeters to inches.

• ftToKm(ft)
  Convert distance in feet to kilometers.

• ftToM(ft)
  Convert distance in feet to meters.

• ftToNm(ft)
  Convert distance in feet to nautical miles.

• inToCm(inches)
  Convert in inches to centimeters.

• kmToFt(km)
  Convert distance in kilometers to feet.

• kmToNm(km)
  Convert distance in kilometers to nautical miles.

• mToFt(m)
  Convert distance in meters to feet.

• mToSm(m)
  Convert distance in meters to statute miles.

• nmToFt(nm)
  Convert distance in nautical miles to feet.

• nmToKm(nm)
  Convert distance in nautical miles. to kilometers.

• nmToSm(nm)
  Convert distance in nautical miles to statute miles.

• smToM(sm)
  Convert distance in statute miles to meters.

• smToNm(sm)
  Convert distance in statute miles to nautical miles.

Fuel efficiency

• nmplToNmpg(nmpl)
  Convert fuel efficiency in nautical miles per gallon to nautical miles per liter.

• nmpgToNmpl(nmpg)
  Convert fuel efficiency in nautical miles per liter to nautical miles per gallon.

Pressure

• hpaToInhg(hPa)
  Convert pressure in hectopascals to inches of Mercury.

• inhgToHpa(hg)
  Convert pressure in nches of Mercury to hectopascals.

Speed

• ktToMph(kt)
  Convert speed in knots to miles per hour.

• ktToMps(kt)
  Convert speed in knots to meters per second.

• mphToKt(mph)
  Convert speed in miles per hour to knots.

• mpsToKt(mps)
  Convert speed in meters per second to knots.

Temperature

• degCtoF(C)
  Convert temperature in °C to °F.

• degFtoC(F)
  Convert temperature in °F to °C.

• tempDiffCtoF(C)
  Convert temperature difference in °C to °F.

• tempDiffFtoC(F)
  Convert temperature difference in °F to °C.

Time

• hrToMin(hr)
  Convert time in hours to minutes.

• hrToMsec(hr)
  Convert time in hours to milliseconds.

• hrToSec(hr)
  Convert time in hours to seconds.

• minToHr(min)
  Convert time in minutes to hours.

• minToMsec(min)
  Convert time in minutes to milliseconds.

• msecToHr(msec)
  Convert time in milliseconds to hours.

• msecToMin(msec)
  Convert time in milliseconds to minutes.

• secToHr(sec)
  Convert time in seconds to hours.

Volume

• galToL(gal)
  Convert volume in gallons to liters.

• lToGal(l)
  Convert volume in liters to gallons.

Weight

• kgToLb(kg)
  Convert weight in kilograms to pounds.
• lbToKg(lb)
  Convert weight in pounds to kilograms.

Constants

Constants are available for import from common/mvcs/exports.js.

Distance

• FTPERM
  Feet per meter

• FTPERNM
  Feet per nautical mile

• FTPERSM
  Feet per statute mile

• INPERCM
  Inches per centimeter

• MPERNM
  Meters per nautical mile

Volume

• GALPERL
  Gallons per liter

Weight

• LBPERKG
  Pounds per kilogram

units

Syntax

import {units} from 'common/mvcs/export.js';

The units object contains the properties and methods used to define and manage units.

units properties

defaultUnits

An object that maps unit-type strings (e.g. 'weight', 'fuel') to the default unit string used by the application for that type. defaultUnits is read directly when looking up the default unit for a type, and is written by the app at startup to establish which units are in use.

The initial value is an empty object {}. The app populates it before any unit-aware computation takes place. For example:

units.defaultUnits = {weight: 'lb', fuel: 'gal', distance: 'nm'};

getCurrentUnits() reads from defaultUnits by default, so setting entries here is sufficient for apps that do not need dynamic unit switching.

units methods

addConversion()

Syntax

addConversion(from, to, fn)

Add a new conversion. The conversion units are specified as from and to. fn is a function that, given a value in from units, will return the value in to units. If the unit strings are not already present, they will be recorded in the internal list of available unit strings. Here's an example

units.addConversion('ft', 'm', ftToM);

Once a conversion is added, it is available for use via the convert() method.

Parameters

• from
  The unit string for the units to be converted from.
• to
  The unit string for the units to be converted to.
• fn
  A function or a string. If a function, it takes a single numeric value argument in from units and returns the equivalent value in to units. If a string, it must be an existing unit string for which conversions from from to fn and fn to to already exist. The addConversion() method will then compose the two existing conversion functions to make the function that converts from units to to units.

convert()

Syntax

convert(value, from, to)

Return value converted from units from to units to. If the to and from unit strings are identical the value is returned.

Parameters

• value
  The value to be converted.
• from
  The unit string for the units to be converted from.
• to
  The unit string for the units to be converted to.

Return value

A Number. The Converted value.

fmtAbbrev()

Syntax

fmtAbbrev(unitStr)

Return the abbreviation string for the unitstr unit string. By default, the abbreviation is the unit string followed by a '.'.

Parameters

• unitStr
  A unit string.

Return value

A String.

getCurrentUnits()

Syntax

getCurrentUnits(unitType)

Returns the current unit string for the given unitType. By default this returns units.defaultUnits[unitType], making it equivalent to a direct lookup. Apps that support dynamic unit switching (e.g., an in-flight toggle between 'lb' and 'kg') may replace this property with a function that returns the currently active unit for the type.

Parameters

• unitType
  A unit-type string (e.g. 'weight', 'fuel'). Must match a key set in defaultUnits.

Return value

A unit string, or undefined if the type has not been registered.

isUnitString()

Syntax

isUnitString(str)

Return true if str is an existing unit string.

Parameters

• str
  A string.

Return value

A Boolean.

setAbbrev()

Syntax

setAbbrev(unitStr, abbrev)

Add a custom abbreviation for unitStr. The abbrev string will override any existing abbreviations. By default, the abbreviation is the unit string followed by a '.'.

Parameters

• unitStr
  An existing unit string.
• abbrev
  A string for the custom abbreviation.

toCurrentUnits()

Syntax

toCurrentUnits(unitType, value)

Converts value from the default units for unitType to the currently active units for that type, as returned by getCurrentUnits(). If the current units are the same as the default units, value is returned unchanged.

Parameters

• unitType
  A unit-type string (e.g. 'weight', 'fuel'). Must match a key set in defaultUnits.
• value
  The numeric value to convert, expressed in defaultUnits[unitType] units.

Return value

A Number. The value converted to the current units for unitType.