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.