Class ilib.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.
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.
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
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.

Depends directive: !depends unitfmt.js
Defined in: ilib-dyn-full.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	ilib.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

ilib.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:
{ilib.Measurement} measurement: measurement to format

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

{ilib.Locale} getLocale()

Return the locale used with this formatter instance.

Returns:: {ilib.Locale} the ilib.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 ilib.UnitFmt