Class UnitFmt

Create a new unit formatter instance. The unit formatter is immutable once it is created, but can format as many different strings with different values as needed with the same options. Create different unit formatter instances for different purposes and then keep them cached for use later if you have more than one unit string to format.

The options may contain any of the following properties:

locale - locale to use when formatting the units. The locale also controls the translation of the names of the units. If the locale is not specified, then the default locale of the app or web page will be used.
autoScale - when true, automatically scale the amount to get the smallest number greater than 1, where possible, possibly by converting units within the locale's measurement system. For example, if the current locale is "en-US", and we have a measurement containing 278 fluid ounces, then the number "278" can be scaled down by converting the units to a larger one such as gallons. The scaled size would be 2.17188 gallons. Since iLib does not have a US customary measure larger than gallons, it cannot scale it down any further. If the amount is less than the smallest measure already, it cannot be scaled down any further and no autoscaling will be applied. Default for the autoScale property is "true", so it only needs to be specified when you want to turn off autoscaling.
autoConvert - automatically convert the units to the nearest appropriate measure of the same type in the measurement system used by the locale. For example, if a measurement of length is given in meters, but the current locale is "en-US" which uses the US Customary system, then the nearest appropriate measure would be "yards", and the amount would be converted from meters to yards automatically before being formatted. Default for the autoConvert property is "true", so it only needs to be specified when you want to turn off autoconversion.
usage - describe the reason for the measure. For example, the usage of a formatter may be for a "person height", which implies that certain customary units should be used, even though other measures in the same system may be more efficient. In US Customary measures, a person's height is traditionally given in feet and inches, even though yards, feet and inches would be more efficient and logical.
Specifying a usage implies that the autoScale is turned on so that the measure can be scaled to the level required for the customary measures for the usage. Setting the usage can also implicitly set the style, the max- and minFractionDigits, roundingMode, length, etc. if those options are not explicitly given in this options object. If they are given, the explicit settings override the defaults of the usage.
Usages imply that the formatter should be used with a specific type of measurement. If the format method is called on a measurement that is of the wrong type for the usage, it will be formatted as a regular measurement with default options.
List of usages currently supported:
- general no specific usage with no preselected measures. (Default which does not restrict the units used for any type of measurement.)
- floorSpace area of the floor of a house or building
- landArea area of a piece of plot of land
- networkingSpeed speed of transfer of data over a network
- audioSpeed speed of transfer of audio data
- interfaceSpeed speed of transfer of data over a computer interface such as a USB or SATA bus
- foodEnergy amount of energy contains in food
- electricalEnergy amount of energy in electricity
- heatingEnergy amount of energy required to heat things such as water or home interiors
- babyHeight length of a baby
- personHeight height of an adult or child (not a baby)
- vehicleDistance distance traveled by a vehicle or aircraft (except a boat)
- nauticalDistance distance traveled by a boat
- personWeight weight/mass of an adult human or larger child
- babyWeight weight/mass of a baby or of small animals such as cats and dogs
- vehicleWeight weight/mass of a vehicle (including a boat)
- drugWeight weight/mass of a medicinal drug
- vehicleSpeed speed of travel of a vehicle or aircraft (except a boat)
- nauticalSpeed speed of travel of a boat
- dryFoodVolume volume of a dry food substance in a recipe such as flour
- liquidFoodVolume volume of a liquid food substance in a recipe such as milk
- drinkVolume volume of a drink
- fuelVolume volume of a vehicular fuel
- engineVolume volume of an engine's combustion space
- storageVolume volume of a mass storage tank
- gasVolume volume of a gas such as natural gas used in a home
style - give the style of this formatter. This is used to decide how to format the number and units when the number is not whole, or becomes not whole after auto conversion and scaling. There are two basic styles supported so far:
- numeric - only the largest unit is used and the number is given as decimals. Example: "5.25 lbs"
- list - display the measure with a list of successively smaller-sized units. Example: "5 lbs 4 oz"
The style is most useful for units which are not powers of 10 greater than the smaller units as in the metric system, though it can be useful for metric measures as well. Example: "2kg 381g".
The style may be set implicitly when you set the usage. For example, if the usage is "personWeight", the style will be "numeric" and the maxFractionDigits will be 0. That is, weight of adults and children are most often given in whole pounds. (eg. "172 lbs"). If the usage is "babyWeight", the style will be "list", and the measures will be pounds and ounces. (eg. "7 lbs 2 oz").
length - the length of the units text. This can be either "short" or "long" with the default being "long". Example: a short units text might be "kph" and the corresponding long units text would be "kilometers per hour". Typically, it is the long units text that is translated per locale, though the short one may be as well. Plurals are taken care of properly per locale as well.
maxFractionDigits - the maximum number of digits that should appear in the formatted output after the decimal. A value of -1 means unlimited, and 0 means only print the integral part of the number.
minFractionDigits - the minimum number of fractional digits that should appear in the formatted output. If the number does not have enough fractional digits to reach this minimum, the number will be zero-padded at the end to get to the limit.
significantDigits - the number of significant digits that should appear in the formatted output. If the given number is less than 1, this option will be ignored.
roundingMode - When the maxFractionDigits or maxIntegerDigits is specified, this property governs how the least significant digits are rounded to conform to that maximum. The value of this property is a string with one of the following values:
- up - round away from zero
- down - round towards zero. This has the effect of truncating the number
- ceiling - round towards positive infinity
- floor - round towards negative infinity
- halfup - round towards nearest neighbour. If equidistant, round up.
- halfdown - round towards nearest neighbour. If equidistant, round down.
- halfeven - round towards nearest neighbour. If equidistant, round towards the even neighbour
- halfodd - round towards nearest neighbour. If equidistant, round towards the odd neighbour
Default if this is not specified is "halfup".
onLoad - a callback function to call when the date format object is fully loaded. When the onLoad option is given, the UnitFmt object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.

Here is an example of how you might use the unit formatter to format a string with the correct units.

Defined in: UnitFmt.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	UnitFmt(options)

Method Summary
Method Attributes	Method Name and Description
	format(measurement) Format a particular unit instance according to the settings of this formatter object.
	getLocale() Return the locale used with this formatter instance.
	getMeasurementSystem() Return the measurement system that is used for this formatter.
	getScale() Return whether or not this formatter will auto-scale the units while formatting.
	getTemplate() Return the template string that is used to format date/times for this formatter instance.
	toString() Convert this formatter to a string representation by returning the format template.

Class Detail

UnitFmt(options)

Parameters:
{Object} options: options governing the way this date formatter instance works

Method Detail

{string} format(measurement)

Format a particular unit instance according to the settings of this formatter object.

Parameters:
{Measurement} measurement: measurement to format

Returns:: {string} the formatted version of the given date instance

{Locale} getLocale()

Return the locale used with this formatter instance.

Returns:: {Locale} the Locale instance for this formatter

{string} getMeasurementSystem()

Return the measurement system that is used for this formatter.

Returns:: {string} the measurement system used in this formatter

{boolean} getScale()

Return whether or not this formatter will auto-scale the units while formatting.

Returns:: {boolean} true if auto-scaling is turned on

{string} getTemplate()

Return the template string that is used to format date/times for this formatter instance. This will work, even when the template property is not explicitly given in the options to the constructor. Without the template option, the constructor will build the appropriate template according to the options and use that template in the format method.

Returns:: {string} the format template for this formatter

{string} toString()

Convert this formatter to a string representation by returning the format template. This method delegates to getTemplate.

Returns:: {string} the format template

Classes

Class UnitFmt