Namespace: Unitz

Classes

Class

Conversion

Fraction

Group

Parsed

Members

staticUnitz.classesArray.<Unitz.Class>

An array of all unit classes.

See:

• Unitz.addClass

staticUnitz.classMapObject

A map of all unit classes where the key is their Unitz.Class#className.

See:

• Unitz.addClass

staticUnitz.unitToClassObject

A map of all units (lowercased) to their Unitz.Class

See:

• Unitz.addClass

Methods

staticUnitz.addClass(unitClass)

Unitz.js, line 892

Adds a new Unitz.Class to Unitz registering all converters in the class to be available for parsing.

Name	Type	Description
unitClass	Unitz.Class	The unit class to add.

staticUnitz.best(input, returnFraction, abbreviations, largestDenominator){Unitz.Parsed}

Unitz.js, line 428

Determines the best way to represent the parsable input, optionally using fractions. This will look at all units available in the parsed class and use the conversion which results in the closest representation with the shortest string representation favoring larger units. A Unitz.Parsed instance is returned with the Unitz.Parsed#normal property set to the best representation.

Unitz.best('2 pints'); // '1 quart'
Unitz.best('2640 ft'); // '0.5 miles'
Unitz.best('2640 ft', true); // '1/2 mile'

Name	Type	Default	Description
input	parsable		The input to return the best representation of.
returnFraction	Boolean	false	optional If the best representation should attempted to be a fraction.
abbreviations	Boolean	false	optional If the returned value should use abbreviations if they're available.
largestDenominator	Number		optional See Unitz.Fraction.

Returns:

The parsed instance with the Unitz.Parsed#normal property set to the best representation.

staticUnitz.combine(inputA, inputB, fraction, abbreviations, largestDenominator){String}

Unitz.js, line 616

Adds the two expressions together into a single string. Each expression can be a comma delimited string of value & unit pairs - this function will take the parsed values with the same classes and add them together. The string returned has expressions passed through the Unitz.best function optionally using fractions.

Unitz.combine( 2, '3 tacos' ); // '5 tacos'
Unitz.combine( '2 cups', '1 pt' ); // '1 quart'
Unitz.combine( '3 cups, 1 bag', '2 bags, 12 tacos' ); // `3 cups, 3 bags, 12 tacos'

Name	Type	Default	Description
inputA	String | parsable | Array.<parsable>		The first expression or set of expressions to add together.
inputB	String | parsable | Array.<parsable>		The second expression or set of expressions to add together.
fraction	Boolean	false	optional If the returned value should attempt to use fractions.
abbreviations	Boolean	false	optional If the returned value should use abbreviations if they're available.
largestDenominator	Number		optional See Unitz.Fraction.

Returns:

The string representation of inputA + inputB.

staticUnitz.compound(input, unitsAllowed){String}

Unitz.js, line 340

Parses a number and unit out of the given string and returns a human friendly representation of the number and unit class - which is known as a compound representation because it can contain as many units as necessary to accurately describe the value. This is especially useful when you want precise amounts for a fractional value.

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'

Name	Type	Default	Description
input	String		The input to parse a number & unit from.
unitsAllowed	Array.<String>	false	optional The units to be restricted to use. This can be used to avoid using undesirable units in the output. If this is not given, then all units for the parsed input may be used.

Returns:

The compound string built from the input.

staticUnitz.conversions(input, min, max, largestDenominator){Unitz.Parsed}

Unitz.js, line 844

Parses the given input and returns a Unitz.Parsed instance with a new conversions property which is an array of Unitz.Conversions. The array of conversions generated can be limited by minimum and maximum numbers to only return human friendly conversions.

Unitz.conversions('2.25 hrs', 0.1, 1000); // '135 minutes', '2 1/4 hours'

Name	Type	Description
input	parsable	The input to generate conversions for.
min	Number	optional If given, the conversions returned will all have values above min.
max	Number	optional If given, the conversions returned will all have values below max.
largestDenominator	Number	optional See Unitz.Fraction.

Returns:

The instance parsed from the input with a conversions array. If the parsed input is not valid or has a unit class then the input given is returned.

staticUnitz.convert(input, unit){Number}

Unitz.js, line 510

Converts the parsable input to the given unit. If the conversion can't be done then false is returned.

Unitz.convert('30 in', 'ft'); // 2.5
Unitz.convert('1 in', 'cm'); // 2.54
Unitz.convert('2 1/2 gal', 'qt'); // 10

Name	Type	Description
input	parsable	The input to parse and convert to the given unit.
unit	String	The unit to convert to.

Returns:

The converted number.

staticUnitz.createNormal(value, unit){String}

Unitz.js, line 189

Creates a stirng representation of a value and a unit. If the value doesn't have a unit then the value is returned immediately.

Name	Type	Description
value	Number | String	The value to add a unit to.
unit	String	optional The unit to add to the value.

Returns:

The normal representation of a value and its unit.

staticUnitz.findUnit(units, singular){String}

Unitz.js, line 572

Given an array of unknown units - return the singular or plural unit. The singular unit is the shorter string and the plural unit is the longer string.

Name	Type	Description
units	Array.<String>	The array of units to look through.
singular	Boolean	True if the singular unit should be returned, otherwise false if the plural unit should be returned.

Returns:

The singular or plural unit determined.

staticUnitz.isHeuristicMatch(unitA, unitB){Boolean}

Unitz.js, line 172

Determines whether the two units are close enough a match to be considered units of the same group. This is used when units are given by the user which aren't known to Unitz. It determines this by comparing the first Unitz.heuristicLength characters of each unit.

Unitz.isHeuristicMatch('loaves', 'loaf'); // true
Unitz.isHeuristicMatch('taco', 'tacos'); // true
Unitz.isHeuristicMatch('pk', 'pack'); // false

Name	Type	Description
unitA	String	The first unit to test.
unitB	String	The second string to test.

Returns:

True if the two units are a match, otherwise false.

staticUnitz.isSingular(x){Boolean}

Unitz.js, line 133

Determines if the given variable is a number equivalent to one (both positive and negative). This is used to determine when to use the singluar or plural version of a unit.

Name	Type	Description
x	Number	The number to check for oneness.

Returns:

True if the given number is equivalent to +1 or -1.

staticUnitz.isWhole(x){Boolean}

Unitz.js, line 147

Determines if the given variable is a whole number.

Name	Type	Description
x	Number	The number to check for wholeness.

Returns:

True if the given number is a whole number, otherwise false.

staticUnitz.parse(input){Unitz.Parsed}

Unitz.js, line 272

Parses a number and unit out of the given string and returns a parsed instance. If the given input is not in a valid format false is returned.

Unitz.parse('1.5'); // A unitless value.
Unitz.parse('1/2'); // A unitless fraction.
Unitz.parse('2 1/3'); // A unitless fraction with a whole number.
Unitz.parse('unit'); // A unit with a value of 1.
Unitz.parse('0.5 unit'); // A number value with a unit.
Unitz.parse('1/2 unit'); // A fraction with a unit.
Unitz.parse('3 1/4 unit'); // A fraction with a whole number with a unit.
Unitz.parse(''); // false

Name	Type	Description
input	String	The input to parse a number & unit from.

Returns:

The parsed instance.

staticUnitz.parseInput(input){Unitz.Parsed}

Unitz.js, line 233

Parses the input and returns an instance of Unitz.Parsed. If the given input cannot be parsed then false is returned.

Name	Type	Description
input	parsable	The parsable input.

Returns:

The parsed instance.

staticUnitz.removeGroup(unit){Boolean}

Unitz.js, line 110

Removes the group which has the given unit. The group will be removed entirely from the system and can no longer be parsed or converted to and from.

Name	Type	Description
unit	String	The lowercase unit of the group to remove.

Returns:

True if the group was removed, false if it does not exist in this class.

staticUnitz.removeUnit(unit){Boolean}

Unitz.js, line 86

Removes a unit from its class. The group the unit to still exists in the class, but the unit won't be parsed to the group anymore.

Name	Type	Description
unit	String	The lowercase unit to remove from this class.

Returns:

True if the unit was removed, false if it does not exist in this class.

staticUnitz.splitInput(input){Array}

Unitz.js, line 205

Converts input to an array of

Name	Type	Description
input	String | Array | Object	optional The input to convert to an array.

See:

• Unitz.combine
• Unitz.subtract

Returns:

The array of converted inputs.

staticUnitz.subtract(inputA, inputB, allowNegatives, fraction, abbreviations, largestDenominator){String}

Unitz.js, line 730

Subtracts the second expression from the first expression and returns a string representation of the results. Each expression can be a comma delimited string of value & unit pairs - this function will take the parsed values with the same classes and subtract them from each other. The string returned has expressions passed through the Unitz.best function optionally using fractions. By default negative quantities are not included in the result but can overriden with allowNegatives.

Unitz.subtract( '3 tacos', '1 taco' ); // '2 tacos'
Unitz.subtract( 4, 1 ); // '3'
Unitz.subtract( '3 cups, 1 bag', '2 bags, 12 tacos' ); // `3 cups'

Name	Type	Default	Description
inputA	String | parsable | Array.<parsable>		The expression to subtract from.
inputB	String | parsable | Array.<parsable>		The expression to subtract from inputA.
allowNegatives	Boolean	false	optional Whether or not negative values should be included in the results.
fraction	Boolean	false	optional If the returned value should attempt to use fractions.
abbreviations	Boolean	false	optional If the returned value should use abbreviations if they're available.
largestDenominator	Number		optional See Unitz.Fraction.

Returns:

The string representation of inputA - inputB.