https://github.com/clickermonkey/unitz
A unit parser, converter, & combiner in JS: '1 cup' + '1.5 pint' = '1 quart`
https://github.com/clickermonkey/unitz
Last synced: 11 months ago
JSON representation
A unit parser, converter, & combiner in JS: '1 cup' + '1.5 pint' = '1 quart`
- Host: GitHub
- URL: https://github.com/clickermonkey/unitz
- Owner: ClickerMonkey
- Created: 2016-06-09T14:44:48.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2018-10-01T01:28:34.000Z (over 7 years ago)
- Last Synced: 2025-03-20T08:45:02.038Z (11 months ago)
- Language: JavaScript
- Homepage: http://clickermonkey.github.io/unitz/
- Size: 360 KB
- Stars: 36
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
This library is no longer maintained, and has been replaced by [unitz-ts](https://github.com/ClickerMonkey/unitz-ts)
# Unitz
[](https://travis-ci.org/ClickerMonkey/unitz)
[](https://david-dm.org/ClickerMonkey/unitz#info=devDependencies)
[](https://david-dm.org/ClickerMonkey/unitz)
[](https://github.com/ClickerMonkey/unitz/blob/master/LICENSE)
[]()
Unitz is a library designed to take in a quantity and unit provided by a user and perform addition, subtraction, conversion, and transformation to human friendly representations.
Unitz will attempt to handle conversions, additions, and subtractions even if the units aren't recognized.
### Documentation
http://clickermonkey.github.io/unitz/
### Installation
Install via `bower install unitz` or `npm install unitz`.
Several classes are implemented - you can even add your own:
- Area
- Digital
- Length
- Rotation
- Time
- Volume
- Weight
Further down this document provides a detailed list of all units supported.
### Examples
```javascript
// =============================================================================
// Unitz.parse( input )
// =============================================================================
// Valid numbers: 1, 1/2, 1 1/2, 3/2, 1.5, .5, -1 1/2, -1.5, -.5
Unitz.parse('2c'); /*{
value: 2,
unit: 'c',
normal: '2 cups',
unitClass: ... // Unitz.Class instance
group: ... // Unitz.Group instance
}*/
// =============================================================================
// Unitz.parse( input ).convert( toUnit, returnFraction, withUnit, largestDenominator, classlessDenominators )
// =============================================================================
Unitz.parse('2c').convert('tbsp'); // 32
Unitz.parse('2 cup').convert('tbsp', false, true); // '32 tbsp'
Unitz.parse('4 tbsps').convert('cups', true); // {numerator: 1, denominator: 4, string: '1/4', remainder: 1, whole: 0, actual: 0.25, distance: 0, valid: true}
Unitz.parse('4 tbsps').convert('cups', true).string; // '1/4'
Unitz.parse('3 cups').convert('pint', true).string; // '1 1/2 pints'
// =============================================================================
// Unitz.parse( input ).best()
// Unitz.best( input )
// =============================================================================
Unitz.parse('2c').best().normal; // '1 pint'
Unitz.best('12in').normal; // '1 foot'
Unitz.best('1/4 cup').normal; // '2 fluid ounces'
// =============================================================================
// Unitz.compound( input, unitsAllowed )
// =============================================================================
Unitz.compound('2 cups', ['pt', 'c']); // '1 pt'
Unitz.compound('2 cups', ['c', 'tbsp']); // '2 c'
Unitz.compound('0.625 cups', ['c', 'tbsp', 'tsp']); // '1/2 c, 2 tbsp'
Unitz.compound('1.342 cups', ['c', 'tbsp', 'tsp']); // '1 c, 5 tbsp, 1 tsp'
// =============================================================================
// Unitz.combine( a, b, useFractions, abbreviations, largestDenominator )
// =============================================================================
Unitz.combine( '1 cup', '2 cups' ); // '3 cups'
Unitz.combine( '1 pint', '2 cup' ); // '1 quart'
Unitz.combine( '2 bags, 2 cup', '1 pint, 1 bag' ); // '3 bags, 1 quart'
// units that don't exist, but they look similar enough to intelligibly join (looks at first X characters) and intelligibly guess the correct singular/plural form.
Unitz.combine( '1 loaf', '2 loaves' ); // '3 loaves'
Unitz.combine( '2, 3, 4', '1 taco' ); // '10 taco'
Unitz.combine( '2, 3 tacos, 4', '1 taco' ); // '10 tacos'
// =============================================================================
// Unitz.subtract( a, b, allowNegatives, useFractions, abbreviations, largestDenominator )
// =============================================================================
Unitz.subtract( '2 bags, 3 pints', '1 bag, 1 quart' ); // '1 bag, 1 pint'
// =============================================================================
// Unitz.conversions( input, largestDenominator, min, max );
// =============================================================================
Unitz.conversions( '1.5 quarts' ); /* Unitz.Parsed with conversions: Unitz.Conversion
conversions[0]
decimal: 288
fraction: Unitz.Fraction
friendly: 288
group: Unitz.Group
longNormal: "288 teaspoons"
longUnit: "teaspoons"
shortNormal: "288 tsp"
shortUnit: "tsp"
...
conversions[3]
decimal: 6
fraction: Unitz.Fraction
friendly: 6
group: Unitz.Group
longNormal: "6 cups"
longUnit: "cups"
shortNormal: "6 c"
shortUnit: "c"
...
conversions[6]
decimal: 0.375
fraction: Unitz.Fraction
friendly: "3/8"
group: Unitz.Group
longNormal: "3/8 gallons"
longUnit: "gallons"
shortNormal: "3/8 gal"
shortUnit: "gal"
*/
```
## Classes
### Volume
- `['tsp', 'ts', 'tsps', 'teaspoon', 'teaspoons']`
- `['tbsp', 'tbsps', 'tablespoon', 'tablespoons']`
- `['oz', 'ounce', 'ounces', 'fl-oz', 'fl oz', 'floz', 'fluid ounce', 'fl. oz.', 'oz. fl.', 'oz fl']`
- `['c', 'cup', 'cups']`
- `['pt', 'pint', 'pints']`
- `['qt', 'quart', 'quarts']`
- `['gal', 'gallon', 'gallons']`
- `['ml', 'millilitre', 'millilitres', 'milliliter', 'milliliters']`
- `['l', 'litre', 'litres', 'liter', 'liters']`
- `['cl', 'centilitre', 'centilitres', 'centiliter', 'centiliters']`
- `['dl', 'decalitre', 'decalitres', 'decaliter', 'decaliters']`
- `['kl', 'kilolitre', 'kilolitres', 'kiloliter', 'kiloliters']`
- `['mm3', 'mm^3', 'cubic mm', 'cubic millimeter', 'cubic millimeters']`
- `['cm3', 'cm^3', 'cubiccmm', 'cubic centimeter', 'cubic centimeters']`
- `['m3', 'm^3', 'cubic m', 'cubic meter', 'cubic meters']`
- `['km3', 'km^3', 'cubic km', 'meter', 'meters']`
- `['in3', 'in^3', 'cubic in', 'cubic inch', 'cubic inches']`
- `['ft3', 'ft^3', 'cubic ft', 'cubic foot', 'cubic feet']`
- `['yd3', 'yd^3', 'cubic yd', 'cubic yard', 'cubic yards']`
### Weight
- `['mg', 'milligram', 'milligrams']`
- `['g', 'gram', 'grams']`
- `['kg', 'kilogram', 'kilograms', 'kilo', 'kilos']`
- `['oz', 'ounce', 'ounces']`
- `['lb', 'lbs', 'pound', 'pounds']`
- `['ton', 'tons', 'tonnes']`
### Length
- `['in', 'inch', 'inches', '"']`
- `['ft', 'foot', 'feet', "'"]`
- `['yd', 'yds', 'yard', 'yards']`
- `['mi', 'mile', 'miles']`
- `['league', 'leagues']`
- `['mm', 'millimeter', 'millimeters']`
- `['cm', 'centimeter', 'centimeters']`
- `['dc', 'decimeter', 'decimeters']`
- `['m', 'meter', 'meters']`
- `['km', 'kilometer', 'kilometers']`
### Time
- `['ns', 'nanosecond', 'nanoseconds', 'nano', 'nanos']`
- `['us', 'microsecond', 'microseconds', 'micros', 'micro']`
- `['ms', 'millisecond', 'milliseconds', 'millis']`
- `['s', 'second', 'seconds', 'sec', 'secs']`
- `['min', 'minute', 'minutes', 'mins']`
- `['hr', 'hour', 'hours', 'hrs']`
- `['day', 'days']`
- `['wk', 'week', 'weeks', 'wks']`
- `['yr', 'year', 'years', 'yrs']`
### Area
- `['sqin', 'sq. in.', 'sq in', 'in2', 'in^2', 'square inch', 'square inches']`
- `['sqft', 'sq. ft.', 'sq ft', 'ft2', 'ft^2', 'square foot', 'square feet']`
- `['sqyd', 'sq. yd.', 'sq yd', 'yd2', 'yd^2', 'square yard', 'square yards']`
- `['acre', 'acres']`
- `['sqmi', 'sq. mi.', 'sq mi', 'mi2', 'mi^2', 'square mile', 'square miles']`
- `['sqmm', 'sq. mm.', 'sq mm', 'mm2', 'mm^2', 'square millimeter', 'square millimeters']`
- `['sqcm', 'sq. cm.', 'sq cm', 'cm2', 'cm^2', 'square centimeter', 'square centimeters']`
- `['sqm', 'sq. m.', 'sq m', 'm2', 'm^2', 'square meter', 'square meters']`
- `['sqkm', 'sq. km.', 'sq km', 'km2', 'km^2', 'square kilometer', 'square kilometers']`
### Digital
- `['bit', 'bits']`
- `['nibble', 'nibbles']`
- `['b', 'byte', 'bytes']`
- `['kb', 'kilobyte', 'kilobytes']`
- `['mb', 'megabyte', 'megabytes']`
- `['gb', 'gigabyte', 'gigabytes']`
- `['tb', 'terabyte', 'terabytes']`
- `['pb', 'petabyte', 'petabytes']`
- `['eb', 'exabyte', 'exabytes']`
- `['kbit', 'kilobit', 'kilobits']`
- `['mbit', 'megabit', 'megabits']`
- `['gbit', 'gigabit', 'gigabits']`
- `['tbit', 'terabit', 'terabits']`
- `['pbit', 'petabit', 'petabits']`
- `['ebit', 'exabit', 'exabits']`
### Rotation
- `['deg', 'degs', 'degree', 'degrees']`
- `['rad', 'rads', 'radian', 'radians']`