Class ilib.NumFmt

Create a new number formatter instance. Locales differ in the way that digits in a formatted number are grouped, in the way the decimal character is represented, etc. Use this formatter to get it right for any locale.

This formatter can format plain numbers, currency amounts, and percentage amounts.

As with all formatters, the recommended practice is to create one formatter and use it multiple times to format various numbers.

The options can contain any of the following properties:

locale - use the conventions of the specified locale when figuring out how to format a number.
type - the type of this formatter. Valid values are "number", "currency", or "percentage". If this property is not specified, the default is "number".
currency - the ISO 4217 3-letter currency code to use when the formatter type is "currency". This property is required for currency formatting. If the type property is "currency" and the currency property is not specified, the constructor will throw a an exception.
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. If the type of the formatter is "currency" and this property is not specified, then the minimum fraction digits is set to the normal number of digits used with that currency, which is almost always 0, 2, or 3 digits.
useNative - the flag used to determaine whether to use the native script settings for formatting the numbers .
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
When the type of the formatter is "currency" and the roundingMode property is not set, then the standard legal rounding rules for the locale are followed. If the type is "number" or "percentage" and the roundingMode property is not set, then the default mode is "halfdown"..
style - When the type of this formatter is "currency", the currency amount can be formatted in the following styles: "common" and "iso". The common style is the one commonly used in every day writing where the currency unit is represented using a symbol. eg. "$57.35" for fifty-seven dollars and thirty five cents. The iso style is the international style where the currency unit is represented using the ISO 4217 code. eg. "USD 57.35" for the same amount. The default is "common" style if the style is not specified.
When the type of this formatter is "number", the style can be one of the following:
- standard - format a fully specified floating point number properly for the locale
- scientific - use scientific notation for all numbers. That is, 1 integral digit, followed by a number of fractional digits, followed by an "e" which denotes exponentiation, followed digits which give the power of 10 in the exponent.
- native - format a floating point number using the native digits and formatting symbols for the script of the locale.
- nogrouping - format a floating point number without grouping digits for the integral portion of the number
Note that if you specify a maximum number of integral digits, the formatter with a standard style will give you standard formatting for smaller numbers and scientific notation for larger numbers. The default is standard style if this is not specified.
onLoad - a callback function to call when the format data is fully loaded. When the onLoad option is given, this class 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.

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

Class Summary

Constructor Attributes Constructor Name and Description

ilib.NumFmt(options)

Method Summary

Method Attributes Method Name and Description

format(num)

Format a number according to the settings of this number formatter instance.

<static>
ilib.NumFmt.getAvailableLocales()

Return an array of available locales that this formatter can format

getCurrency()

Returns the ISO 4217 code for the currency that this formatter formats.

getLocale()

Return the locale for this formatter instance.

getMaxFractionDigits()

Returns the maximum fraction digits set up in the constructor.

getMinFractionDigits()

Returns the minimum fraction digits set up in the constructor.

getRoundingMode()

Returns the rounding mode set up in the constructor.

getStyle()

If this formatter is a currency formatter, then the style determines how the currency is denoted in the formatted output.

getType()

Return the type of formatter.

getUseNative()

Return true if this formatter uses native digits to format the number.

isGroupingUsed()

Returns true if this formatter groups together digits in the integral portion of a number, based on the options set up in the constructor.

Class Detail

ilib.NumFmt(options)

Parameters:

{Object.<string|*>} options

A set of options that govern how the formatter will behave

Method Detail

{string} format(num)

Format a number according to the settings of this number formatter instance.

Parameters:

num

{number|string|Number|ilib.Number} a floating point number to format

Returns:

{string} a string containing the formatted number

<static> {Array.<ilib.Locale>|undefined} ilib.NumFmt.getAvailableLocales()

Return an array of available locales that this formatter can format

Returns:

{Array.<ilib.Locale>|undefined} an array of available locales

{string} getCurrency()

Returns the ISO 4217 code for the currency that this formatter formats. IF the typeof this formatter is not "currency", then this method will return undefined.

Returns:

{string} the ISO 4217 code for the currency that this formatter formats, or undefined if this not a currency formatter

{ilib.Locale} getLocale()

Return the locale for this formatter instance.

Returns:

{ilib.Locale} the locale instance for this formatter

{number} getMaxFractionDigits()

Returns the maximum fraction digits set up in the constructor.

Returns:

{number} the maximum number of fractional digits this formatter will format, or -1 for no maximum

{number} getMinFractionDigits()

Returns the minimum fraction digits set up in the constructor. If the formatter has the type "currency", then the minimum fraction digits is the amount of digits that is standard for the currency in question unless overridden in the options to the constructor.

Returns:

{number} the minimum number of fractional digits this formatter will format, or -1 for no minimum

{string} getRoundingMode()

Returns the rounding mode set up in the constructor. The rounding mode controls how numbers are rounded when the integral or fraction digits of a number are limited.

Returns:

{string} the name of the rounding mode used in this formatter

{string} getStyle()

If this formatter is a currency formatter, then the style determines how the currency is denoted in the formatted output. This method returns the style that this formatter will produce. (See the constructor comment for more about the styles.)

Returns:

{string} the name of the style this formatter will use to format currency amounts, or "undefined" if this formatter is not a currency formatter

{string} getType()

Return the type of formatter. Valid values are "number", "currency", and "percentage".

Returns:

{string} the type of formatter

{boolean} getUseNative()

Return true if this formatter uses native digits to format the number. If the useNative option is given to the constructor, then this flag will be honoured. If the useNative option is not given to the constructor, this this formatter will use native digits if the locale typically uses native digits.

Returns:

{boolean} true if this formatter will format with native digits, false otherwise

{boolean} isGroupingUsed()

Returns true if this formatter groups together digits in the integral portion of a number, based on the options set up in the constructor. In most western European cultures, this means separating every 3 digits of the integral portion of a number with a particular character.

Returns:

{boolean} true if this formatter groups digits in the integral portion of the number

Method Attributes	Method Name and Description
	format(num) Format a number according to the settings of this number formatter instance.
<static>	ilib.NumFmt.getAvailableLocales() Return an array of available locales that this formatter can format
	getCurrency() Returns the ISO 4217 code for the currency that this formatter formats.
	getLocale() Return the locale for this formatter instance.
	getMaxFractionDigits() Returns the maximum fraction digits set up in the constructor.
	getMinFractionDigits() Returns the minimum fraction digits set up in the constructor.
	getRoundingMode() Returns the rounding mode set up in the constructor.
	getStyle() If this formatter is a currency formatter, then the style determines how the currency is denoted in the formatted output.
	getType() Return the type of formatter.
	getUseNative() Return true if this formatter uses native digits to format the number.
	isGroupingUsed() Returns true if this formatter groups together digits in the integral portion of a number, based on the options set up in the constructor.

Classes

Class ilib.NumFmt