1 // 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html#License 3 /* 4 ******************************************************************************* 5 * Copyright (C) 2009-2016, International Business Machines Corporation and * 6 * others. All Rights Reserved. * 7 ******************************************************************************* 8 */ 9 package com.ibm.icu.text; 10 11 import java.util.Locale; 12 import java.util.Map; 13 14 import com.ibm.icu.impl.CurrencyData; 15 import com.ibm.icu.util.ULocale; 16 17 /** 18 * Returns currency names localized for a locale. 19 * 20 * This class is not intended for public subclassing. 21 * 22 * @stable ICU 4.4 23 */ 24 public abstract class CurrencyDisplayNames { 25 /** 26 * Return an instance of CurrencyDisplayNames that provides information 27 * localized for display in the provided locale. If there is no data for the 28 * provided locale, this falls back to the current default locale; if there 29 * is no data for that either, it falls back to the root locale. Substitute 30 * values are returned from APIs when there is no data for the requested ISO 31 * code. 32 * 33 * @param locale the locale into which to localize the names 34 * @return a CurrencyDisplayNames 35 * @stable ICU 4.4 36 */ 37 public static CurrencyDisplayNames getInstance(ULocale locale) { 38 return CurrencyData.provider.getInstance(locale, true); 39 } 40 41 /** 42 * Return an instance of CurrencyDisplayNames that provides information 43 * localized for display in the provided locale. If there is no data for the 44 * provided locale, this falls back to the current default locale; if there 45 * is no data for that either, it falls back to the root locale. Substitute 46 * values are returned from APIs when there is no data for the requested ISO 47 * code. 48 * 49 * @param locale the locale into which to localize the names 50 * @return a CurrencyDisplayNames 51 * @stable ICU 54 52 */ 53 public static CurrencyDisplayNames getInstance(Locale locale) { 54 return getInstance(locale, true); 55 } 56 57 /** 58 * Return an instance of CurrencyDisplayNames that provides information 59 * localized for display in the provided locale. If noSubstitute is false, 60 * this behaves like {@link #getInstance(ULocale)}. Otherwise, 1) if there 61 * is no supporting data for the locale at all, there is no fallback through 62 * the default locale or root, and null is returned, and 2) if there is data 63 * for the locale, but not data for the requested ISO code, null is returned 64 * from those APIs instead of a substitute value. 65 * 66 * @param locale the locale into which to localize the names 67 * @param noSubstitute if true, do not return substitute values. 68 * @return a CurrencyDisplayNames 69 * @stable ICU 49 70 */ 71 public static CurrencyDisplayNames getInstance(ULocale locale, boolean noSubstitute) { 72 return CurrencyData.provider.getInstance(locale, !noSubstitute); 73 } 74 75 /** 76 * Return an instance of CurrencyDisplayNames that provides information 77 * localized for display in the provided locale. If noSubstitute is false, 78 * this behaves like {@link #getInstance(Locale)}. Otherwise, 1) if there 79 * is no supporting data for the locale at all, there is no fallback through 80 * the default locale or root, and null is returned, and 2) if there is data 81 * for the locale, but not data for the requested ISO code, null is returned 82 * from those APIs instead of a substitute value. 83 * 84 * @param locale the {@link java.util.Locale} into which to localize the names 85 * @param noSubstitute if true, do not return substitute values. 86 * @return a CurrencyDisplayNames 87 * @stable ICU 54 88 */ 89 public static CurrencyDisplayNames getInstance(Locale locale, boolean noSubstitute) { 90 return getInstance(ULocale.forLocale(locale), noSubstitute); 91 } 92 93 /** 94 * Returns true if currency display name data is available. 95 * @return true if currency display name data is available 96 * @internal 97 * @deprecated This API is ICU internal only. 98 */ 99 @Deprecated 100 public static boolean hasData() { 101 return CurrencyData.provider.hasData(); 102 } 103 104 /** 105 * Returns the locale used to determine how to translate the currency names. 106 * This is not necessarily the same locale passed to {@link #getInstance(ULocale)}. 107 * @return the display locale 108 * @stable ICU 49 109 */ 110 public abstract ULocale getULocale(); 111 112 /** 113 * Returns the symbol for the currency with the provided ISO code. If 114 * there is no data for the ISO code, substitutes isoCode or returns null. 115 * 116 * @param isoCode the three-letter ISO code. 117 * @return the display name. 118 * @stable ICU 4.4 119 */ 120 public abstract String getSymbol(String isoCode); 121 122 /** 123 * Returns the 'long name' for the currency with the provided ISO code. 124 * If there is no data for the ISO code, substitutes isoCode or returns null. 125 * 126 * @param isoCode the three-letter ISO code 127 * @return the display name 128 * @stable ICU 4.4 129 */ 130 public abstract String getName(String isoCode); 131 132 /** 133 * Returns a 'plural name' for the currency with the provided ISO code corresponding to 134 * the pluralKey. If there is no data for the ISO code, substitutes isoCode or 135 * returns null. If there is data for the ISO code but no data for the plural key, 136 * substitutes the 'other' value (and failing that the isoCode) or returns null. 137 * 138 * @param isoCode the three-letter ISO code 139 * @param pluralKey the plural key, for example "one", "other" 140 * @return the display name 141 * @see com.ibm.icu.text.PluralRules 142 * @stable ICU 4.4 143 */ 144 public abstract String getPluralName(String isoCode, String pluralKey); 145 146 /** 147 * Returns a mapping from localized symbols and currency codes to currency codes. 148 * The returned map is unmodifiable. 149 * @return the map 150 * @stable ICU 4.4 151 */ 152 public abstract Map<String, String> symbolMap(); 153 154 /** 155 * Returns a mapping from localized names (standard and plural) to currency codes. 156 * The returned map is unmodifiable. 157 * @return the map 158 * @stable ICU 4.4 159 */ 160 public abstract Map<String, String> nameMap(); 161 162 /** 163 * Sole constructor. (For invocation by subclass constructors, 164 * typically implicit.) 165 * @internal 166 * @deprecated This API is ICU internal only. 167 */ 168 @Deprecated 169 protected CurrencyDisplayNames() { 170 } 171 } 172
