Skip to content

ClickerMonkey/unitz

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

20 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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']