Units Module Reference

Related documents

• MVCS index

Table of contents

• Introduction
• Unit strings
  • Registered conversions
• 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 and the conversion functions and constants are exported from source/app/common/option/units.js. It is not re-exported from common/mvcs/export.js. Other common modules import it as ../option/units.js, and apps import it as ../common/option/units.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 '.', unless the unit string already ends with a '.'. Abbreviations that differ from that default are noted below.

The following list is the pre-defined unit strings (those registered by addConversion() in units.js) along with their abbreviations.

Distance

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

Fuel efficiency

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

Fuel flow

• 'gph' - gallons per hour
• 'gpm' - gallons per minute
• 'lph' - liters per hour
• 'pph' - pounds per hour
• 'kgph' - kilograms per hour

Gradient

• 'fpnm' - feet per nautical mile
• 'pct' - percent (opposite/adjacent) (abbreviation: %)

Pressure

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

Speed

• 'mps' - meters per second
• 'mph' - miles per hour
• 'kt' - knots
• 'kias' - knots indicated airspeed
• 'mias' - miles per hour indicated airspeed

Temperature

• 'dC' - °C (abbreviation: °C)
• 'dF' - °F (abbreviation: °F)
• 'C' - °C
• 'F' - °F
• 'dCr' - relative (difference) °C
• 'dFr' - relative (difference) °F

Time

• 'min' - minutes
• 'hr' - hours

Volume

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

Weight

• 'kg' - kilograms
• 'lb' - pounds (abbreviation: lb.)

Two further abbreviations are set for the fuel-weight strings 'lbf' (lb.) and 'kgf' (kg.), although no conversions are currently registered for them. The strings 'km' and 'sec' are not registered unit strings (isUnitString() returns false for them), although conversion functions involving kilometers and seconds exist.

Registered conversions

The following conversions are registered with units.addConversion() and can be used with convert(). Pairs marked with a conversion function use it directly. The others are composed from existing conversions.

• Altimeter: inhg ↔ hpa.
• Length: ft ↔ m, ft ↔ in, m ↔ cm, cm ↔ in, ft ↔ cm, m ↔ in, nm ↔ sm.
• Volume: gal ↔ l.
• Weight: lb ↔ kg.
• Fuel efficiency: nmpg ↔ nmpl.
• Fuel flow: gpm ↔ gph, gph ↔ lph, pph ↔ kgph.
• Speed: kt ↔ mph, kt ↔ mps, mph ↔ mps, kias ↔ mias.
• Temperature: dC ↔ dF, C ↔ F, dCr ↔ dFr.
• Time: hr ↔ min.
• Gradient: fpnm ↔ pct.

Exported identifiers and functions

All exported values are available from source/app/common/option/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 distance in centimeters to inches. The result is rounded to the nearest 0.1.

• 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 distance in inches to centimeters. The result is rounded to the nearest 0.1.

• 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 liter to nautical miles per gallon.

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

Gradient

• fpnmToPct(fpnm)
  Convert gradient in feet per nautical mile to percent (100 × fpnm / FT_PER_NM).

• pctToFpnm(pct)
  Convert gradient in percent to feet per nautical mile.

Pressure

• hpaToInhg(hPa)
  Convert pressure in hectopascals to inches of Mercury. The result is rounded to 2 decimal places.

• inhgToHpa(hg)
  Convert pressure in inches of Mercury to hectopascals. The result is rounded to an integer.

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 exported from source/app/common/option/units.js.

Distance

• FT_PER_M
  Feet per meter (3.2808)

• FT_PER_NM
  Feet per nautical mile (6076.1)

• FT_PER_SM
  Feet per statute mile (5280)

• IN_PER_CM
  Inches per centimeter (12 × FT_PER_M / 100)

• M_PER_NM
  Meters per nautical mile (1852)

Volume

• GAL_PER_L
  Gallons per liter (0.26417)

Weight

• LB_PER_KG
  Pounds per kilogram (2.2046)

units

Syntax

import {units} from '../common/option/units.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. If a custom abbreviation has been set with setAbbrev() it is returned. Otherwise, the abbreviation is the unit string followed by a '.', unless the unit string already ends with 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 '.' (unless it already ends with 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.