mi# Unitz
A unit parser, converter, & calculator for TypeScript and JS.
npm install unitz-ts, bower install unitz-ts, download// TypeScript
import { uz } from 'unitz';
// Javascript
var uz = Unitz.uz;
// Add built-in units
Unitz.Classes.addDefaults();
// Parsing
uz('2.5 cups'); // parses numbers
uz('1/2 in'); // parses fractions
uz('3 1/4'); // mixed fractions and unitless values
uz('mile'); // implicit values (1)
uz('4-5 seconds'); // parses ranges
uz('4s - 3min'); // parses ranges with mixed units
uz('2c, 4s, 23mi'); // mixed unit classes
uz('23 m/s, 60 mph, 2 1/2 liters per second'); // rates
// Transformations
uz('1.5 pints').normalize(); // = 3 cups: convert to unit in same class which is more human friendly
uz('1c, 1pt').compact(); // = 1.5 pt: join values in the same unit class together
uz('43in').expand(); // = 3 ft, 7 in: pull unit values of the same class apart to be more human friendly
// Operations
uz('1 pt').add('1 cup').normalize(); // = 3 cups
uz('1 pt').sub('1 cup').normalize(); // = 1 cup
uz('1 pt, 3 in').scale(2); // = 2 pt, 6 in
uz('1 pt, 3 in').scaleTo('6 c'); // = 3 pt, 9 in
// Convert
uz('1 - 2 gal').convert('c'); // = 16 - 32 c
uz('3 cup').conversions(); // = 3/16 gal, 3/4 qt, 1 1/2 pt, 3 c, 24 floz, 48 tbsp, 144 tsp
// Mutations
uz('3 cups').preferred(); // = 3 c: convert units to preferred
uz('-2 in, 4 mi, -2 - 2').positive(); // = 4 mi, 0 - 2: we only want positive
uz('-2 in, 4 mi, -2 - 2').negative(); // = -2 in, -2 - 0: we only want negative
uz('-2 in, 4 mi, 0 tacos').nonzero(); // = -2 in, 4 mi: we only want non-zero
uz('-2 in, 4 mi, -2 - 2').min(); // = -2 in, -2: we only the minimum values of a range
uz('-2 in, 4 mi, -2 - 2').max(); // = -2 in, 2: we only the maximum values of a range
uz('0.5 tsp').fractions(); // = 1/2 tsp: convert to fractions
uz('1/2 tsp').numbers(); // = 0.5 tsp: convert to numbers
// Sorting
uz('1 tsp, 1 pt, 4 gal').sort(); // = 4 gal, 1 pt, 1 tsp: sort values
// Dynamic unit groups
uz('1 loaf').add('4 loaves').normalize(); // = 5 loaves
// Output
uz('1 cup').output( options ); // the above functions return objects, to get a string you must call output which can take options to override the global output options.
// Alternative Input Formats
uz({ value: 34, unit: 'ms' }); // a single number value
uz({ num: 4, den: 12, unit: 'c' }); // a single fraction value
uz({ min: '4c', max: '8c' }); // a range with value strings
uz({ min:{value:1}, max:{value:2, unit:'m'} }); // range with value objects
uz([ '4c', '1-2m' ]); // range list of range/value strings
uz([ {value: 34, unit: 'ms'}, {min:'1m', max:'2m' ]); // range list of range/value objects
// Translations
Unitz.Translations.addDefaults();
uz('one pound'); // = 1 pound
uz('dozen tacos'); // = 12 tacos
uz('an eleven meters'); // = 11 meters
uz('a third of an acre'); // = 1/3acre
uz('half a dozen eggs'); // = 6eggs
uz('a seventh of a mile'); // = 1/7mile
uz('23 and a half eggs'); // = 23 1/2eggs
uz('one and a half acres'); // = 1 1/2acres
uz('23 and a third'); // = 23 1/3
uz('12 and one fourth cups'); // = 12 1/4cups
uz('(one and a half) acre'); // = 1 1/2acre
uz('(12) tacos'); // = 12 tacos
uz('1 (6 ounce)'); // = 6ounce
uz('5 (3 liter)'); // = 15liter
// Rates (aliases)
Unitz.Rates.addDefaults();
uz('60 mph');; // 60 miles/hour
uz('23 knots');; // 23 nautical miles/hour
You can customize exactly how Unitz behaves.
// The "distance" used to determine if a value is close enough to 0, 1, or if a calculated fraction is close enough to the real value.
Unitz.Functions.EPSILON = 0.001;
// The default settings for outputting values
Unitz.Core.globalOutput;
// The default settings for transforms
Unitz.Core.globalTransform;
// The default settings for sorting
Unitz.Core.globalSort;
// When preferred() is ran, use this unit
Unitz.Core.setPreferred( 'cup' );
// Set this unit group as common or uncommon
Unitz.Core.setCommon( 'cup', false ); // we don't use cups round these parts
// Set the denominators available for a unit group
Unitz.Core.setDenominators( 'cup', [2, 3, 4, 5, 6] );
// Add some units to an existing group
Unitz.Core.getGroup('cup').addUnits({
'cupz': Unitz.Plurality.PLURAL
});
// Remove some units from an existing group
Unitz.Core.getGroup('c').removeUnits(['cup', 'cups']);
// Add my own rate
Unitz.Rates.add('feet', 'second', ['fps']);
// Add my own class
Unitz.Core.addClass(new Class('Loaf', [
{
system: Unitz.System.ANY,
common: true,
unit: 'loaf',
baseUnit: 'loaf',
denominators: [2, 3, 4, 5, 6, 7, 8, 9, 10],
units: {
'loaf': Unitz.Plurality.SINGULAR,
'loaf of bread': Unitz.Plurality.SINGULAR,
'loafs': Unitz.Plurality.PLURAL,
'loaves': Unitz.Plurality.PLURAL,
'loaves of bread': Unitz.Plurality.PLURAL
}
}
]));
// To create dynamic groups Unitz looks at the first 3 characters to determine if two units are matches. You can override this by figuring out a value which can be used as a key.
Unitz.Core.getDynamicMatch = function(unit) {
// use soundex instead of the first three characters. cup and kup are equal now!
return soundex( unit );
};
// To override the logic for determining what value is "normal" (most user friendly)
Unitz.Core.isMoreNormal = function(fromValue, toValue, transform, forOutput) {
return true;
};
Angle:
Area:
Digital:
Length:
Temperature:
Time:
Volume:
Weight:
A map of classes is an object where the key is a unit and the value is a class.
A function which takes a number and returns a number.
A double object where both keys are units and the value is a Converter. This is used by Class to convert from one base unit to another.
An object where the key is a unit and a value is a Converter.
A function which takes a unit and returns a Group instance.
An array of groups.
An object of groups keyed by their units.
A type which is a single number or an array of numbers.
The types which can be passed as range inputs.
An array of ranges.
A function which takes a range and might return a range based on the given.
The types which can be passed as range list inputs.
A map of Rates by their abbreviations.
A function which provides a regular expression match, a group factory, and a constant variable which was provided earlier to run a translation and return the translated value.
An object which specifies the priority between different class types.
The priorities are numbers keyed by the class names.
A function which takes two ranges and returns a number which discribes the ordering relationship between the two ranges. If a < b then a negative value is returned. If a > b then a positive value is returned. If a = b then zero is returned.
A function which takes user input and a group factor and converts the user input into another string to be parsed by the next translator or the Parse class.
An object where the key is a unit and the value is a Plurality value. This is used when defining a group's units.
The types which can be passed as value inputs.
Creates a Translator which matches against a regular expression and when the user input matches the regular expression another handler function is called to translate the input. Optionally a constant value can be passed to this function and down to the translator.
The regular expression to match against user input.
The function to call if the input matched the expression.
The constant value to pass to the RegexTranslator.
A Translator function.
Takes user input and returns a new instance of [Base].
Generated using TypeDoc
The types which can be passed as base inputs.