Currency
open class Currency : MeasureUnit
kotlin.Any | ||
↳ | 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
Note: This class deliberately resembles java.util.Currency but it has a completely independent implementation, and adds features not present in the JDK.
Summary
Nested classes | |
---|---|
Currency Usage used for Decimal Format |
Constants | |
---|---|
static Int |
Selector for getName() indicating the formal currency symbol. |
static Int |
Selector for getName() indicating the long name for a currency, such as "US Dollar" for USD. |
static Int |
Selector for getName() indicating the narrow currency symbol. |
static Int |
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". |
static Int |
Selector for getName() indicating a symbolic name for a currency, such as "$" for USD. |
static Int |
Selector for getName() indicating the variant currency symbol. |
Protected constructors | |
---|---|
Constructs a currency object for the given ISO 4217 3-letter code. |
Public methods | |
---|---|
open static Currency! |
fromJavaCurrency(currency: Currency!) Returns a Currency object based on the currency represented by the given java. |
open static MutableSet<Currency!>! |
Returns the set of available currencies. |
open static Array<String!>! |
getAvailableCurrencyCodes(loc: ULocale!, d: Date!) Returns an array of Strings which contain the currency identifiers that are valid for the given locale on the given date. |
open static Array<String!>! |
getAvailableCurrencyCodes(loc: Locale!, d: Date!) Returns an array of Strings which contain the currency identifiers that are valid for the given |
open static Array<Locale!>! |
Return an array of the locales for which a currency is defined. |
open static Array<ULocale!>! |
Return an array of the ulocales for which a currency is defined. |
open String! |
Returns the ISO 4217 3-letter code for this currency object. |
open Int |
Returns the number of the number of fraction digits that should be displayed for this currency. |
open Int |
Returns the number of the number of fraction digits that should be displayed for this currency with Usage. |
open String! |
Returns the display name for this currency in the default locale. |
open String! |
getDisplayName(locale: Locale!) Returns the display name for this currency in the given locale. |
open static Currency! |
getInstance(locale: Locale!) Returns a currency object for the default currency in the given locale. |
open static Currency! |
getInstance(locale: ULocale!) Returns a currency object for the default currency in the given locale. |
open static Currency! |
getInstance(theISOCode: String!) Returns a currency object given an ISO 4217 3-letter code. |
static Array<String!>! |
getKeywordValuesForLocale(key: String!, locale: ULocale!, commonlyUsed: Boolean) Given a key and a locale, returns an array of values for the key for which data exists. |
open String! |
getName(locale: Locale!, nameStyle: Int, isChoiceFormat: BooleanArray!) Returns the display name for the given currency in the given locale. |
open String! |
getName(locale: ULocale!, nameStyle: Int, isChoiceFormat: BooleanArray!) Returns the display name for the given currency in the given locale. |
open String! |
getName(locale: Locale!, nameStyle: Int, pluralCount: String!, isChoiceFormat: BooleanArray!) Returns the display name for the given currency in the given locale. |
open String! |
getName(locale: ULocale!, nameStyle: Int, pluralCount: String!, isChoiceFormat: BooleanArray!) Returns the display name for the given currency in the given locale. |
open Int |
Returns the ISO 4217 numeric code for this currency object. |
open Double |
Returns the rounding increment for this currency, or 0. |
open Double |
Returns the rounding increment for this currency, or 0. |
open String! |
Convenience and compatibility override of getName that requests the symbol name for the default |
open String! |
Convenience and compatibility override of getName that requests the symbol name. |
open String! |
Convenience and compatibility override of getName that requests the symbol name. |
open static Boolean |
isAvailable(code: String!, from: Date!, to: Date!) Queries if the given ISO 4217 3-letter code is available on the specified date range. |
open Currency! |
Returns a java. |
open String |
toString() Returns the ISO 4217 code for this currency. |
Inherited functions | |
---|---|
Inherited properties | |
---|---|
Constants
FORMAL_SYMBOL_NAME
static val FORMAL_SYMBOL_NAME: Int
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.
Value: 4
LONG_NAME
static val LONG_NAME: Int
Selector for getName() indicating the long name for a currency, such as "US Dollar" for USD.
Value: 1
NARROW_SYMBOL_NAME
static val NARROW_SYMBOL_NAME: Int
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.
Value: 3
PLURAL_LONG_NAME
static val PLURAL_LONG_NAME: Int
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".
Value: 2
SYMBOL_NAME
static val SYMBOL_NAME: Int
Selector for getName() indicating a symbolic name for a currency, such as "$" for USD.
Value: 0
VARIANT_SYMBOL_NAME
static val VARIANT_SYMBOL_NAME: Int
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.
Value: 5
Protected constructors
Currency
protected Currency(theISOCode: String!)
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
open static fun fromJavaCurrency(currency: 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. |
Return | |
---|---|
Currency! |
An equivalent ICU currency object. |
getAvailableCurrencies
open static fun getAvailableCurrencies(): MutableSet<Currency!>!
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.
Return | |
---|---|
MutableSet<Currency!>! |
The set of available currencies. The returned set could be empty if there is no currency data available. |
getAvailableCurrencyCodes
open static fun getAvailableCurrencyCodes(
loc: ULocale!,
d: Date!
): Array<String!>!
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. |
Return | |
---|---|
Array<String!>! |
The array of ISO currency codes. |
getAvailableCurrencyCodes
open static fun getAvailableCurrencyCodes(
loc: Locale!,
d: Date!
): Array<String!>!
Returns an array of Strings which contain the currency identifiers that are valid for the given java.util.Locale
on the given date. If there are no such identifiers, returns null. Returned identifiers are in preference order.
Parameters | |
---|---|
loc |
Locale!: the java.util.Locale for which to retrieve currency codes. |
d |
Date!: the date for which to retrieve currency codes for the given locale. |
Return | |
---|---|
Array<String!>! |
The array of ISO currency codes. |
getAvailableLocales
open static fun getAvailableLocales(): Array<Locale!>!
Return an array of the locales for which a currency is defined.
Return | |
---|---|
Array<Locale!>! |
an array of the available locales |
getAvailableULocales
open static fun getAvailableULocales(): Array<ULocale!>!
Return an array of the ulocales for which a currency is defined.
Return | |
---|---|
Array<ULocale!>! |
an array of the available ulocales |
getCurrencyCode
open fun getCurrencyCode(): String!
Returns the ISO 4217 3-letter code for this currency object.
getDefaultFractionDigits
open fun getDefaultFractionDigits(): Int
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.
Return | |
---|---|
Int |
a non-negative number of fraction digits to be displayed |
getDefaultFractionDigits
open fun getDefaultFractionDigits(Usage: Currency.CurrencyUsage!): Int
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) |
Return | |
---|---|
Int |
a non-negative number of fraction digits to be displayed |
getDisplayName
open fun getDisplayName(): String!
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 java.util.Currency#getDisplayName()
and is equivalent to getName(Locale.getDefault(), LONG_NAME, null)
.
Return | |
---|---|
String! |
The display name of this currency |
getDisplayName
open fun getDisplayName(locale: Locale!): String!
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 java.util.Currency#getDisplayName(java.util.Locale)
and is equivalent to getName(locale, LONG_NAME, null)
.
Parameters | |
---|---|
locale |
Locale!: locale in which to display currency |
Return | |
---|---|
String! |
The display name of this currency for the specified locale |
getInstance
open static fun getInstance(locale: Locale!): Currency!
Returns a currency object for the default currency in the given locale.
Parameters | |
---|---|
locale |
Locale!: the locale |
Return | |
---|---|
Currency! |
the currency object for this locale |
getInstance
open static fun getInstance(locale: ULocale!): Currency!
Returns a currency object for the default currency in the given locale.
getInstance
open static fun getInstance(theISOCode: String!): Currency!
Returns a currency object given an ISO 4217 3-letter code.
Parameters | |
---|---|
theISOCode |
String!: the iso code |
Return | |
---|---|
Currency! |
the currency for this iso code |
Exceptions | |
---|---|
java.lang.NullPointerException |
if theISOCode is null. |
java.lang.IllegalArgumentException |
if theISOCode is not a 3-letter alpha code. |
getKeywordValuesForLocale
static fun getKeywordValuesForLocale(
key: String!,
locale: ULocale!,
commonlyUsed: Boolean
): Array<String!>!
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. |
Return | |
---|---|
Array<String!>! |
an array of values for the given key and the locale. If there is no data, the array will be empty. |
getName
open fun getName(
locale: Locale!,
nameStyle: Int,
isChoiceFormat: BooleanArray!
): String!
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 |
BooleanArray!: 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 |
Return | |
---|---|
String! |
display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned. |
getName
open fun getName(
locale: ULocale!,
nameStyle: Int,
isChoiceFormat: BooleanArray!
): String!
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 |
BooleanArray!: 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 |
Return | |
---|---|
String! |
display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the nameStyle is not SYMBOL_NAME or LONG_NAME. |
getName
open fun getName(
locale: Locale!,
nameStyle: Int,
pluralCount: String!,
isChoiceFormat: BooleanArray!
): String!
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 |
BooleanArray!: 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 |
Return | |
---|---|
String! |
display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned. |
getName
open fun getName(
locale: ULocale!,
nameStyle: Int,
pluralCount: String!,
isChoiceFormat: BooleanArray!
): String!
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 |
BooleanArray!: 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 |
Return | |
---|---|
String! |
display string for this currency. If the resource data contains no entry for this currency, then the ISO 4217 code is returned. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the nameStyle is not SYMBOL_NAME, LONG_NAME, or PLURAL_LONG_NAME. |
getNumericCode
open fun getNumericCode(): Int
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.
Return | |
---|---|
Int |
The ISO 4217 numeric code of this currency. |
getRoundingIncrement
open fun getRoundingIncrement(): Double
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);
Return | |
---|---|
Double |
the non-negative rounding increment, or 0.0 if none |
getRoundingIncrement
open fun getRoundingIncrement(Usage: Currency.CurrencyUsage!): Double
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) |
Return | |
---|---|
Double |
the non-negative rounding increment, or 0.0 if none |
getSymbol
open fun getSymbol(): String!
Convenience and compatibility override of getName that requests the symbol name for the default DISPLAY
locale.
getSymbol
open fun getSymbol(loc: Locale!): String!
Convenience and compatibility override of getName that requests the symbol name.
Parameters | |
---|---|
loc |
Locale!: the Locale for the symbol |
See Also
getSymbol
open fun getSymbol(uloc: ULocale!): String!
Convenience and compatibility override of getName that requests the symbol name.
Parameters | |
---|---|
uloc |
ULocale!: the ULocale for the symbol |
See Also
isAvailable
open static fun isAvailable(
code: String!,
from: Date!,
to: Date!
): Boolean
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 |
Return | |
---|---|
Boolean |
true if the given ISO 4217 3-letter code is supported on the specified date range. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
when to is before from . |
toJavaCurrency
open fun toJavaCurrency(): Currency!
Returns a java.util.Currency object based on the currency represented by this Currency.
Return | |
---|---|
Currency! |
An equivalent Java currency object. |
toString
open fun toString(): String
Returns the ISO 4217 code for this currency.
Return | |
---|---|
String |
a string representation of the object. |