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 {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.