diff --git a/README.md b/README.md index 87ab9b4..950a1ed 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,19 @@ Qty.parse('foo') // => null Qty.getKinds(); // => Array of names of every well-known kind of units ``` +### Available unit names by category + +```javascript +Qty.getUnits(); // => Object of unit arrays of every well-known kind of units +// Can be optionally restricted to only one kind +Qty.getUnits("length"); // => Array of all units of type length +``` +### Available well-known prefixes + +```javascript +Qty.getPrefix(); // => Array of arrays of every well-known kind of prefixes grouped by alias +``` + ### Quantity compatibility, kind and various queries ```javascript diff --git a/spec/quantitiesSpec.js b/spec/quantitiesSpec.js index d2cb152..997e18b 100644 --- a/spec/quantitiesSpec.js +++ b/spec/quantitiesSpec.js @@ -1239,6 +1239,34 @@ describe("js-quantities", function() { }); }); + describe("Qty.getUnits", function() { + it("should return a dictionary of categories with array units grouped by alises", function() { + var units = Qty.getUnits(), + expectedKey = "length", + expectedValue = ["m","meter","meters","metre","metres"]; + + expect(units[expectedKey]).toContain(expectedValue); + }); + + it("should optionally restrict returned units to one category", function() { + var units = Qty.getUnits("area"), + unexpectedValue = ["stone","stones","st"], + expectedValue = ["acre","acres"]; + + expect(units).not.toContain(unexpectedValue); + expect(units).toContain(expectedValue); + }); + }); + + describe("Qty.getPrefix", function() { + it("should return an array of array grouped by pefix", function() { + var prefixes = Qty.getPrefix(), + expectedValue = ["Ki","Kibi","kibi"]; + + expect(prefixes).toContain(expectedValue); + }); + }); + describe("information", function() { describe("bits and bytes", function() { it("should have 'information' as kind", function() { diff --git a/src/quantities.js b/src/quantities.js index 0e8d90e..ab798d9 100644 --- a/src/quantities.js +++ b/src/quantities.js @@ -500,6 +500,77 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI return (scalar + " " + units).trim(); } +/** + * Returns the object of available well-known units of per category + * returning a list of list per category e.g. + * + * @param {EMPTY} no parameter + * + * @returns {Object[]} names of categoires as keys, with array of units grouped + * by aliases + * mass: + * [ [ 'kg', 'kilogram', 'kilograms' ], + * [ 'u', 'AMU', 'amu' ], + * [ 'Da', 'Dalton', 'Daltons', 'dalton', 'daltons' ]] + * + * @param {string} kind - kind, string formated + * + * @returns {array} List of all units, group by alias + * + * [ [ 'kg', 'kilogram', 'kilograms' ], + * ['u', 'AMU', 'amu' ], + * [ 'Da', 'Dalton', 'Daltons', 'dalton', 'daltons']] + */ + Qty.getUnits = function(kind) { + var kinds = {}, + k; + for (var unitId in UNITS) { + k = UNITS[unitId][2]; + if (k.length === 0) { + continue; + } + if (kinds[k] === undefined) { + kinds[k] = []; + } + kinds[k].push(UNITS[unitId][0]); + } + if(kind) { + if(kinds[kind] === undefined) { + throw new QtyError(kind + ": Category not recognized."); + } + return kinds[kind]; + } + return kinds; + }; + +/** + * Returns the list of prefixes groups by prefix aliases e.g. + * ["Ki","Kibi","kibi"] + * + * @returns {array[]} names of kinds as keys, with values of + */ + Qty.getPrefix = function() { + var prefixes = []; + for (var unitId in UNITS) { + if (UNITS[unitId][2] == "prefix"){ + prefixes.push(UNITS[unitId][0]); + } + } + return prefixes; + }; + + /** + * Default formatter + * + * @param {number} scalar + * @param {string} units + * + * @returns {string} formatted result + */ + function defaultFormatter(scalar, units) { + return (scalar + " " + units).trim(); + } + /** * * Configurable Qty default formatter