Currency

public class Currency
extends MeasureUnit

java.lang.Object
   ↳ android.icu.util.MeasureUnit
     ↳ android.icu.util.Currency

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
The DecimalFormat class uses these data to display currencies.

Note: This class deliberately resembles java.util.Currency but it has a completely independent implementation, and adds features not present in the JDK.

Summary

Constants

int FORMAL_SYMBOL_NAME

Selector for getName() indicating the formal currency symbol.

int LONG_NAME

Selector for getName() indicating the long name for a currency, such as "US Dollar" for USD.

int NARROW_SYMBOL_NAME

Selector for getName() indicating the narrow currency symbol.

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.

int VARIANT_SYMBOL_NAME

Selector for getName() indicating the variant currency symbol.

Inherited fields

Protected constructors

Currency(String theISOCode)

Constructs a currency object for the given ISO 4217 3-letter code.

Public methods

static Currency fromJavaCurrency(Currency currency)

Returns a Currency object based on the currency represented by the given java.util.Currency.

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 getDisplayName(Locale locale)

Returns the display name for this currency in the given locale.

static Currency getInstance(String theISOCode)

Returns a currency object given an ISO 4217 3-letter code.

static Currency getInstance(Locale locale)

Returns a currency object for the default currency in the given locale.

static Currency getInstance(ULocale locale)

Returns a currency object for the default currency in the given locale.

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.

String getName(Locale locale, int nameStyle, String pluralCount, boolean[] isChoiceFormat)

Returns the display name for the given currency in the given locale.

String getName(Locale locale, int nameStyle, boolean[] isChoiceFormat)

Returns the display name for the given currency in the given locale.

String getName(ULocale locale, int nameStyle, boolean[] isChoiceFormat)

Returns the display name for the given currency in the given locale.

String getName(ULocale locale, int nameStyle, String pluralCount, boolean[] isChoiceFormat)

Returns the display name for the given currency in the given locale.

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 getSymbol(Locale loc)

Convenience and compatibility override of getName that requests the symbol name.

String getSymbol(ULocale uloc)

Convenience and compatibility override of getName that requests the symbol name.

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.

Currency toJavaCurrency()

Returns a java.util.Currency object based on the currency represented by this Currency.

String toString()

Returns the ISO 4217 code for this currency.

Inherited methods

Constants

FORMAL_SYMBOL_NAME

Added in API level 33 
public static final int FORMAL_SYMBOL_NAME

Selector for getName() indicating the formal currency symbol.

The formal currency symbol is similar to the regular currency symbol, but it always takes the form used in formal settings such as banking; for example, "NT$" instead of "$" for TWD in zh-TW.

Constant Value: 4 (0x00000004)

LONG_NAME

Added in API level 24 
public static final int LONG_NAME

Selector for getName() indicating the long name for a currency, such as "US Dollar" for USD.

Constant Value: 1 (0x00000001)

NARROW_SYMBOL_NAME

Added in API level 30 
public static final int NARROW_SYMBOL_NAME

Selector for getName() indicating the narrow currency symbol.

The narrow currency symbol is similar to the regular currency symbol, but it always takes the shortest form; for example, "$" instead of "US$" for USD in en-CA.

Constant Value: 3 (0x00000003)

PLURAL_LONG_NAME

Added in API level 24 
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".

Constant Value: 2 (0x00000002)

SYMBOL_NAME

Added in API level 24 
public static final int SYMBOL_NAME

Selector for getName() indicating a symbolic name for a currency, such as "$" for USD.

Constant Value: 0 (0x00000000)

VARIANT_SYMBOL_NAME

Added in API level 33 
public static final int VARIANT_SYMBOL_NAME

Selector for getName() indicating the variant currency symbol.

The variant symbol for a currency is an alternative symbol that is not necessarily as widely used as the regular symbol.

Constant Value: 5 (0x00000005)

Protected constructors

Currency

Added in API level 24 
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 String: The iso code used to construct the currency.

Public methods

fromJavaCurrency

Added in API level 29 
public static Currency fromJavaCurrency (Currency currency)

Returns a Currency object based on the currency represented by the given java.util.Currency.

Parameters
currency Currency: The Java currency object to convert.
Returns
Currency An equivalent ICU currency object.

getAvailableCurrencies

Added in API level 24 
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
Set<Currency> The set of available currencies. The returned set could be empty if there is no currency data available.

getAvailableCurrencyCodes

Added in API level 24 
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 ULocale: the locale for which to retrieve currency codes.
d Date: the date for which to retrieve currency codes for the given locale.
Returns
String[] The array of ISO currency codes.

getAvailableCurrencyCodes

Added in API level 24 
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 Locale: the Locale for which to retrieve currency codes.
d Date: the date for which to retrieve currency codes for the given locale.
Returns
String[] The array of ISO currency codes.

getAvailableLocales

Added in API level 24 
public static Locale[] getAvailableLocales ()

Return an array of the locales for which a currency is defined.

Returns
Locale[] an array of the available locales

getAvailableULocales

Added in API level 24 
public static ULocale[] getAvailableULocales ()

Return an array of the ulocales for which a currency is defined.

Returns
ULocale[] an array of the available ulocales

getCurrencyCode

Added in API level 24 
public String getCurrencyCode ()

Returns the ISO 4217 3-letter code for this currency object.

Returns
String

getDefaultFractionDigits

Added in API level 24 
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); Important: The number of fraction digits for a given currency is NOT guaranteed to be constant across versions of ICU or CLDR. For example, do NOT use this value as a mechanism for deciding the magnitude used to store currency values in a database. You should use this value for display purposes only.

Returns
int a non-negative number of fraction digits to be displayed

getDefaultFractionDigits

Added in API level 24 
public int getDefaultFractionDigits (Currency.CurrencyUsage Usage)

Returns the number of the number of fraction digits that should be displayed for this currency with Usage. Important: The number of fraction digits for a given currency is NOT guaranteed to be constant across versions of ICU or CLDR. For example, do NOT use this value as a mechanism for deciding the magnitude used to store currency values in a database. You should use this value for display purposes only.

Parameters
Usage Currency.CurrencyUsage: the usage of currency(Standard or Cash)
Returns
int a non-negative number of fraction digits to be displayed

getDisplayName

Added in API level 24 
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 Currency.getDisplayName() and is equivalent to getName(Locale.getDefault(), LONG_NAME, null).

Returns
String The display name of this currency

getDisplayName

Added in API level 24 
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 Currency.getDisplayName(java.util.Locale) and is equivalent to getName(locale, LONG_NAME, null).

Parameters
locale Locale: locale in which to display currency
Returns
String The display name of this currency for the specified locale

getInstance

Added in API level 24 
public static Currency getInstance (String theISOCode)

Returns a currency object given an ISO 4217 3-letter code.

Parameters
theISOCode String: the iso code
Returns
Currency the currency for this iso code
Throws
NullPointerException if theISOCode is null.
IllegalArgumentException if theISOCode is not a 3-letter alpha code.

getInstance

Added in API level 24 
public static Currency getInstance (Locale locale)

Returns a currency object for the default currency in the given locale.

Parameters
locale Locale: the locale
Returns
Currency the currency object for this locale

getInstance

Added in API level 24 
public static Currency getInstance (ULocale locale)

Returns a currency object for the default currency in the given locale.

Parameters
locale ULocale

Returns
Currency

getKeywordValuesForLocale

Added in API level 24 
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, ULocale.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 String: key whose values to look up. the only recognized key is "currency"
locale ULocale: the locale
commonlyUsed boolean: if true, return only values that are currently used in the locale. Otherwise returns all values.
Returns
String[] an array of values for the given key and the locale. If there is no data, the array will be empty.

getName

Added in API level 24 
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 Locale: locale in which to display currency
nameStyle int: selector for which kind of name to return
pluralCount String: plural count string for this locale
isChoiceFormat boolean: isChoiceFormat[0] is always set to false, or isChoiceFormat can be null; display names are static strings; since ICU 4.4, ChoiceFormat patterns are no longer supported
Returns
String display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned.

getName

Added in API level 24 
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 Locale: locale in which to display currency
nameStyle int: selector for which kind of name to return. The nameStyle should be SYMBOL_NAME, NARROW_SYMBOL_NAME, or LONG_NAME. Otherwise, throw IllegalArgumentException.
isChoiceFormat boolean: isChoiceFormat[0] is always set to false, or isChoiceFormat can be null; display names are static strings; since ICU 4.4, ChoiceFormat patterns are no longer supported
Returns
String display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned.

getName

Added in API level 24 
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 ULocale: locale in which to display currency
nameStyle int: selector for which kind of name to return. The nameStyle should be SYMBOL_NAME, NARROW_SYMBOL_NAME, or LONG_NAME. Otherwise, throw IllegalArgumentException.
isChoiceFormat boolean: isChoiceFormat[0] is always set to false, or isChoiceFormat can be null; display names are static strings; since ICU 4.4, ChoiceFormat patterns are no longer supported
Returns
String display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned.

Throws
IllegalArgumentException if the nameStyle is not SYMBOL_NAME or LONG_NAME.

getName

Added in API level 24 
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 ULocale: locale in which to display currency
nameStyle int: selector for which kind of name to return
pluralCount String: plural count string for this locale
isChoiceFormat boolean: isChoiceFormat[0] is always set to false, or isChoiceFormat can be null; display names are static strings; since ICU 4.4, ChoiceFormat patterns are no longer supported
Returns
String display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned.
Throws
IllegalArgumentException if the nameStyle is not SYMBOL_NAME, LONG_NAME, or PLURAL_LONG_NAME.

getNumericCode

Added in API level 24 
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
int The ISO 4217 numeric code of this currency.

getRoundingIncrement

Added in API level 24 
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
double the non-negative rounding increment, or 0.0 if none

getRoundingIncrement

Added in API level 24 
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 Currency.CurrencyUsage: the usage of currency(Standard or Cash)
Returns
double the non-negative rounding increment, or 0.0 if none

getSymbol

Added in API level 24 
public String getSymbol ()

Convenience and compatibility override of getName that requests the symbol name for the default DISPLAY locale.

Returns
String

getSymbol

Added in API level 24 
public String getSymbol (Locale loc)

Convenience and compatibility override of getName that requests the symbol name.

Parameters
loc Locale: the Locale for the symbol
Returns
String

getSymbol

Added in API level 24 
public String getSymbol (ULocale uloc)

Convenience and compatibility override of getName that requests the symbol name.

Parameters
uloc ULocale: the ULocale for the symbol
Returns
String

isAvailable

Added in API level 24 
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 String: The ISO 4217 3-letter code.
from Date: The lower bound of the date range, inclusive. When from is null, check the availability of the currency any date before to
to Date: The upper bound of the date range, inclusive. When to is null, check the availability of the currency any date after from
Returns
boolean true if the given ISO 4217 3-letter code is supported on the specified date range.
Throws
IllegalArgumentException when to is before from.

toJavaCurrency

Added in API level 29 
public Currency toJavaCurrency ()

Returns a java.util.Currency object based on the currency represented by this Currency.

Returns
Currency An equivalent Java currency object.

toString

Added in API level 24 
public String toString ()

Returns the ISO 4217 code for this currency.

Returns
String a string representation of the object.