A class encapsulating a currency, as defined by ISO 4217. A Currency object can be created given a Locale or given an ISO 4217 code. Once created, the Currency object can return various data necessary to its proper display:
- A display symbol, for a specific locale
- The number of fraction digits to display
- A rounding increment
Note: This class deliberately resembles java.util.Currency but it has a completely independent implementation, and adds features not present in the JDK.
Nested Class Summary
enum | Currency.CurrencyUsage | Currency Usage used for Decimal Format |
Constant Summary
int | LONG_NAME | Selector for getName() indicating the long name for a currency, such as "US Dollar" for USD. |
int | PLURAL_LONG_NAME | Selector for getName() indicating the plural long name for a currency, such as "US dollar" for USD in "1 US dollar", and "US dollars" for USD in "2 US dollars". |
int | SYMBOL_NAME | Selector for getName() indicating a symbolic name for a currency, such as "$" for USD. |
Inherited Field Summary
Protected Constructor Summary
Public Method Summary
static Set<Currency> |
getAvailableCurrencies()
Returns the set of available currencies.
|
static String[] |
getAvailableCurrencyCodes(ULocale loc, Date d)
Returns an array of Strings which contain the currency
identifiers that are valid for the given locale on the
given date.
|
static String[] |
getAvailableCurrencyCodes(Locale loc, Date d)
Returns an array of Strings which contain the currency
identifiers that are valid for the given
Locale on the
given date. |
static Locale[] |
getAvailableLocales()
Return an array of the locales for which a currency
is defined.
|
static ULocale[] |
getAvailableULocales()
Return an array of the ulocales for which a currency
is defined.
|
String |
getCurrencyCode()
Returns the ISO 4217 3-letter code for this currency object.
|
int |
getDefaultFractionDigits()
Returns the number of the number of fraction digits that should
be displayed for this currency.
|
int |
getDefaultFractionDigits(Currency.CurrencyUsage Usage)
Returns the number of the number of fraction digits that should
be displayed for this currency with Usage.
|
String |
getDisplayName()
Returns the display name for this currency in the default locale.
|
String | |
static Currency | |
static Currency | |
static Currency | |
final static String[] |
getKeywordValuesForLocale(String key, ULocale locale, boolean commonlyUsed)
Given a key and a locale, returns an array of values for the key for which data
exists.
|
String | |
String | |
String | |
String | |
int |
getNumericCode()
Returns the ISO 4217 numeric code for this currency object.
|
double |
getRoundingIncrement()
Returns the rounding increment for this currency, or 0.0 if no
rounding is done by this currency.
|
double |
getRoundingIncrement(Currency.CurrencyUsage Usage)
Returns the rounding increment for this currency, or 0.0 if no
rounding is done by this currency with the Usage.
|
String |
getSymbol()
Convenience and compatibility override of getName that
requests the symbol name for the default
DISPLAY locale. |
String | |
String | |
static boolean |
isAvailable(String code, Date from, Date to)
Queries if the given ISO 4217 3-letter code is available on the specified date range.
|
String |
toString()
Returns the ISO 4217 code for this currency.
|
Inherited Method Summary
Constants
public static final int LONG_NAME
Selector for getName() indicating the long name for a currency, such as "US Dollar" for USD.
public static final int PLURAL_LONG_NAME
Selector for getName() indicating the plural long name for a currency, such as "US dollar" for USD in "1 US dollar", and "US dollars" for USD in "2 US dollars".
public static final int SYMBOL_NAME
Selector for getName() indicating a symbolic name for a currency, such as "$" for USD.
Protected Constructors
protected Currency (String theISOCode)
Constructs a currency object for the given ISO 4217 3-letter code. This constructor assumes that the code is valid.
Parameters
theISOCode | The iso code used to construct the currency. |
---|
Public Methods
public static Set<Currency> getAvailableCurrencies ()
Returns the set of available currencies. The returned set of currencies contains all of the available currencies, including obsolete ones. The result set can be modified without affecting the available currencies in the runtime.
Returns
- The set of available currencies. The returned set could be empty if there is no currency data available.
public static String[] getAvailableCurrencyCodes (ULocale loc, Date d)
Returns an array of Strings which contain the currency identifiers that are valid for the given locale on the given date. If there are no such identifiers, returns null. Returned identifiers are in preference order.
Parameters
loc | the locale for which to retrieve currency codes. |
---|---|
d | the date for which to retrieve currency codes for the given locale. |
Returns
- The array of ISO currency codes.
public static String[] getAvailableCurrencyCodes (Locale loc, Date d)
Returns an array of Strings which contain the currency
identifiers that are valid for the given Locale
on the
given date. If there are no such identifiers, returns null.
Returned identifiers are in preference order.
Parameters
loc | the Locale for which to retrieve currency codes. |
---|---|
d | the date for which to retrieve currency codes for the given locale. |
Returns
- The array of ISO currency codes.
public static Locale[] getAvailableLocales ()
Return an array of the locales for which a currency is defined.
Returns
- an array of the available locales
public static ULocale[] getAvailableULocales ()
Return an array of the ulocales for which a currency is defined.
Returns
- an array of the available ulocales
public int getDefaultFractionDigits ()
Returns the number of the number of fraction digits that should be displayed for this currency. This is equivalent to getDefaultFractionDigits(CurrencyUsage.STANDARD);
Returns
- a non-negative number of fraction digits to be displayed
public int getDefaultFractionDigits (Currency.CurrencyUsage Usage)
Returns the number of the number of fraction digits that should be displayed for this currency with Usage.
Parameters
Usage | the usage of currency(Standard or Cash) |
---|
Returns
- a non-negative number of fraction digits to be displayed
public String getDisplayName ()
Returns the display name for this currency in the default locale. If the resource data for the default locale contains no entry for this currency, then the ISO 4217 code is returned.
Note: This method is a convenience equivalent for
getDisplayName()
and is equivalent to
getName(Locale.getDefault(), LONG_NAME, null)
.
Returns
- The display name of this currency
public String getDisplayName (Locale locale)
Returns the display name for this currency in the given locale. If the resource data for the given locale contains no entry for this currency, then the ISO 4217 code is returned.
Note: This method is a convenience equivalent for
getDisplayName(java.util.Locale)
and is equivalent
to getName(locale, LONG_NAME, null)
.
Parameters
locale | locale in which to display currency |
---|
Returns
- The display name of this currency for the specified locale
public static Currency getInstance (String theISOCode)
Returns a currency object given an ISO 4217 3-letter code.
Parameters
theISOCode | the iso code |
---|
Returns
- the currency for this iso code
Throws
NullPointerException | if theISOCode is null. |
---|---|
IllegalArgumentException | if theISOCode is not a
3-letter alpha code.
|
public static Currency getInstance (Locale locale)
Returns a currency object for the default currency in the given locale.
Parameters
locale | the locale |
---|
Returns
- the currency object for this locale
public static Currency getInstance (ULocale locale)
Returns a currency object for the default currency in the given locale.
Parameters
locale |
---|
public static final String[] getKeywordValuesForLocale (String key, ULocale locale, boolean commonlyUsed)
Given a key and a locale, returns an array of values for the key for which data exists. If commonlyUsed is true, these are the values that typically are used with this locale, otherwise these are all values for which data exists. This is a common service API.
The only supported key is "currency", other values return an empty array.
Currency information is based on the region of the locale. If the locale does not
indicate a region, addLikelySubtags(ULocale)
is used to infer a region,
except for the 'und' locale.
If commonlyUsed is true, only the currencies known to be in use as of the current date are returned. When there are more than one, these are returned in preference order (typically, this occurs when a country is transitioning to a new currency, and the newer currency is preferred), see Unicode TR#35 Sec. C1. If commonlyUsed is false, all currencies ever used in any locale are returned, in no particular order.
Parameters
key | key whose values to look up. the only recognized key is "currency" |
---|---|
locale | the locale |
commonlyUsed | if true, return only values that are currently used in the locale. Otherwise returns all values. |
Returns
- an array of values for the given key and the locale. If there is no data, the array will be empty.
public String getName (Locale locale, int nameStyle, String pluralCount, boolean[] isChoiceFormat)
Returns the display name for the given currency in the given locale. This is a convenience overload of getName(ULocale, int, String, boolean[]);
Parameters
locale | |
---|---|
nameStyle | |
pluralCount | |
isChoiceFormat |
public String getName (Locale locale, int nameStyle, boolean[] isChoiceFormat)
Returns the display name for the given currency in the given locale. This is a convenient method for getName(ULocale, int, boolean[]);
Parameters
locale | |
---|---|
nameStyle | |
isChoiceFormat |
public String getName (ULocale locale, int nameStyle, boolean[] isChoiceFormat)
Returns the display name for the given currency in the given locale. For example, the display name for the USD currency object in the en_US locale is "$".
Parameters
locale | locale in which to display currency |
---|---|
nameStyle | selector for which kind of name to return. The nameStyle should be either SYMBOL_NAME or LONG_NAME. Otherwise, throw IllegalArgumentException. |
isChoiceFormat | fill-in; isChoiceFormat[0] is set to true if the returned value is a ChoiceFormat pattern; otherwise it is set to false |
Returns
- display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned. If isChoiceFormat[0] is true, then the result is a ChoiceFormat pattern. Otherwise it is a static string. Note: as of ICU 4.4, choice formats are not used, and the value returned in isChoiceFormat is always false.
Throws
IllegalArgumentException | if the nameStyle is not SYMBOL_NAME or LONG_NAME. |
---|
public String getName (ULocale locale, int nameStyle, String pluralCount, boolean[] isChoiceFormat)
Returns the display name for the given currency in the given locale. For example, the SYMBOL_NAME for the USD currency object in the en_US locale is "$". The PLURAL_LONG_NAME for the USD currency object when the currency amount is plural is "US dollars", such as in "3.00 US dollars"; while the PLURAL_LONG_NAME for the USD currency object when the currency amount is singular is "US dollar", such as in "1.00 US dollar".
Parameters
locale | locale in which to display currency |
---|---|
nameStyle | selector for which kind of name to return |
pluralCount | plural count string for this locale |
isChoiceFormat | fill-in; isChoiceFormat[0] is set to true if the returned value is a ChoiceFormat pattern; otherwise it is set to false |
Returns
- display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned. If isChoiceFormat[0] is true, then the result is a ChoiceFormat pattern. Otherwise it is a static string. Note: as of ICU 4.4, choice formats are not used, and the value returned in isChoiceFormat is always false.
Throws
IllegalArgumentException | if the nameStyle is not SYMBOL_NAME, LONG_NAME, or PLURAL_LONG_NAME. |
---|
public int getNumericCode ()
Returns the ISO 4217 numeric code for this currency object.
Note: If the ISO 4217 numeric code is not assigned for the currency or the currency is unknown, this method returns 0.
Returns
- The ISO 4217 numeric code of this currency.
public double getRoundingIncrement ()
Returns the rounding increment for this currency, or 0.0 if no rounding is done by this currency. This is equivalent to getRoundingIncrement(CurrencyUsage.STANDARD);
Returns
- the non-negative rounding increment, or 0.0 if none
public double getRoundingIncrement (Currency.CurrencyUsage Usage)
Returns the rounding increment for this currency, or 0.0 if no rounding is done by this currency with the Usage.
Parameters
Usage | the usage of currency(Standard or Cash) |
---|
Returns
- the non-negative rounding increment, or 0.0 if none
public String getSymbol ()
Convenience and compatibility override of getName that
requests the symbol name for the default DISPLAY
locale.
public String getSymbol (Locale loc)
Convenience and compatibility override of getName that requests the symbol name.
Parameters
loc | the Locale for the symbol |
---|
See Also
public String getSymbol (ULocale uloc)
Convenience and compatibility override of getName that requests the symbol name.
Parameters
uloc | the ULocale for the symbol |
---|
See Also
public static boolean isAvailable (String code, Date from, Date to)
Queries if the given ISO 4217 3-letter code is available on the specified date range.
Note: For checking availability of a currency on a specific date, specify the date on both from
and
to
. When both from
and to
are null, this method checks if the specified
currency is available all time.
Parameters
code | The ISO 4217 3-letter code. |
---|---|
from | The lower bound of the date range, inclusive. When from is null, check the availability
of the currency any date before to |
to | The upper bound of the date range, inclusive. When to is null, check the availability of
the currency any date after from |
Returns
- true if the given ISO 4217 3-letter code is supported on the specified date range.
Throws
IllegalArgumentException | when to is before from .
|
---|
public String toString ()
Returns the ISO 4217 code for this currency.
Returns
- a printable representation of this object.