@bstoots/convert-units

convert-units
=============


A handy utility for converting between quantities in different units.

Installation
-----

``
npm i @bstoots/convert-units
`

Usage
-----

convert-units has a simple chained API that is easy to read.

Here's how you move between the metric units for volume:

`js
var convert = require('@bstoots/convert-units')

convert(1).from('l').to('ml')
// 1000
`

Jump from imperial to metric units the same way:

`js
convert(1).from('lb').to('kg')
// 0.4536... (tested to 4 significant figures)
`

Just be careful not to ask for an impossible conversion:

`js
convert(1).from('oz').to('fl-oz')
// throws -- you can't go from mass to volume!
`

You can ask convert-units to select the best unit for you. You can also optionally explicitly exclude orders of magnitude or specify a cut off number for selecting the best representation.
`js
convert(12000).from('mm').toBest()
// 12 Meters (the smallest unit with a value above 1)

convert(12000).from('mm').toBest({ exclude: ['m'] })
// 1200 Centimeters (the smallest unit excluding meters)

convert(900).from('mm').toBest({ cutOffNumber: 10 });
// 90 Centimeters (the smallest unit with a value equal to or above 10)

convert(1000).from('mm').toBest({ cutOffNumber: 10 })
// 100 Centimeters (the smallest unit with a value equal to or above 10)
`

You can get a list of the measurement types supported with .measures

`js
convert().measures()
// [ 'length', 'mass', 'volume' ]
`

If you ever want to know the possible conversions for a unit, just use .possibilities

`js
convert().from('l').possibilities()
// [ 'ml', 'l', 'tsp', 'Tbs', 'fl-oz', 'cup', 'pnt', 'qt', 'gal' ]

convert().from('kg').possibilities()
// [ 'mcg', 'mg', 'g', 'kg', 'oz', 'lb' ]
`

You can also get the possible conversions for a measure:
`js
convert().possibilities('mass')
// [ 'mcg', 'mg', 'g', 'kg', 'oz', 'lb', 'mt', 't' ]
`

You can also get the all the available units:
`js
convert().possibilities()
// [ 'mm', 'cm', 'm', 'in', 'ft-us', 'ft', 'mi', 'mcg', 'mg', 'g', 'kg', 'oz', 'lb', 'mt', 't', 'ml', 'l', 'tsp', 'Tbs', 'fl-oz', 'cup', 'pnt', 'qt', 'gal', 'ea', 'dz' ];
`

To get a detailed description of a unit, use describe

`js
convert().describe('kg')
/*
{
abbr: 'kg'
, measure: 'mass'
, system: 'metric'
, singular: 'Kilogram'
, plural: 'Kilograms'
}
*/
`

To get detailed descriptions of all units, use list.

`js
convert().list()
/*
[{
abbr: 'kg'
, measure: 'mass'
, system: 'metric'
, singular: 'Kilogram'
, plural: 'Kilograms'
}, ...]
*/
`

You can also get detailed descriptions of all units for a measure:

`js
convert().list('mass')
/*
[{
abbr: 'kg'
, measure: 'mass'
, system: 'metric'
, singular: 'Kilogram'
, plural: 'Kilograms'
}, ...]
*/
`

Supported Units
---------------


$3

Adding new measurement sets is easy. Take a look at lib/definitions` to see how it's done.