measurement
Version:
A flexible library for handling unit conversions
113 lines (75 loc) • 3.09 kB
Markdown
Measurement [](https://travis-ci.org/jfelsinger/measurement) [](https://github.com/igrigorik/ga-beacon)
===========
A flexible library for handling unit conversions
```
npm install measurement
```
or include it on your page.
```
<script src="dist/measurement.min.js" type="text/javascript"></script>
```
To start initialize a new instance of the measurement factory.
```
var measurement = require('measurement');
var mf = new measurement.Factory();
// Get a new measurement
var measurement = mf.km(25);
// from a string
measurement = mf.measure('25km');
// or
measurement = mf.measurement('25km');
// as a combination of a scalar value and a unit
measurement = mf.measure(25, 'km');
measurement = mf.measure(25, mf.units.km);
// or
measurement = mf.measurement(25, 'km');
measurement = mf.measurement(25, mf.units.km);
// Get the scalar value that represent the measurement
var value = measurement.getValue();
// Get the value in terms of another unit
var valueInMeters = measurement.getValue('m'); // or .getValue(mf.units.m);
```
Measurements can be converted from one unit to another by calling
a unit method or by using the generic ``to()`` and ``as()`` methods.
```
measurement = mf.km(8);
// convert to miles using the unit method
var miles = measurement.mi();
// using the as() method returns a copy with the converted unit
var miles = measurement.as('mi');
var miles = measurement.as(mf.units.mi);
// using to() converts the object itself to the given unit
measurement.to('mi');
measurement.to(mf.units.mi);
```
Compound units can be built up from the base units of ``TIME``, ``LENGTH``,
``VOLUME``, ``MEMORY``, and ``MASS`` to represent values such as speed or
transfer rate.
```
var distance = mf.km(25);
// The per() method adds another unit to the current, compounding it
var speed = distance.per('hr'); // or per(mf.units.hr)
// There isn't a hard limit to the amount of units you can compound on
// 25km/hr/s, acceleration at a pace of 25km/hr every second
var acceleration = speed.per('s'); // mf.km(25).per('hr').per('s')
```
Measurements with compound units are special and act as an array of different
units bunched together. The unit methods act on separate pieces of compound units,
while the ``to()`` and ``as()`` methods act differently whether another compound
unit or a base unit is supplied.
```
var speed = mf.km(25).per('hr'); // => 25km/h
// Using the unit method to convert to mi/h
var mph = speed.mi();
// Unit methods default to changing the first unit in the list,
// but they can also be supplied a zero-based index
var metersPerSecond = speed.m().s(1); // => 6.9444m/s
// All of the functions that deal with units can take an index parameter to
// deal with the individual parts of compound units
var valueInKilometersPerSecond = speed.getValue('s', 1);
```