{"_id":"@allisonshaw/js-quantities","_rev":"4-471900828d434cbbb7717e0edb8b878f","time":{"1.7.3":"2019-02-19T22:10:28.506Z","created":"2019-02-21T17:56:29.909Z","1.7.4-0":"2019-02-21T17:56:30.341Z","modified":"2022-04-04T13:33:20.175Z"},"name":"@allisonshaw/js-quantities","dist-tags":{"latest":"1.7.4-0"},"versions":{"1.7.4-0":{"name":"@allisonshaw/js-quantities","main":"./build/quantities.js","description":"JavaScript library for quantity calculation and unit conversion","version":"1.7.4-0","homepage":"https://github.com/allisonshaw/js-quantities","repository":{"type":"git","url":"git+https://github.com/allisonshaw/js-quantities.git"},"keywords":["conversion","convert","imperial","measure","measurement","metric","parse","parser","physical","quantity","quantities","temperature","unit","units"],"author":{"name":"Allison Shaw"},"contributors":[{"name":"Julien Sanchez","email":"julien.sanchez@gmail.com"},{"name":"Rage Shadowman","email":"ralph@crc-corp.com"},{"name":"Allison Shaw"}],"license":"MIT","scripts":{"test":"jasmine-node spec/","build:esm":"find src -iname *.js | rollup --file=build/quantities.esm.js --format=es --name=Qty src/quantities.js"},"bugs":{"url":"https://github.com/allisonshaw/js-quantities/issues"},"devDependencies":{"jasmine-node":"1.x","jscs":"^2.7.0","jshint":"^2.9.0","rollup":"~0.57"},"gitHead":"e53de35651106546d005c973f1fee36b6888f12e","_id":"@allisonshaw/js-quantities@1.7.4-0","_nodeVersion":"6.14.3","_npmVersion":"6.8.0","dist":{"integrity":"sha512-ECF7umVFtf3+HhZmPj6a41rPzTLAhzQycuK956dsfMN4h7z3i0Q4Q8lpQYJLeS72JuHHNFYfB6QkIpCl0oajzQ==","shasum":"266b6b6c63df137558e397b95b72433080d047c5","tarball":"https://registry.npmjs.org/@allisonshaw/js-quantities/-/js-quantities-1.7.4-0.tgz","fileCount":44,"unpackedSize":1778315,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcbuZOCRA9TVsSAnZWagAAMwwQAKG8FMlRlxPoyr3DLohW\nak61Hd2LJE2af9zVtqdi0VXL2kwHFW1pcDvUFRCgmlCpLJNMayzFVsdRhlN0\nOAyxrFBkK/GynT+LIkKcTRMmF91E5MBx75Cshatr6knxYs6AAL9kA1LoTzBy\n9/oW4Wp17aJGE+JW0aynFoi430rP/4NfRJZ3rFHERLOyE4cCaG66GsHtnda1\nRoUBMmV3aGUsiBdv1wNz3afA9PcJCV4fgx2NnF1S40U5vxpvHWGTgn2ihvhP\noayHukZRJm9L3Zb7DFcPlY5NW3M1V+9Cpcgan0ErUUMSEqD31x2l3IBS0u3U\nAJN81u/E6KAq4eqVpznZ4PyI9WRAsKqPxNhdqTKMvmJRc5n4OSLkNjdMoq7k\nj8aLgGPEKzX7fu6zC3/UPja4432c0Wd81o3n5tAjg7ZVaTqp6wzjLgeSBHNG\nxXzBu4bTmg8YThzLbWiq8V4QNUVsBev/O3OPtOe+GwIKmH/lz8x50j8EwI6K\nes0cib36dOFj6gMNeIHRiXabATs+FQTHnTRAJlSzodFdiOuSMu4PSSJHEz+D\n32lwNPFxY7kV/tubTfQiZhmhhjFPeb1z7q+ak+KtHhOqstTOpGQx94XWEsk+\nz1ItZ2aZt/ofBlMGfC5hwGF4hJXywTuugTZ7DYuN9piRzYIAnNy+Dh9cyvpU\nQ0Kb\r\n=s6/Z\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIDX+vZmnguXbymmQkBE5fgRq0ehzjn6iUMvvp6snuM+mAiBYTbs6srt/JP46jEpHAu0HvLX8d9x9ia8bnN7YCAoPIg=="}]},"maintainers":[{"name":"allisonshaw","email":"allisonshaw1016@gmail.com"}],"_npmUser":{"name":"allisonshaw","email":"allisonshaw1016@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/js-quantities_1.7.4-0_1550771790100_0.9828136849619689"},"_hasShrinkwrap":false}},"maintainers":[{"name":"allisonshaw","email":"allisonshaw1016@gmail.com"}],"description":"JavaScript library for quantity calculation and unit conversion","homepage":"https://github.com/allisonshaw/js-quantities","keywords":["conversion","convert","imperial","measure","measurement","metric","parse","parser","physical","quantity","quantities","temperature","unit","units"],"repository":{"type":"git","url":"git+https://github.com/allisonshaw/js-quantities.git"},"contributors":[{"name":"Julien Sanchez","email":"julien.sanchez@gmail.com"},{"name":"Rage Shadowman","email":"ralph@crc-corp.com"},{"name":"Allison Shaw"}],"author":{"name":"Allison Shaw"},"bugs":{"url":"https://github.com/allisonshaw/js-quantities/issues"},"license":"MIT","readme":"# JS-quantities\n\n[![Build Status](https://travis-ci.org/gentooboontoo/js-quantities.png)](https://travis-ci.org/gentooboontoo/js-quantities)\n\n***\nThis is a fork of [js-quantities](https://github.com/gentooboontoo/js-quantities) with temperature units (K, °C, °F, °R) aliased.\n\nNew aliases map to temperature NOT differential temperature.\n***\n\nJS-quantities is originally a JavaScript port of Kevin Olbrich's library Ruby\nUnits (http://github.com/olbrich/ruby-units).\n\nThe library aims to simplify the handling of units for scientific calculations\ninvolving quantities.\n\nJS-quantities is defined as an UMD module and can be used with AMD, Node\nand within browsers.\n\n## Installing JS-quantities\n\n### Browser\n\nDownload [latest release v1.7.4-0](https://raw.github.com/allisonshaw/js-quantities/v1.7.4-0/build/quantities.js)\nor install it with Bower:\n\n    bower install js-quantities\n\nThen include it:\n\n```html\n<script src='quantities.js'></script>\n```\n\nWhen using [Require.JS](http://requirejs.org/):\n\n```javascript\ndefine(['quantities'], function(Qty) {\n  ...\n});\n```\n\n### Node\n\n```\n$ npm install js-quantities\n$ node\n> var Qty = require('js-quantities');\n```\n\n## Synopsis\n\n### Creation\n\nInstances of quantities are made by means of `Qty()` method. `Qty` can both be\nused as a constructor (with new) or as a factory (without new):\n\n```javascript\nqty = new Qty('23 ft'); // constructor\nqty = Qty('23 ft'); // factory\n```\n\n`Qty` constructor accepts strings, numbers and `Qty` instances as\ninitializing values.\n\nIf scalars and their respective units are available programmatically, the\ntwo argument signature may be useful:\n\n```javascript\nqty = new Qty(124, 'cm'); // => 1.24 meter\nqty = Qty(124, 'cm'); // => 1.24 meter\n```\n\nFor the sake of simplicity, one will use the factory way below but using\n`new Qty()` is equivalent.\n\n```javascript\nqty = Qty('1m'); // => 1 meter\nqty = Qty('m'); // =>  1 meter (scalar defaults to 1)\n\nqty = Qty('1 N*m');\nqty = Qty('1 N m'); // * is optional\n\nqty = Qty('1 m/s');\n\nqty = Qty('1 m^2/s^2');\nqty = Qty('1 m^2 s^-2'); // negative powers\nqty = Qty('1 m2 s-2'); // ^ is optional\n\nqty = Qty('1 m^2 kg^2 J^2/s^2 A');\n\nqty = Qty('1.5'); // unitless quantity\nqty = Qty(1.5); // number as initializing value\n\nqty = Qty('1 attoparsec/microfortnight');\n\nqtyCopy = Qty(qty); // quantity could be copied when used as\n                    // initializing value\n```\n\n`Qty.parse` utility method is also provided to parse and create\nquantities from strings. Unlike the constructor, it will return `null`\ninstead of throwing an error when parsing an invalid quantity.\n\n```javascript\nQty.parse('1 m'); // => 1 meter\nQty.parse('foo') // => null\n```\n\n### Available well-known kinds\n\n```javascript\nQty.getKinds(); // => Array of names of every well-known kind of units\n```\n\n### Available units of a particular kind\n\n```javascript\nQty.getUnits('currency'); // => [ 'dollar', 'cents' ]\n// Or all alphabetically sorted\nQty.getUnits(); // => [ 'acre','Ah','ampere','AMU','angstrom']\n```\n\n### Alternative names of a unit\n\n```javascript\nQty.getAliases('m'); // => [ 'm', 'meter', 'meters', 'metre', 'metres' ]\n```\n\n### Quantity compatibility, kind and various queries\n\n```javascript\nqty1.isCompatible(qty2); // => true or false\n\nqty.kind(); // => 'length', 'area', etc...\n\nqty.isUnitless(); // => true or false\nqty.isBase(); // => true if quantity is represented with base units\n```\n\n### Conversion\n\n```javascript\nqty.toBase(); // converts to SI units (10 cm => 0.1 m) (new instance)\n\nqty.toFloat(); // returns scalar of unitless quantity\n               // (otherwise throws error)\n\nqty.to('m'); // converts quantity to meter if compatible\n             // or throws an error (new instance)\nqty1.to(qty2); // converts quantity to same unit of qty2 if compatible\n               // or throws an error (new instance)\n\nqty.inverse(); // converts quantity to its inverse\n               // ('100 m/s' => '.01 s/m')\n// Inverses can be used, but there is no special checking to\n// rename the units\nQty('10ohm').inverse() // '.1/ohm'\n                       // (not '.1S', although they are equivalent)\n// however, the 'to' command will convert between inverses also\nQty('10ohm').to('S') // '.1S'\n```\n\n`Qty.swiftConverter()` is a fast way to efficiently convert large array of\nNumber values. It configures a function accepting a value or an array of Number\nvalues to convert.\n\n```javascript\nvar convert = Qty.swiftConverter('m/h', 'ft/s'); // Configures converter\n\n// Converting single value\nvar converted = convert(2500); // => 2.278..\n\n// Converting large array of values\nvar convertedSerie = convert([2500, 5000, ...]); // => [2.278.., 4.556.., ...]\n```\n\nThe main drawback of this conversion method is that it does not take care of\nrounding issues.\n\n### Comparison\n\n```javascript\nqty1.eq(qty2); // => true if both quantities are equal (1m == 100cm => true)\nqty1.same(qty2); // => true if both quantities are same (1m == 100cm => false)\nqty1.lt(qty2); // => true if qty1 is stricty less than qty2\nqty1.lte(qty2); // => true if qty1 is less than or equal to qty2\nqty1.gt(qty2); // => true if qty1 is stricty greater than qty2\nqty1.gte(qty2); // => true if qty1 is greater than or equal to qty2\n\nqty1.compareTo(qty2); // => -1 if qty1 < qty2,\n                      // => 0 if qty1 == qty2,\n                      // => 1 if qty1 > qty2\n```\n\n### Operators\n\n* add(other): Add. other can be string or quantity. other should be unit compatible.\n* sub(other): Substract. other can be string or quantity. other should be unit compatible.\n* mul(other): Multiply. other can be string, number or quantity.\n* div(other): Divide. other can be string, number or quantity.\n\n### Rounding\n\n`Qty#toPrec(precision)` : returns the nearest multiple of quantity passed as\nprecision.\n\n```javascript\nvar qty = Qty('5.17 ft');\nqty.toPrec('ft'); // => 5 ft\nqty.toPrec('0.5 ft'); // => 5 ft\nqty.toPrec('0.25 ft'); // => 5.25 ft\nqty.toPrec('0.1 ft'); // => 5.2 ft\nqty.toPrec('0.05 ft'); // => 5.15 ft\nqty.toPrec('0.01 ft'); // => 5.17 ft\nqty.toPrec('0.00001 ft'); // => 5.17 ft\nqty.toPrec('2 ft'); // => 6 ft\nqty.toPrec('2'); // => 6 ft\n\nvar qty = Qty('6.3782 m');\nqty.toPrec('dm'); // => 6.4 m\nqty.toPrec('cm'); // => 6.38 m\nqty.toPrec('mm'); // => 6.378 m\nqty.toPrec('5 cm'); // => 6.4 m\nqty.toPrec('10 m'); // => 10 m\nqty.toPrec(0.1); // => 6.3 m\n\nvar qty = Qty('1.146 MPa');\nqty.toPrec('0.1 bar'); // => 1.15 MPa\n```\n\n### Formatting quantities\n\n`Qty#toString` returns a string using the canonical form of the quantity (that\nis it could be seamlessly reparsed by `Qty`).\n\n```javascript\nvar qty = Qty('1.146 MPa');\nqty.toString(); // => '1.146 MPa'\n```\n\nAs a shorthand, units could be passed to `Qty#toString` and is equivalent to\nsuccessively call `Qty#to` then `Qty#toString`.\n\n```javascript\nvar qty = Qty('1.146 MPa');\nqty.toString('bar'); // => '11.46 bar'\nqty.to('bar').toString(); // => '11.46 bar'\n```\n\n`Qty#toString` could also be used with any method from `Qty` to make some sort\nof formatting. For instance, one could use `Qty#toPrec` to fix the maximum\nnumber of decimals:\n\n```javascript\nvar qty = Qty('1.146 MPa');\nqty.toPrec(0.1).toString(); // => '1.1 MPa'\nqty.to('bar').toPrec(0.1).toString(); // => '11.5 bar'\n```\n\nFor advanced formatting needs as localization, specific rounding or any other\ncustom customization, quantities can be transformed into strings through\n`Qty#format` according to optional target units and formatter. If target units\nare specified, the quantity is converted into them before formatting.\n\nSuch a string is not intended to be reparsed to construct a new instance of\n`Qty` (unlike output of `Qty#toString`).\n\nIf no formatter is specified, quantities are formatted according to default\njs-quantities' formatter and is equivalent to `Qty#toString`.\n\n```javascript\nvar qty = Qty('1.1234 m');\nqty.format(); // same units, default formatter => '1.234 m'\nqty.format('cm'); // converted to 'cm', default formatter => '123.45 cm'\n```\n\n`Qty#format` could delegates formatting to a custom formatter if required. A\nformatter is a callback function accepting scalar and units as parameters and\nreturning a formatted string representing the quantity.\n\n```javascript\nvar configurableRoundingFormatter = function(maxDecimals) {\n  return function(scalar, units) {\n    var pow = Math.pow(10, maxDecimals);\n    var rounded = Math.round(scalar * pow) / pow;\n\n    return rounded + ' ' + units;\n  };\n};\n\nvar qty = Qty('1.1234 m');\n\n// same units, custom formatter => '1.12 m'\nqty.format(configurableRoundingFormatter(2));\n\n// convert to 'cm', custom formatter => '123.4 cm'\nqty.format('cm', configurableRoundingFormatter(1));\n```\n\nCustom formatter can be configured globally by setting `Qty.formatter`.\n\n```javascript\nQty.formatter = configurableRoundingFormatter(2);\nvar qty = Qty('1.1234 m');\nqty.format(); // same units, current default formatter => '1.12 m'\n```\n\n### Temperatures\n\nLike ruby-units, JS-quantities makes a distinction between a temperature (which\ntechnically is a property) and degrees of temperature (which temperatures are\nmeasured in).\n\nTemperature units (i.e., 'tempK') can be converted back and forth, and will take\ninto account the differences in the zero points of the various scales.\nDifferential temperature (e.g., '100 degC') units behave like most other units.\n\nTemperatures aliased with the actual degree symbols (K, °C, °F, °R) are temperature units and NOT differential units.\n\n```javascript\nQty('37 tempC').to('tempF') // => 98.6 tempF\n```\n\nJS-quantities will throw an error if you attempt to create a temperature unit\nthat would fall below absolute zero.\n\nUnit math on temperatures is fairly limited.\n\n```javascript\nQty('100 tempC').add('10 degC')  // 110 tempC\nQty('100 tempC').sub('10 degC')  // 90 tempC\nQty('100 tempC').add('50 tempC') // throws error\nQty('100 tempC').sub('50 tempC') // 50 degC\nQty('50 tempC').sub('100 tempC') // -50 degC\nQty('100 tempC').mul(scalar)     // 100*scalar tempC\nQty('100 tempC').div(scalar)     // 100/scalar tempC\nQty('100 tempC').mul(qty)        // throws error\nQty('100 tempC').div(qty)        // throws error\nQty('100 tempC*unit')            // throws error\nQty('100 tempC/unit')            // throws error\nQty('100 unit/tempC')            // throws error\nQty('100 tempC').inverse()       // throws error\n```\n\n```javascript\nQty('100 tempC').to('degC') // => 100 degC\n```\n\nThis conversion references the 0 point on the scale of the temperature unit\n\n```javascript\nQty('100 degC').to('tempC') // => -173.15 tempC\n```\n\nThese conversions are always interpreted as being relative to absolute zero.\nConversions are probably better done like this...\n\n```javascript\nQty('0 tempC').add('100 degC') // => 100 tempC\n```\n\n### Errors\n\nEvery error thrown by JS-quantities is an instance of `Qty.Error`.\n\n```javascript\ntry {\n  // code triggering an error inside JS-quantities\n}\ncatch(e) {\n  if(e instanceof Qty.Error) {\n    // ...\n  }\n  else {\n    // ...\n  }\n}\n```\n\n## Tests\n\nTests are implemented with Jasmine (https://github.com/pivotal/jasmine).\nYou could use both HTML and jasmine-node runners.\n\nTo execute specs through HTML runner, just open `SpecRunner.html` file in a\nbrowser to execute them.\n\nTo execute specs through `jasmine-node`, launch:\n\n    make test\n\n### Performance regression test\n\nThere is a small benchmarking HTML page to spot performance regression between\ncurrently checked-out quantities.js and any committed version.\nJust execute:\n\n    make bench\n\nthen open http://0.0.0.0:3000/bench\n\nChecked-out version is benchmarked against HEAD by default but it could be changed by passing\nany commit SHA on the command line. Port (default 3000) is also configurable.\n\n    make bench COMMIT=e0c7fc468 PORT=5000\n\n## Contribute\n\nFeedback and contributions are welcomed.\n\nPull requests must pass tests and linting. Please make sure that `make test`\nand `make lint` return no errors before submitting.\n","readmeFilename":"README.md"}