java.util

Class Currency

public final class Currency extends Object implements Serializable

Representation of a currency for a particular locale. Each currency is identified by its ISO 4217 code, and only one instance of this class exists per currency. As a result, instances are created via the getInstance() methods rather than by using a constructor.

Since: 1.4

Method Summary
String	getCurrencyCode() Returns the ISO4217 currency code of this currency.
int	getDefaultFractionDigits() Returns the number of digits which occur after the decimal point for this particular currency.
static Currency	getInstance(Locale locale) Builds a new currency instance for this locale.
static Currency	getInstance(String currencyCode) Builds the currency corresponding to the specified currency code.
String	getSymbol() This method returns the symbol which precedes or follows a value in this particular currency in the default locale.
String	getSymbol(Locale locale) This method returns the symbol which precedes or follows a value in this particular currency.
String	toString() Returns the international ISO4217 currency code of this currency.

Method Detail

getCurrencyCode

public String getCurrencyCode()

Returns the ISO4217 currency code of this currency.

Returns: a String containing currency code.

getDefaultFractionDigits

public int getDefaultFractionDigits()

Returns the number of digits which occur after the decimal point for this particular currency. For example, currencies such as the U.S. dollar, the Euro and the Great British pound have two digits following the decimal point to indicate the value which exists in the associated lower-valued coinage (cents in the case of the first two, pennies in the latter). Some currencies such as the Japanese Yen have no digits after the decimal point. In the case of pseudo currencies, such as IMF Special Drawing Rights, -1 is returned.

Returns: the number of digits after the decimal separator for this currency.

getInstance

public static Currency getInstance(Locale locale)

Builds a new currency instance for this locale. All components of the given locale, other than the country code, are ignored. The results of calling this method may vary over time, as the currency associated with a particular country changes. For countries without a given currency (e.g. Antarctica), the result is null.

Parameters: locale a Locale instance.

Returns: a new Currency instance.

Throws: NullPointerException if the locale or its country code is null. IllegalArgumentException if the country of the given locale is not a supported ISO3166 code.

getInstance

public static Currency getInstance(String currencyCode)

Builds the currency corresponding to the specified currency code.

Parameters: currencyCode a string representing a currency code.

Returns: a new Currency instance.

Throws: NullPointerException if currencyCode is null. IllegalArgumentException if the supplied currency code is not a supported ISO 4217 code.

getSymbol

public String getSymbol()

This method returns the symbol which precedes or follows a value in this particular currency in the default locale. In cases where there is no such symbol for the currency, the ISO 4217 currency code is returned.

Returns: the currency symbol, or the ISO 4217 currency code if one doesn't exist.

getSymbol

public String getSymbol(Locale locale)

This method returns the symbol which precedes or follows a value in this particular currency. The returned value is the symbol used to denote the currency in the specified locale.

For example, a supplied locale may specify a different symbol for the currency, due to conflicts with its own currency. This would be the case with the American currency, the dollar. Locales that also use a dollar-based currency (e.g. Canada, Australia) need to differentiate the American dollar using 'US$' rather than '$'. So, supplying one of these locales to getSymbol() would return this value, rather than the standard '$'.

In cases where there is no such symbol for a particular currency, the ISO 4217 currency code is returned.

Parameters: locale the locale to express the symbol in.

Returns: the currency symbol, or the ISO 4217 currency code if one doesn't exist.

Throws: NullPointerException if the locale is null.

toString

public String toString()

Returns the international ISO4217 currency code of this currency.

Returns: a String containing the ISO4217 currency code.