/*
*******************************************************************************
- * Copyright (C) 2009-2011, International Business Machines Corporation and *
+ * Copyright (C) 2009-2013, International Business Machines Corporation and *
* others. All Rights Reserved. *
*******************************************************************************
*/
import com.ibm.icu.util.Calendar;
import com.ibm.icu.util.GregorianCalendar;
+import com.ibm.icu.util.TimeZone;
/**
* Provides information about currencies that is not specific to a locale.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ *
+ * A note about currency dates. The CLDR data provides data to the day,
+ * inclusive. The date information used by CurrencyInfo and CurrencyFilter
+ * is represented by milliseconds, which is overly precise. These times are
+ * in GMT, so queries involving dates should use GMT times, but more generally
+ * you should avoid relying on time of day in queries.
+ *
+ * This class is not intended for public subclassing.
+ *
+ * @stable ICU 4.4
*/
public class CurrencyMetaInfo {
private static final CurrencyMetaInfo impl;
/**
* Returns the unique instance of the currency meta info.
* @return the meta info
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static CurrencyMetaInfo getInstance() {
return impl;
}
+ /**
+ * Returns the unique instance of the currency meta info, or null if
+ * noSubstitute is true and there is no data to support this API.
+ * @param noSubstitute true if no substitute data should be used
+ * @return the meta info, or null
+ * @stable ICU 49
+ */
+ public static CurrencyMetaInfo getInstance(boolean noSubstitute) {
+ return hasData ? impl : null;
+ }
+
/**
* Returns true if there is data for the currency meta info.
* @return true if there is actual data
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @internal
+ * @deprecated This API is ICU internal only.
*/
public static boolean hasData() {
return hasData;
/**
* A filter used to select which currency info is returned.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static final class CurrencyFilter {
/**
* The region to filter on. If null, accepts any region.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public final String region;
/**
* The currency to filter on. If null, accepts any currency.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public final String currency;
/**
- * The from date to filter on (milliseconds). Accepts any currency on or after this date.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * The from date to filter on (as milliseconds). Accepts any currency on or after this date.
+ * @stable ICU 4.4
*/
public final long from;
/**
- * The to date to filter on (milliseconds). Accepts any currency on or before this date.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * The to date to filter on (as milliseconds). Accepts any currency on or before this date.
+ * @stable ICU 4.4
*/
public final long to;
+
+ /**
+ * true if we are filtering only for currencies used as legal tender.
+ * @internal
+ * @deprecated This API is ICU internal only.
+ */
+ public final boolean tenderOnly;
- private CurrencyFilter(String region, String currency, long from, long to) {
+ private CurrencyFilter(String region, String currency, long from, long to, boolean tenderOnly) {
this.region = region;
this.currency = currency;
this.from = from;
this.to = to;
+ this.tenderOnly = tenderOnly;
+
}
- private CurrencyFilter(String region, String currency, Date dateFrom, Date dateTo) {
- this.region = region;
- this.currency = currency;
- this.from = dateFrom == null ? Long.MIN_VALUE : dateFrom.getTime();
- this.to = dateTo == null ? Long.MAX_VALUE : dateTo.getTime();
- }
-
- private static final CurrencyFilter ALL = new CurrencyFilter(null, null, null, null);
+ private static final CurrencyFilter ALL = new CurrencyFilter(
+ null, null, Long.MIN_VALUE, Long.MAX_VALUE, false);
/**
* Returns a filter that accepts all currency data.
* @return a filter
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static CurrencyFilter all() {
return ALL;
* Returns a filter that accepts all currencies in use as of the current date.
* @return a filter
* @see #withDate(Date)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static CurrencyFilter now() {
return ALL.withDate(new Date());
* @param region the region code
* @return a filter
* @see #withRegion(String)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static CurrencyFilter onRegion(String region) {
return ALL.withRegion(region);
* @param currency the currency code
* @return a filter
* @see #withCurrency(String)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static CurrencyFilter onCurrency(String currency) {
return ALL.withCurrency(currency);
* @param date the date
* @return a filter
* @see #withDate(Date)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static CurrencyFilter onDate(Date date) {
return ALL.withDate(date);
* Returns a filter that accepts all currencies that were in use at some point between
* the given dates, or if dates are equal, currencies in use on that date.
* @param from date on or after a currency must have been in use
- * @param to date before which a currency must have been in use, or if equal to from,
- * the date on which a currency must have been in use
+ * @param to date on or before which a currency must have been in use,
+ * or if equal to from, the date on which a currency must have been in use
* @return a filter
- * @see #withRange(Date, Date)
- * @draft ICU 4.4
+ * @see #withDateRange(Date, Date)
+ * @stable ICU 49
+ */
+ public static CurrencyFilter onDateRange(Date from, Date to) {
+ return ALL.withDateRange(from, to);
+ }
+
+ /**
+ * Returns a filter that accepts all currencies in use on the given date.
+ * @param date the date as milliseconds after Jan 1, 1970
+ * @draft ICU 51
+ * @provisional This API might change or be removed in a future release.
+ */
+ public static CurrencyFilter onDate(long date) {
+ return ALL.withDate(date);
+ }
+
+ /**
+ * Returns a filter that accepts all currencies that were in use at some
+ * point between the given dates, or if dates are equal, currencies in
+ * use on that date.
+ * @param from The date on or after a currency must have been in use.
+ * Measured in milliseconds since Jan 1, 1970 GMT.
+ * @param to The date on or before which a currency must have been in use.
+ * Measured in milliseconds since Jan 1, 1970 GMT.
+ * @draft ICU 51
* @provisional This API might change or be removed in a future release.
*/
- public static CurrencyFilter onRange(Date from, Date to) {
- return ALL.withRange(from, to);
+ public static CurrencyFilter onDateRange(long from, long to) {
+ return ALL.withDateRange(from, to);
+ }
+
+ /**
+ * Returns a CurrencyFilter for finding currencies that were either once used,
+ * are used, or will be used as tender.
+ * @draft ICU 51
+ * @provisional This API might change or be removed in a future release.
+ */
+ public static CurrencyFilter onTender() {
+ return ALL.withTender();
}
/**
* @param region the region code
* @return the filter
* @see #onRegion(String)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public CurrencyFilter withRegion(String region) {
- return new CurrencyFilter(region, this.currency, this.from, this.to);
+ return new CurrencyFilter(region, this.currency, this.from, this.to, this.tenderOnly);
}
/**
* @param currency the currency code
* @return the filter
* @see #onCurrency(String)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public CurrencyFilter withCurrency(String currency) {
- return new CurrencyFilter(this.region, currency, this.from, this.to);
+ return new CurrencyFilter(this.region, currency, this.from, this.to, this.tenderOnly);
}
/**
* @param date the date on which the currency must have been in use
* @return the filter
* @see #onDate(Date)
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public CurrencyFilter withDate(Date date) {
- return new CurrencyFilter(this.region, this.currency, date, date);
+ return new CurrencyFilter(this.region, this.currency, date.getTime(), date.getTime(), this.tenderOnly);
}
/**
* Returns a copy of this filter, with from and to set to the given dates.
* @param from date on or after which the currency must have been in use
- * @param to date before which the currency must have been in use
+ * @param to date on or before which the currency must have been in use
* @return the filter
- * @see #onRange(Date, Date)
- * @draft ICU 4.4
+ * @see #onDateRange(Date, Date)
+ * @stable ICU 49
+ */
+ public CurrencyFilter withDateRange(Date from, Date to) {
+ long fromLong = from == null ? Long.MIN_VALUE : from.getTime();
+ long toLong = to == null ? Long.MAX_VALUE : to.getTime();
+ return new CurrencyFilter(this.region, this.currency, fromLong, toLong, this.tenderOnly);
+ }
+
+ /**
+ * Returns a copy of this filter that accepts all currencies in use on
+ * the given date.
+ * @param date the date as milliseconds after Jan 1, 1970
+ * @draft ICU 51
* @provisional This API might change or be removed in a future release.
*/
- public CurrencyFilter withRange(Date from, Date to) {
- return new CurrencyFilter(this.region, this.currency, from, to);
+ public CurrencyFilter withDate(long date) {
+ return new CurrencyFilter(this.region, this.currency, date, date, this.tenderOnly);
}
/**
- * Overrides equals.
- * @draft ICU 4.4
+ * Returns a copy of this filter that accepts all currencies that were
+ * in use at some point between the given dates, or if dates are equal,
+ * currencies in use on that date.
+ * @param from The date on or after a currency must have been in use.
+ * Measured in milliseconds since Jan 1, 1970 GMT.
+ * @param to The date on or before which a currency must have been in use.
+ * Measured in milliseconds since Jan 1, 1970 GMT.
+ * @draft ICU 51
+ * @provisional This API might change or be removed in a future release.
+ */
+ public CurrencyFilter withDateRange(long from, long to) {
+ return new CurrencyFilter(this.region, this.currency, from, to, this.tenderOnly);
+ }
+
+ /**
+ * Returns a copy of this filter that filters for currencies that were
+ * either once used, are used, or will be used as tender.
+ * @draft ICU 51
* @provisional This API might change or be removed in a future release.
*/
+ public CurrencyFilter withTender() {
+ return new CurrencyFilter(this.region, this.currency, this.from, this.to, true);
+ }
+
+ /**
+ * {@inheritDoc}
+ * @stable ICU 4.4
+ */
@Override
public boolean equals(Object rhs) {
return rhs instanceof CurrencyFilter &&
* Type-safe override of {@link #equals(Object)}.
* @param rhs the currency filter to compare to
* @return true if the filters are equal
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public boolean equals(CurrencyFilter rhs) {
return this == rhs || (rhs != null &&
equals(this.region, rhs.region) &&
equals(this.currency, rhs.currency) &&
this.from == rhs.from &&
- this.to == rhs.to);
+ this.to == rhs.to &&
+ this.tenderOnly == rhs.tenderOnly);
}
/**
- * Overrides hashCode.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * {@inheritDoc}
+ * @stable ICU 4.4
*/
@Override
public int hashCode() {
hc = hc * 31 + (int) (from >>> 32);
hc = hc * 31 + (int) to;
hc = hc * 31 + (int) (to >>> 32);
+ hc = hc * 31 + (tenderOnly ? 1 : 0);
return hc;
}
/**
* Returns a string representing the filter, for debugging.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @return A string representing the filter.
+ * @stable ICU 4.4
*/
@Override
public String toString() {
/**
* Represents the raw information about fraction digits and rounding increment.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public static final class CurrencyDigits {
/**
* Number of fraction digits used to display this currency.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 49
*/
- public final byte fractionDigits;
+ public final int fractionDigits;
/**
* Rounding increment used when displaying this currency.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 49
*/
- public final byte roundingIncrement;
+ public final int roundingIncrement;
/**
* Constructor for CurrencyDigits.
* @param fractionDigits the fraction digits
* @param roundingIncrement the rounding increment
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public CurrencyDigits(int fractionDigits, int roundingIncrement) {
- this.fractionDigits = (byte) fractionDigits;
- this.roundingIncrement = (byte) roundingIncrement;
+ this.fractionDigits = fractionDigits;
+ this.roundingIncrement = roundingIncrement;
}
/**
* Returns a string representing the currency digits, for debugging.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @return A string representing the currency digits.
+ * @stable ICU 4.4
*/
@Override
public String toString() {
/**
* Represents a complete currency info record listing the region, currency, from and to dates,
* and priority.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * Use {@link CurrencyMetaInfo#currencyInfo(CurrencyFilter)}
+ * for a list of info objects matching the filter.
+ * @stable ICU 4.4
*/
public static final class CurrencyInfo {
/**
* Region code where currency is used.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public final String region;
/**
* The three-letter ISO currency code.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public final String code;
/**
- * Date on which the currency was first officially used in the region. If there is no
- * date, this is Long.MIN_VALUE;
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * Date on which the currency was first officially used in the region.
+ * This is midnight at the start of the first day on which the currency was used, GMT.
+ * If there is no date, this is Long.MIN_VALUE;
+ * @stable ICU 4.4
*/
public final long from;
/**
- * Date at which the currency stopped being officially used in the region. If there is
- * no date, this is Long.MAX_VALUE;
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * Date at which the currency stopped being officially used in the region.
+ * This is one millisecond before midnight at the end of the last day on which the currency was used, GMT.
+ * If there is no date, this is Long.MAX_VALUE.
+ *
+ * @stable ICU 4.4
*/
public final long to;
* Preference order of currencies being used at the same time in the region. Lower
* values are preferred (generally, this is a transition from an older to a newer
* currency). Priorities within a single country are unique.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 49
*/
- public final short priority;
+ public final int priority;
+
+
+ private final boolean tender;
+ /**
+ * @deprecated ICU 51 Use {@link CurrencyMetaInfo#currencyInfo(CurrencyFilter)} instead.
+ */
+ public CurrencyInfo(String region, String code, long from, long to, int priority) {
+ this(region, code, from, to, priority, true);
+ }
+
/**
* Constructs a currency info.
- * @param region region code
- * @param code currency code
- * @param from start date in milliseconds
- * @param to end date in milliseconds
- * @param priority priority value, 0 is highest priority, increasing values are lower
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ *
+ * @internal
+ * @deprecated This API is ICU internal only.
*/
- public CurrencyInfo(String region, String code, long from, long to, int priority) {
+ public CurrencyInfo(String region, String code, long from, long to, int priority, boolean tender) {
this.region = region;
this.code = code;
this.from = from;
this.to = to;
- this.priority = (short) priority;
+ this.priority = priority;
+ this.tender = tender;
}
/**
- * Returns a string useful for debugging.
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * Returns a string representation of this object, useful for debugging.
+ * @return A string representation of this object.
+ * @stable ICU 4.4
*/
@Override
public String toString() {
return debugString(this);
}
+
+ /**
+ * Determine whether or not this currency was once used, is used,
+ * or will be used as tender in this region.
+ * @draft ICU 51
+ * @provisional This API might change or be removed in a future release.
+ */
+ public boolean isTender() {
+ return tender;
+ }
}
///CLOVER:OFF
/**
* Returns the list of CurrencyInfos matching the provided filter. Results
- * are ordered by country code, then by highest to lowest priority (0 is highest).
+ * are ordered by country code, then by highest to lowest priority (0 is highest).
* The returned list is unmodifiable.
* @param filter the filter to control which currency info to return
* @return the matching information
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public List<CurrencyInfo> currencyInfo(CurrencyFilter filter) {
return Collections.emptyList();
* @param filter the filter to control which currencies to return. If filter is null,
* returns all currencies for which information is available.
* @return the matching currency codes
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public List<String> currencies(CurrencyFilter filter) {
return Collections.emptyList();
- }
+ }
/**
* Returns the list of region codes matching the provided filter.
* @param filter the filter to control which regions to return. If filter is null,
* returns all regions for which information is available.
* @return the matching region codes
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public List<String> regions(CurrencyFilter filter) {
return Collections.emptyList();
* Returns the CurrencyDigits for the currency code.
* @param isoCode the currency code
* @return the CurrencyDigits
- * @draft ICU 4.4
- * @provisional This API might change or be removed in a future release.
+ * @stable ICU 4.4
*/
public CurrencyDigits currencyDigits(String isoCode) {
return defaultDigits;
return null;
}
GregorianCalendar gc = new GregorianCalendar();
+ gc.setTimeZone(TimeZone.getTimeZone("GMT"));
gc.setTimeInMillis(date);
return "" + gc.get(Calendar.YEAR) + '-' + (gc.get(Calendar.MONTH) + 1) + '-' +
gc.get(Calendar.DAY_OF_MONTH);