com.ibm.icu.util
Class Currency

java.lang.Object
  extended by com.ibm.icu.util.MeasureUnit
      extended by com.ibm.icu.util.Currency
All Implemented Interfaces:
Serializable

public class Currency
extends MeasureUnit
implements Serializable

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:

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.

Author:
Alan Liu
See Also:
Serialized Form
Status:
Stable ICU 2.2.

Field Summary
static int LONG_NAME
          Selector for ucurr_getName indicating the long name for a currency, such as "US Dollar" for USD.
static int SYMBOL_NAME
          Selector for getName() indicating a symbolic name for a currency, such as "$" for USD.
 
Constructor Summary
protected Currency(String theISOCode)
          Constructs a currency object for the given ISO 4217 3-letter code.
 
Method Summary
 boolean equals(Object rhs)
          Return true if rhs is a Currency instance, is non-null, and has the same currency code.
static String[] getAvailableCurrencyCodes(ULocale loc, Date d)
          Returns an array of Strings which contain the currency identifiers which 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.
static Currency getInstance(Locale locale)
          Returns a currency object for the default currency in the given locale.
static Currency getInstance(String theISOCode)
          Returns a currency object given an ISO 4217 3-letter code.
static Currency getInstance(ULocale locale)
          Returns a currency object for the default currency in the given locale.
 ULocale getLocale(ULocale.Type type)
          Deprecated. This API is obsolete.
 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.
 double getRoundingIncrement()
          Returns the rounding increment for this currency, or 0.0 if no rounding is done by this currency.
 String getSymbol()
          Convenience and compatibility override of getName that requests the symbol name.
 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.
 int hashCode()
          Return a hashcode for this currency.
static String parse(ULocale locale, String text, ParsePosition pos)
          Deprecated. This API is ICU internal only.
static Object registerInstance(Currency currency, ULocale locale)
          Registers a new currency for the provided locale.
 String toString()
          Returns the ISO 4217 code for this currency.
static boolean unregister(Object registryKey)
          Unregister the currency associated with this key (obtained from registerInstance).
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

SYMBOL_NAME

public static final int SYMBOL_NAME
Selector for getName() indicating a symbolic name for a currency, such as "$" for USD.

See Also:
Constant Field Values
Status:
Stable ICU 2.6.

LONG_NAME

public static final int LONG_NAME
Selector for ucurr_getName indicating the long name for a currency, such as "US Dollar" for USD.

See Also:
Constant Field Values
Status:
Stable ICU 2.6.
Constructor Detail

Currency

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.
Status:
Draft ICU 3.4.
Method Detail

getInstance

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
Status:
Stable ICU 2.2.

getInstance

public static Currency getInstance(ULocale locale)
Returns a currency object for the default currency in the given locale.

Status:
Stable ICU 3.2.

getAvailableCurrencyCodes

public static String[] getAvailableCurrencyCodes(ULocale loc,
                                                 Date d)
Returns an array of Strings which contain the currency identifiers which are valid for the given locale on the given date.

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.
Status:
Draft ICU 4.0.

getInstance

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:
NullPoninterException - if theISOCode is null.
IllegalArgumentException - if theISOCode is not a 3-letter alpha code.
Status:
Stable ICU 2.2.

registerInstance

public static Object registerInstance(Currency currency,
                                      ULocale locale)
Registers a new currency for the provided locale. The returned object is a key that can be used to unregister this currency object.

Parameters:
currency - the currency to register
locale - the ulocale under which to register the currency
Returns:
a registry key that can be used to unregister this currency
See Also:
unregister(java.lang.Object)
Status:
Stable ICU 3.2.

unregister

public static boolean unregister(Object registryKey)
Unregister the currency associated with this key (obtained from registerInstance).

Parameters:
registryKey - the registry key returned from registerInstance
See Also:
registerInstance(com.ibm.icu.util.Currency, com.ibm.icu.util.ULocale)
Status:
Stable ICU 2.6.

getAvailableLocales

public static Locale[] getAvailableLocales()
Return an array of the locales for which a currency is defined.

Returns:
an array of the available locales
Status:
Stable ICU 2.2.

getAvailableULocales

public static ULocale[] getAvailableULocales()
Return an array of the ulocales for which a currency is defined.

Returns:
an array of the available ulocales
Status:
Stable ICU 3.2.

hashCode

public int hashCode()
Return a hashcode for this currency.

Overrides:
hashCode in class Object
Status:
Stable ICU 2.2.

equals

public boolean equals(Object rhs)
Return true if rhs is a Currency instance, is non-null, and has the same currency code.

Overrides:
equals in class Object
Status:
Stable ICU 2.2.

getCurrencyCode

public String getCurrencyCode()
Returns the ISO 4217 3-letter code for this currency object.

Status:
Stable ICU 2.2.

getSymbol

public String getSymbol()
Convenience and compatibility override of getName that requests the symbol name.

See Also:
getName(java.util.Locale, int, boolean[])
Status:
Stable ICU 3.4.

getSymbol

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:
getName(java.util.Locale, int, boolean[])
Status:
Stable ICU 3.4.

getSymbol

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:
getName(java.util.Locale, int, boolean[])
Status:
Stable ICU 3.4.

getName

public String getName(Locale 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
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.
Status:
Stable ICU 3.2.

getName

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
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.
Status:
Stable ICU 3.2.

parse

public static String parse(ULocale locale,
                           String text,
                           ParsePosition pos)
Deprecated. This API is ICU internal only.

Attempt to parse the given string as a currency, either as a display name in the given locale, or as a 3-letter ISO 4217 code. If multiple display names match, then the longest one is selected. If both a display name and a 3-letter ISO code match, then the display name is preferred, unless it's length is less than 3.

Parameters:
locale - the locale of the display names to match
text - the text to parse
pos - input-output position; on input, the position within text to match; must have 0 <= pos.getIndex() < text.length(); on output, the position after the last matched character. If the parse fails, the position in unchanged upon output.
Returns:
the ISO 4217 code, as a string, of the best match, or null if there is no match
Status:
Internal. This API is ICU internal only.

getDefaultFractionDigits

public int getDefaultFractionDigits()
Returns the number of the number of fraction digits that should be displayed for this currency.

Returns:
a non-negative number of fraction digits to be displayed
Status:
Stable ICU 2.2.

getRoundingIncrement

public double getRoundingIncrement()
Returns the rounding increment for this currency, or 0.0 if no rounding is done by this currency.

Returns:
the non-negative rounding increment, or 0.0 if none
Status:
Stable ICU 2.2.

toString

public String toString()
Returns the ISO 4217 code for this currency.

Overrides:
toString in class Object
Status:
Stable ICU 2.2.

getLocale

public final ULocale getLocale(ULocale.Type type)
Deprecated. This API is obsolete.

Return the locale that was used to create this object, or null. This may may differ from the locale requested at the time of this object's creation. For example, if an object is created for locale en_US_CALIFORNIA, the actual data may be drawn from en (the actual locale), and en_US may be the most specific locale that exists (the valid locale).

Note: This method will be obsoleted. The implementation is no longer locale-specific and so there is no longer a valid or actual locale associated with the Currency object. Until it is removed, this method will return the root locale.

Parameters:
type - type of information requested, either ULocale.VALID_LOCALE or ULocale.ACTUAL_LOCALE.
Returns:
the information specified by type, or null if this object was not constructed from locale data.
See Also:
ULocale, ULocale.VALID_LOCALE, ULocale.ACTUAL_LOCALE
Status:
Obsolete. Will be removed in ICU 3.2 to be removed.


Copyright (c) 2009 IBM Corporation and others.