# ben-ng/convert-units

An elegant way to convert quantities between different units.
JavaScript
Switch branches/tags
Nothing to show
Latest commit c129a45 Jul 5, 2017 2.3.1
 Failed to load latest commit information. lib Jul 6, 2017 test Jul 6, 2017 .gitignore Nov 9, 2015 .travis.yml Feb 22, 2017 Jakefile May 30, 2016 LICENSE Nov 8, 2015 README.md Jul 6, 2017 package.json Jul 6, 2017

# convert-units

A handy utility for converting between quantities in different 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:

```var convert = require('convert-units')

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

Jump from imperial to metric units the same way:

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

Just be careful not to ask for an impossible conversion:

```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 with optional exclusions:

```convert(1200).from('mm').toBest()
// 1.2 Meters (the smallest unit with a value above 1)

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

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

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

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

```convert().from('l').possibilities()
// [ 'ml', 'l', 'tsp', 'tbsp', '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:

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

You can also get the all the available units:

```convert().possibilities()
// [ 'mm', 'cm', 'm', 'in', 'ft-us', 'ft', 'mi', 'mcg', 'mg', 'g', 'kg', 'oz', 'lb', 'ml', 'l', 'tsp', 'Tbs', 'fl-oz', 'cup', 'pnt', 'qt', 'gal', 'ea', 'dz' ];```

To get a detailed description of a unit, use `describe`

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

To get detailed descriptions of all units, use `list`.

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

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

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

## Supported Units

• mm
• cm
• m
• in
• ft-us
• ft
• mi

• mm2
• cm2
• m2
• ha
• km2
• in2
• ft2
• ac
• mi2

• mcg
• mg
• g
• kg
• oz
• lb

• mm3
• cm3
• ml
• l
• kl
• m3
• km3
• tsp
• tbsp
• in3
• fl-oz
• cup
• pnt
• qt
• gal
• ft3
• yd3

• mm3/s
• cm3/s
• ml/s
• cl/s
• dl/s
• l/s
• l/min
• l/h
• kl/s
• kl/min
• kl/h
• m3/s
• m3/min
• m3/h
• km3/s
• tsp/s
• Tbs/s
• in3/s
• in3/min
• in3/h
• fl-oz/s
• fl-oz/min
• fl-oz/h
• cup/s
• pnt/s
• pnt/min
• pnt/h
• qt/s
• gal/s
• gal/min
• gal/h
• ft3/s
• ft3/min
• ft3/h
• yd3/s
• yd3/min
• yd3/h'

• C
• F
• K
• R

• ns
• mu
• ms
• s
• min
• h
• d
• week
• month
• year

• m/s
• km/h
• m/h
• knot
• ft/s

• Pa
• hPa
• kPa
• MPa
• bar
• torr
• psi
• ksi

• b
• Kb
• Mb
• Gb
• Tb
• B
• KB
• MB
• GB
• TB

• ppm
• ppb
• ppt
• ppq

• V
• mV
• kV

• A
• mA
• kA

• W
• mW
• kW
• MW
• GW

• VA
• mVA
• kVA
• MVA
• GVA

• VAR
• mVAR
• kVAR
• MVAR
• GVAR

• Wh
• mWh
• kWh
• MWh
• GWh
• J
• kJ

• VARh
• mVARh
• kVARh
• MVARh
• GVARh

### Want More?

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