618 lines
9.6 KiB
Markdown
618 lines
9.6 KiB
Markdown
## Unit conversion
|
|
|
|
Here's how you move between the metric units for volume:
|
|
|
|
```js
|
|
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();
|
|
// { val: 12, unit: 'm', plural: 'Meters' } (the smallest unit with a value above 1)
|
|
|
|
convert(12000).from('mm').toBest({ exclude: ['m'] });
|
|
// { val: 1200, unit: 'cm', plural: 'Centimeters' } (the smallest unit excluding meters)
|
|
|
|
convert(900).from('mm').toBest({ cutOffNumber: 10 });
|
|
// { val: 90, unit: 'cm', plural: 'Centimeters' } (the smallest unit with a value equal to or above 10)
|
|
|
|
convert(1000).from('mm').toBest({ cutOffNumber: 10 });
|
|
// { val: 100, unit: 'cm', plural: 'Centimeters' } (the smallest unit with a value equal to or above 10)
|
|
```
|
|
|
|
You can get a list of the measures available to the current instance with `.measures`
|
|
|
|
```js
|
|
convert().measures();
|
|
// [ 'length', 'mass', 'volume', ... ]
|
|
|
|
const differentConvert = configureMeasurements({
|
|
volume,
|
|
mass,
|
|
length,
|
|
area,
|
|
});
|
|
differentConvert().measures();
|
|
// [ 'length', 'mass', 'volume', 'area' ]
|
|
```
|
|
|
|
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',
|
|
}, ...]
|
|
*/
|
|
```
|
|
|
|
Custom Measures
|
|
---------------
|
|
|
|
It's possible to define custom measures if the ones packaged aren't what you need:
|
|
|
|
```js
|
|
import configureMeasurements from 'convert-units';
|
|
|
|
const customMeasure = {
|
|
systems: {
|
|
A: {
|
|
a: {
|
|
name: {
|
|
singular: 'a',
|
|
plural: 'as',
|
|
},
|
|
// to_anchor: The factor used to reach the base unit
|
|
// The base unit should have a to_anchor value of 1
|
|
// Eg. 1 a -> al = 1a * 1e-1 (to_anchor of al) = 10 al
|
|
to_anchor: 1,
|
|
},
|
|
al: {
|
|
name: {
|
|
singular: 'al',
|
|
plural: 'als',
|
|
},
|
|
to_anchor: 1e-1,
|
|
},
|
|
},
|
|
B: {
|
|
b: {
|
|
name: {
|
|
singular: 'b',
|
|
plural: 'bs',
|
|
},
|
|
to_anchor: 1,
|
|
},
|
|
bl: {
|
|
name: {
|
|
singular: 'bl',
|
|
plural: 'bls',
|
|
},
|
|
to_anchor: 1e-1,
|
|
},
|
|
},
|
|
C: {
|
|
c: {
|
|
name: {
|
|
singular: 'c',
|
|
plural: 'cs',
|
|
},
|
|
to_anchor: 1,
|
|
},
|
|
cl: {
|
|
name: {
|
|
singular: 'cl',
|
|
plural: 'cls',
|
|
},
|
|
to_anchor: 1e-1,
|
|
},
|
|
},
|
|
},
|
|
anchors: {
|
|
A: {
|
|
// unit a -> unit b
|
|
B: {
|
|
ratio: 2,
|
|
},
|
|
// unit a -> unit c
|
|
C: {
|
|
ratio: 3,
|
|
},
|
|
},
|
|
B: {
|
|
// unit b -> unit a
|
|
A: {
|
|
ratio: 1 / 2,
|
|
},
|
|
// unit b -> unit c
|
|
C: {
|
|
ratio: 3 / 2,
|
|
},
|
|
},
|
|
C: {
|
|
// unit c -> unit a
|
|
A: {
|
|
ratio: 1 / 3,
|
|
},
|
|
// unit c -> unit b
|
|
B: {
|
|
ratio: 2 / 3,
|
|
},
|
|
},
|
|
},
|
|
};
|
|
|
|
const convert = configureMeasurements({ customMeasure });
|
|
convert(1).from('a').to('bl')
|
|
// 20
|
|
```
|
|
|
|
The order of opperations goes as follows:
|
|
|
|
```js
|
|
// a -> bl
|
|
let v = 1 // 1 a
|
|
let a_to_anchor = 1 // systems.A.a.to_anchor
|
|
let r = v * a_to_anchor
|
|
// r = 1 a
|
|
let ratio = 2 // anchors.A.B.ratio
|
|
r *= ratio
|
|
// r = 2 b
|
|
let bl_to_anchor = 1e-1 // systems.B.bl.to_anchor
|
|
r /= b_to_anchor
|
|
// r = 20 bl
|
|
```
|
|
|
|
It's also possible to extend existing measures:
|
|
|
|
```ts
|
|
import configureMeasurements, {
|
|
length,
|
|
LengthSystems,
|
|
LengthUnits,
|
|
Measure
|
|
} from 'convert-units';
|
|
|
|
type NewLengthUnits = LengthUnits | 'px';
|
|
const DPI = 96;
|
|
const extendedLength: Measure<LengthSystems, NewLengthUnits> = {
|
|
systems: {
|
|
metric: {
|
|
...length.systems.metric,
|
|
px: {
|
|
name: {
|
|
singular: 'Pixel',
|
|
plural: 'Pixels',
|
|
},
|
|
to_anchor: 0.0254 / DPI,
|
|
},
|
|
},
|
|
imperial: {
|
|
...length.systems.imperial,
|
|
},
|
|
},
|
|
anchors: {
|
|
...length.anchors,
|
|
},
|
|
};
|
|
|
|
const convert = configureMeasurements<'length', LengthSystems, NewLengthUnits>(
|
|
{ length: extendedLength }
|
|
);
|
|
|
|
convert(4).from('cm').to('px');
|
|
// 151.18110236220474
|
|
```
|
|
|
|
Migrating from Old API
|
|
---------------------
|
|
|
|
This only applies if moving from `<=2.3.4` to `>=3.x`.
|
|
|
|
`index.js`
|
|
```js
|
|
import convert from 'convert-units';
|
|
|
|
convert(1).from('m').to('mm');
|
|
convert(1).from('m').to('ft');
|
|
```
|
|
|
|
The code above could be changed to match the following:
|
|
|
|
`index.js`
|
|
```js
|
|
import convert from './convert'; // defined below
|
|
|
|
convert(1).from('m').to('mm');
|
|
convert(1).from('m').to('ft');
|
|
```
|
|
|
|
`convert.js`
|
|
```js
|
|
import configureMeasurements, { allMeasures } from 'convert-units';
|
|
|
|
export default configureMeasurements(allMeasures);
|
|
```
|
|
|
|
Typescript
|
|
----------
|
|
|
|
Defining types can provide the benefit of exposing issues while working on your application.
|
|
|
|
```ts
|
|
import configureMeasurements, {
|
|
AllMeasures,
|
|
allMeasures,
|
|
AllMeasuresSystems,
|
|
AllMeasuresUnits,
|
|
area,
|
|
AreaSystems,
|
|
AreaUnits,
|
|
length,
|
|
LengthSystems,
|
|
LengthUnits,
|
|
} from 'convert-units';
|
|
|
|
// Meausres: The names of the measures being used
|
|
type Measures = 'length' | 'area';
|
|
// Systems: The systems being used across all measures
|
|
type Systems = LengthSystems | AreaSystems;
|
|
// Units: All the units across all measures and their systems
|
|
type Units = LengthUnits | AreaUnits;
|
|
const convert = configureMeasurements<Measures, Systems, Units>({
|
|
length,
|
|
area,
|
|
});
|
|
|
|
convert(4).from('m').to('cm');
|
|
// 400
|
|
|
|
// If you'd like to use all the packages measures that can be done like so
|
|
const convertAll = configureMeasurements<
|
|
AllMeasures,
|
|
AllMeasuresSystems,
|
|
AllMeasuresUnits
|
|
>(allMeasures);
|
|
|
|
convertAll(4).from('m2').to('cm2');
|
|
// 400000
|
|
```
|
|
|
|
Request Measures & Units
|
|
-----------------------
|
|
|
|
All new measures and additional units are welcome! Take a look at [`src/definitions`](https://github.com/convert-units/convert-units/tree/main/src/definitions) to see some examples.
|
|
|
|
Packaged Units
|
|
--------------
|
|
### Length
|
|
* nm
|
|
* μm
|
|
* mm
|
|
* cm
|
|
* m
|
|
* km
|
|
* in
|
|
* yd
|
|
* ft-us
|
|
* ft
|
|
* fathom
|
|
* mi
|
|
* nMi
|
|
|
|
### Area
|
|
* mm2
|
|
* cm2
|
|
* m2
|
|
* ha
|
|
* km2
|
|
* in2
|
|
* ft2
|
|
* ac
|
|
* mi2
|
|
|
|
### Mass
|
|
* mcg
|
|
* mg
|
|
* g
|
|
* kg
|
|
* oz
|
|
* lb
|
|
* mt
|
|
* t
|
|
|
|
### Volume
|
|
* mm3
|
|
* cm3
|
|
* ml
|
|
* l
|
|
* kl
|
|
* m3
|
|
* km3
|
|
* tsp
|
|
* Tbs
|
|
* in3
|
|
* fl-oz
|
|
* cup
|
|
* pnt
|
|
* qt
|
|
* gal
|
|
* ft3
|
|
* yd3
|
|
|
|
### Volume Flow Rate
|
|
* 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'
|
|
|
|
### Temperature
|
|
* C
|
|
* F
|
|
* K
|
|
* R
|
|
|
|
### Time
|
|
* ns
|
|
* mu
|
|
* ms
|
|
* s
|
|
* min
|
|
* h
|
|
* d
|
|
* week
|
|
* month
|
|
* year
|
|
|
|
### Frequency
|
|
* Hz
|
|
* mHz
|
|
* kHz
|
|
* MHz
|
|
* GHz
|
|
* THz
|
|
* rpm
|
|
* deg/s
|
|
* rad/s
|
|
|
|
### Speed
|
|
* m/s
|
|
* km/h
|
|
* mph
|
|
* knot
|
|
* ft/s
|
|
|
|
### Pace
|
|
* s/m
|
|
* min/km
|
|
* s/ft
|
|
* min/mi
|
|
|
|
### Pressure
|
|
* Pa
|
|
* hPa
|
|
* kPa
|
|
* MPa
|
|
* bar
|
|
* torr
|
|
* psi
|
|
* ksi
|
|
|
|
### Digital
|
|
* b
|
|
* Kb
|
|
* Mb
|
|
* Gb
|
|
* Tb
|
|
* B
|
|
* KB
|
|
* MB
|
|
* GB
|
|
* TB
|
|
|
|
### Illuminance
|
|
* lx
|
|
* ft-cd
|
|
|
|
### Parts-Per
|
|
* ppm
|
|
* ppb
|
|
* ppt
|
|
* ppq
|
|
|
|
### Voltage
|
|
* V
|
|
* mV
|
|
* kV
|
|
|
|
### Current
|
|
* A
|
|
* mA
|
|
* kA
|
|
|
|
### Power
|
|
* W
|
|
* mW
|
|
* kW
|
|
* MW
|
|
* GW
|
|
* PS
|
|
* Btu/s
|
|
* ft-lb/s
|
|
* hp
|
|
|
|
### Apparent Power
|
|
* VA
|
|
* mVA
|
|
* kVA
|
|
* MVA
|
|
* GVA
|
|
|
|
### Reactive Power
|
|
* VAR
|
|
* mVAR
|
|
* kVAR
|
|
* MVAR
|
|
* GVAR
|
|
|
|
### Energy
|
|
* Wh
|
|
* mWh
|
|
* kWh
|
|
* MWh
|
|
* GWh
|
|
* J
|
|
* kJ
|
|
|
|
### Reactive Energy
|
|
* VARh
|
|
* mVARh
|
|
* kVARh
|
|
* MVARh
|
|
* GVARh
|
|
|
|
### Angle
|
|
* deg
|
|
* rad
|
|
* grad
|
|
* arcmin
|
|
* arcsec
|
|
|
|
### Charge
|
|
* c
|
|
* mC
|
|
* μC
|
|
* nC
|
|
* pC
|
|
|
|
### Force
|
|
* N
|
|
* kN
|
|
* lbf
|
|
|
|
### Acceleration
|
|
* g (g-force)
|
|
* m/s2
|
|
|
|
### Pieces
|
|
* pcs
|
|
* bk-doz
|
|
* cp
|
|
* doz-doz
|
|
* doz
|
|
* gr-gr
|
|
* gros
|
|
* half-dozen
|
|
* long-hundred
|
|
* ream
|
|
* scores
|
|
* sm-gr
|
|
* trio
|
|
|