Formatting quantities

Qty#toString returns a string using the canonical form of the quantity (that
is it could be seamlessly reparsed by Qty).

var qty =Qty('1.146 MPa');

qty.toString();// => '1.146 MPa'

As a shorthand, units could be passed to Qty#toString and is equivalent to
successively call Qty#to then Qty#toString.

var qty =Qty('1.146 MPa');

qty.toString('bar');// => '11.46 bar'

qty.to('bar').toString();// => '11.46 bar'

Qty#toString could also be used with any method from Qty to make some sort
of formatting. For instance, one could use Qty#toPrec to fix the maximum
number of decimals:

var qty =Qty('1.146 MPa');

qty.toPrec(0.1).toString();// => '1.1 MPa'

qty.to('bar').toPrec(0.1).toString();// => '11.5 bar'

For advanced formatting needs as localization, specific rounding or any other
custom customization, quantities can be transformed into strings through
Qty#format according to optional target units and formatter. If target units
are specified, the quantity is converted into them before formatting.

Such a string is not intended to be reparsed to construct a new instance of
Qty (unlike output of Qty#toString).

If no formatter is specified, quantities are formatted according to default
js-quantities' formatter and is equivalent to Qty#toString.

Qty#format could delegates formatting to a custom formatter if required. A
formatter is a callback function accepting scalar and units as parameters and
returning a formatted string representing the quantity.

varconfigurableRoundingFormatter=function(maxDecimals){

returnfunction(scalar,units){

var pow =Math.pow(10, maxDecimals);

var rounded =Math.round(scalar * pow)/ pow;

return rounded +''+ units;

};

};

var qty =Qty('1.1234 m');

// same units, custom formatter => '1.12 m'

qty.format(configurableRoundingFormatter(2));

// convert to 'cm', custom formatter => '123.4 cm'

qty.format('cm',configurableRoundingFormatter(1));

Custom formatter can be configured globally by setting Qty.formatter.

Qty.formatter=configurableRoundingFormatter(2);

var qty =Qty('1.1234 m');

qty.format();// same units, current default formatter => '1.12 m'

Temperatures

Like ruby-units, JS-quantities makes a distinction between a temperature (which
technically is a property) and degrees of temperature (which temperatures are
measured in).

Temperature units (i.e., 'tempK') can be converted back and forth, and will take
into account the differences in the zero points of the various scales.
Differential temperature (e.g., '100 degC') units behave like most other units.

Qty('37 tempC').to('tempF')// => 98.6 tempF

JS-quantities will throw an error if you attempt to create a temperature unit
that would fall below absolute zero.

Unit math on temperatures is fairly limited.

Qty('100 tempC').add('10 degC')// 110 tempC

Qty('100 tempC').sub('10 degC')// 90 tempC

Qty('100 tempC').add('50 tempC')// throws error

Qty('100 tempC').sub('50 tempC')// 50 degC

Qty('50 tempC').sub('100 tempC')// -50 degC

Qty('100 tempC').mul(scalar)// 100*scalar tempC

Qty('100 tempC').div(scalar)// 100/scalar tempC

Qty('100 tempC').mul(qty)// throws error

Qty('100 tempC').div(qty)// throws error

Qty('100 tempC*unit')// throws error

Qty('100 tempC/unit')// throws error

Qty('100 unit/tempC')// throws error

Qty('100 tempC').inverse()// throws error

Qty('100 tempC').to('degC')// => 100 degC

This conversion references the 0 point on the scale of the temperature unit

Qty('100 degC').to('tempC')// => -173.15 tempC

These conversions are always interpreted as being relative to absolute zero.
Conversions are probably better done like this...

Qty('0 tempC').add('100 degC')// => 100 tempC

Errors

Every error thrown by JS-quantities is an instance of Qty.Error.

try{

// code triggering an error inside JS-quantities

}

catch(e){

if(e instanceofQty.Error){

// ...

}

else{

// ...

}

}

Tests

Tests are implemented with Jasmine (https://github.com/pivotal/jasmine).
You could use both HTML and jasmine-node runners.

To execute specs through HTML runner, just open SpecRunner.html file in a
browser to execute them.

To execute specs through jasmine-node, launch:

make test

Performance regression test

There is a small benchmarking HTML page to spot performance regression between
currently checked-out quantities.js and any committed version.
Just execute: