Unitz

A unit parser, converter, & calculator for TypeScript and JS.

• Documentation
• Online Tool
• Installation npm install unitz-ts, bower install unitz-ts, download

// TypeScript
import { uz, Classes } from 'unitz-ts';

// Add built-in units
Classes.addDefaults(); 

// Javascript
var uz = Unitz.uz;

Unitz.Classes.addDefaults(); // Add built-in units

// 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

Customization

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;
};

Supported Units

Angle:

• deg, °, degree, degrees
• rad, radian, radians

Area:

• sqin, sq. in, sq in, in2, in^2, in², inch2, inch^2, inch², inches2, inches^2, inches², square in, square inch, square inches
• sqft, sq. ft, sq ft, ft2, ft^2, ft², foot2, foot^2, foot², feet2, feet^2, feet², square ft, square foot, square feet
• sqyd, sq. yd, sq yd, yd2, yd^2, yd², yard2, yard^2, yard², yards2, yards^2, yards², square yd, square yard, square yards
• acre, acres
• sqmi, sq. mi, sq mi, mi2, mi^2, mi², mile2, mile^2, mile², miles2, miles^2, miles², square mi, square mile, square miles
• sqmm, sq. mm, sq mm, mm2, mm^2, mm², millimeter2, millimeter^2, millimeter², millimeters2, millimeters^2, millimeters², square mm, square millimeter, square millimeters
• sqcm, sq. cm, sq cm, cm2, cm^2, cm², centimeter2, centimeter^2, centimeter², centimeters2, centimeters^2, centimeters², square cm, square centimeter, square centimeters
• sqm, sq. m, sq m, m2, m^2, m², meter2, meter^2, meter², meters2, meters^2, meters², square m, square meter, square meters
• sqkm, sq. km, sq km, km2, km^2, km², kilometer2, kilometer^2, kilometer², kilometers2, kilometers^2, kilometers², square km, square kilometer, square kilometers

Digital:

• b, bit, bits
• nibble, nibbles, nybble, nyble, half-byte, half byte, tetrade, semi-octent, quadbit, quartet
• B, byte, bytes
• kB, kilobyte, kilobytes
• mB, megabyte, megabytes
• gB, gigabyte, gigabytes
• tB, terabyte, terabytes
• pB, petabyte, petabytes
• eB, exabyte, exabytes
• zB, zettabyte, zettabytes
• yB, yottabyte, yottabytes
• KB, kibibyte, kibibytes
• MB, mebibyte, mebibytes
• GB, gibibyte, gibibytes
• TB, tebibyte, tebibytes
• PB, pebibyte, pebibytes
• EB, exbibyte, exbibytes
• ZB, zebibyte, zebibytes
• YB, yobibyte, yobibytes
• kb, kilobit, kilobits
• mb, megabit, megabits
• gb, gigabit, gigabits
• tb, terabit, terabits
• pb, petabit, petabits
• eb, exabit, exabits
• zb, zettabit, zettabits
• yb, yottabit, yottabits
• kibit, kibibit, kibibits
• mibit, mebibit, mebibits
• gibit, gibibit, gibibits
• tibit, tebibit, tebibits
• pibit, pebibit, pebibits
• eibit, exbibit, exbibits
• zibit, zebibit, zebibits
• yibit, yobibit, yobibits

Length:

• in, inch, inches, "
• ft, foot, feet, '
• yd, yard, yards, yds
• mi, mile, miles
• league, leagues
• mm, millimeter, millimeters, millimetre, millimetres
• cm, centimeter, centimeters, centimetre, centimetres
• dc, decimeter, decimeters, decimetre, decimetres
• m, meter, meters, metre, metres
• km, kms, kilometer, kilometers, kilometre, kilometres
• nm, nmi, nautical mi, nautical mile, nautical miles

Temperature:

• F, °F, Fahrenheit
• °C, Celsius
• K, kelvin, kelvins

Time:

• ns, nano, nanos, nanosecond, nanoseconds
• us, micro, micros, microsecond, microseconds
• ms, milli, millis, millisecond, milliseconds
• s, sec, secs, second, seconds
• min, mins, minute, minutes
• hr, hrs, hour, hours
• day, days
• wk, wks, week, weeks,
• yr, yrs, year, years
• score
• decade, decades
• biennium, bienniums
• triennium, trienniums
• quadrennium, quadrenniums
• lustrum, lustrums
• decade, decades
• century, centurys, centuries
• millennium, millenniums, millennia, millennias

Volume:

• ts, tsp, tsps, teaspoon, teaspoons
• tbsp, tbsp, tablespoon, tablespoons
• floz, fl-oz, fl oz, fluid ounce, fluid ounces, fl. oz, oz. fl, oz fl
• c, cup, cups
• pt, pint, pints,
• qt, quart, quarts
• gal gals, gallon, gallons
• ml, millilitre, millilitres, milliliter, milliliters
• cl, centilitre, centilitre, centiliter, centiliters
• l, litre, litres, liter, liters
• dl, decalitre, decalitres, decaliter, decaliters
• kl, kilolitre, kiloletres, kiloliter, kiloliters
• mm3, mm^3, mm³, millimeter3, millimeter^3, millimeter³, millimeters3, millimeters^3, millimeters³, cubic mm, cubic millimeter, cubic millimeters
• cm3, cm^3, cm³, centimeter3, centimeter^3, centimeter³, centimeters3, centimeters^3, centimeters³, cubic cm, cubic centimeter, cubic centimeters
• m3, m^3, m³, meter3, meter^3, meter³, meters3, meters^3, meters³, cubic m, cubic meter, cubic meters
• km3, km^3, km³, kilometer3, kilometer^3, kilometer³, kilometers3, kilometers^3, kilometers³, cubic km, cubic kilometer, cubic kilometers
• in3, in^3, in³, inch3, inch^3, inch³, inches3, inches^3, inches³, cubic in, cubic inch, cubic inches
• ft3, ft^3, ft³, foot3, foot^3, foot³, feet3, feet^3, feet³, cubic ft, cubic foot, cubic feet
• yd3, yd^3, yd³, yard3, yard^3, yard³, yards3, yards^3, yards³, cubic yd, cubic yard, cubic yards

Weight:

• mg, milligram, milligrams
• g, gram, grams
• kg, kilo, kilos, kilogram, kilograms
• oz, ounce, ounces
• lb, lbs, pound, pounds
• ton, tons, tonne, tonnes