Class ilib.Currency

Create a new currency information instance. Instances of this class encode information about a particular currency.

Note: that if you are looking to format currency for display, please see the number formatting class {ilib.NumFmt}. This class only gives information about currencies.

The options can contain any of the following properties:

locale - specify the locale for this instance
code - find info on a specific currency with the given ISO 4217 code
sign - search for a currency that uses this sign
onLoad - a callback function to call when the currency 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.

When searching for a currency by its sign, this class cannot guarantee that it will return info about a specific currency. The reason is that currency signs are sometimes shared between different currencies and the sign is therefore ambiguous. If you need a guarantee, find the currency using the code instead.

The way this class finds a currency by sign is the following. If the sign is unambiguous, then the currency is returned. If there are multiple currencies that use the same sign, and the current locale uses that sign, then the default currency for the current locale is returned. If there are multiple, but the current locale does not use that sign, then the currency with the largest circulation is returned. For example, if you are in the en-GB locale, and the sign is "$", then this class will notice that there are multiple currencies with that sign (USD, CAD, AUD, HKD, MXP, etc.) Since "$" is not used in en-GB, it will pick the one with the largest circulation, which in this case is the US Dollar (USD).

If neither the code or sign property is set, the currency that is most common for the locale will be used instead. If the locale is not set, the default locale will be used. If the code is given, but it is not found in the list of known currencies, this constructor will throw an exception. If the sign is given, but it is not found, this constructor will default to the currency for the current locale. If both the code and sign properties are given, then the sign property will be ignored and only the code property used. If the locale is given, but it is not a known locale, this class will default to the default locale instead.

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

Class Summary
Constructor Attributes	Constructor Name and Description
	ilib.Currency(options)

Method Summary
Method Attributes	Method Name and Description
<static>	ilib.Currency.getAvailableCurrencies() Return an array of the ids for all ISO 4217 currencies that this copy of ilib knows about.
	getCode() Return the ISO 4217 currency code for this instance.
	getFractionDigits() Return the default number of fraction digits that is typically used with this type of currency.
	getLocale() Return the locale for this currency.
	getName() Return the name of the currency in English.
	getSign() Return the sign commonly used to represent this currency.

Class Detail

ilib.Currency(options)

Parameters:
options: {Object} a set of properties to govern how this instance is constructed.

Throws:
: "currency xxx is unknown" when the given currency code is not in the list of known currencies. xxx is replaced with the requested code.

Method Detail

<static> {Array.<string>} ilib.Currency.getAvailableCurrencies()

Return an array of the ids for all ISO 4217 currencies that this copy of ilib knows about.

Returns:: {Array.<string>} an array of currency ids that this copy of ilib knows about.

{string} getCode()

Return the ISO 4217 currency code for this instance.

Returns:: {string} the ISO 4217 currency code for this instance

{number} getFractionDigits()

Return the default number of fraction digits that is typically used with this type of currency.

Returns:: {number} the number of fraction digits for this currency

{ilib.Locale} getLocale()

Return the locale for this currency. If the options to the constructor included a locale property in order to find the currency that is appropriate for that locale, then the locale is returned here. If the options did not include a locale, then this method returns undefined.

Returns:: {ilib.Locale} the locale used in the constructor of this instance, or undefined if no locale was given in the constructor

{string} getName()

Return the name of the currency in English.

Returns:: {string} the name of the currency in English

{string} getSign()

Return the sign commonly used to represent this currency.

Returns:: {string} the sign commonly used to represent this currency

Classes

Class ilib.Currency