Skip to content
A unit parser, converter, & combiner in JS: '1 cup' + '1.5 pint' = '1 quart`
JavaScript HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
build
src
test
.gitignore
.jshintrc
.travis.yml
Gulpfile.js
README.md
bower.json
jsdoc.json
package.json

README.md

This library is no longer maintained, and has been replaced by unitz-ts

Unitz

Build Status devDependency Status Dependency Status License Alpha

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

// =============================================================================
// 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']
You can’t perform that action at this time.