@rwgps/units v1.2.0
rwgps-units
Library for converting and formatting rwgps units.
Currently supported unit types:
distance
- meters
- km
- feet
- miles
incline
- %
- degrees
speed
- mph
- kph
Example Usage:
Conversion:
import {convert} from '@rwgps/units'
convert(3.5).from('miles').to('km') // 5.632689999999999
convert(19).from('grade').to('degrees') // 10.757967088390005
alternatively, you can use the static function converters
import {conversions as C} from '@rwgps/units'
C.milesToKm(3.5) // 5.632689999999999
C.gradeToDegrees(10) // 10.757967088390005
Formatting:
All formatters expect native rwgps units. That means meters for distances, kph for speeds, and percentages for grades. They return unitType objects, which allow for flexible presentation of the result.
All formatters accept two arguments, value
and options
. value
should be the metric quanitity that you would like to format in rwgps native units. options
is an object that can contain the following configuration parameters:
metricUnits
(boolean) - Set this totrue
to output metric unitTypes. Defaults tofalse
.unit
(string) - Explicitly request a specific unitType as output. Will overridemetricUnits
if set....rest
- Other keys are passed through to the unitType constructor, and can be used to override the toLocaleString options used to format numeric labels. See the unitTypes documentation for more info about what you can pass here.
formatDistance
will automatically select between output in feet/meters or miles/km based on the length of the distance passed to it. You can override this behavior by requesting your desired units explicitly.
import {formatDistance} from '@rwpgs/units'
// 500m formatted in imperial units
const i = formatDistance(500)
i.value // 1640.4199475065616
i.long // "feet"
i.short // "ft"
i.compound // false
i.toString() // "1,640 feet"
i.toString({short: true}) // "1,640 ft"
i.valueToString() // "1,640"
// for more info about what arguments the toString and valueToString props accept
// see the documentation on unitTypes below
// 50km formatted in imperial units
formatDistance(50 * 1000).toString() // "31.1 miles"
// you can also request specific output units
formatDistance(50 * 1000, {units: 'feet'}).toString() // "164,042 feet"
// requesting metric units
formatDistance(50 * 1000, {metricUnits: true}).toString() // "50 kilometers"
formatDistance(500, {metricUnits: true}).toString() // "500 meters"
import {formatSpeed} from '@rwpgs/units'
formatSpeed(12).toString() // "7.5 miles per hour"
formatSpeed(12).toString({maximumFractionDigits: 3, short: true}) // "7.456 mph"
formatSpeed(12, {metricUnits: true}).toString() // "12 km per hour"
import {formatGrade} from '@rwgps/units'
// Newberry
formatGrade(12.2).toString() // 12.2 percent
formatGrade(12.2).toString({short: true}) // 12.2%
formatGrade(12.2, {units: 'degrees'}).toString() // 7.0 degrees
unitTypes
unitType
objects are used to provide rich formatting of returned units for display. They have the following properties:
value
- the numeric quantity being formattedlong
- the long unit type label (ex."meters"
or"percent"
)short
- the short unit type label (ex."m"
or"%"
)compound
-false
if the unit is not a compound unit type, otherwise a{numerator, denominator}
object of the component unitsvalueToString(opts)
- returns the value, formatted as a string.opts
is an options object that is passed through toNumber.toLocaleString
.toString({short = false, ...opts})
- returns the value and unit type label, formatted as a string.short
is a boolean parameter, defaultfalse
, which determines whether to render with a short or long unit label.opts
are passed through toNumber.toLocaleString
.