1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 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 */ getInstance(ULocale locale)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 */ getInstance(Locale locale)53 public static CurrencyDisplayNames getInstance(Locale locale) { 54 return getInstance(locale, false); 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 */ getInstance(ULocale locale, boolean noSubstitute)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 */ getInstance(Locale locale, boolean noSubstitute)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 hasData()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 */ getULocale()110 public abstract ULocale getULocale(); 111 112 /** 113 * Returns the symbol for the currency with the provided ISO code. 114 * <p> 115 * If there is no data for this symbol, substitutes isoCode, 116 * or returns null if noSubstitute was set in the factory method. 117 * 118 * @param isoCode the three-letter ISO code. 119 * @return the symbol. 120 * @stable ICU 4.4 121 */ getSymbol(String isoCode)122 public abstract String getSymbol(String isoCode); 123 124 /** 125 * Returns the narrow symbol for the currency with the provided ISO code. 126 * <p> 127 * The narrow currency symbol is similar to the regular currency symbol, 128 * but it always takes the shortest form; 129 * for example, "$" instead of "US$" for USD in en-CA. 130 * <p> 131 * If there is no data for this symbol, substitutes the default symbol, 132 * or returns null if noSubstitute was set in the factory method. 133 * 134 * @param isoCode the three-letter ISO code. 135 * @return the narrow symbol. 136 * @stable ICU 61 137 */ getNarrowSymbol(String isoCode)138 public abstract String getNarrowSymbol(String isoCode); 139 140 /** 141 * Returns the formal symbol for the currency with the provided ISO code. 142 * <p> 143 * The formal currency symbol is similar to the regular currency symbol, 144 * but it always takes the form used in formal settings such as banking; 145 * for example, "NT$" instead of "$" for TWD in zh-TW. 146 * <p> 147 * If there is no data for this symbol, substitutes the default symbol, 148 * or returns null if noSubstitute was set in the factory method. 149 * 150 * @param isoCode the three-letter ISO code. 151 * @return the formal symbol. 152 * @stable ICU 67 153 */ getFormalSymbol(String isoCode)154 public abstract String getFormalSymbol(String isoCode); 155 156 /** 157 * Returns the variant symbol for the currency with the provided ISO code. 158 * <p> 159 * The variant symbol for a currency is an alternative symbol that is not 160 * necessarily as widely used as the regular symbol. 161 * <p> 162 * If there is no data for variant symbol, substitutes the default symbol, 163 * or returns null if noSubstitute was set in the factory method. 164 * 165 * @param isoCode the three-letter ISO code. 166 * @return the variant symbol. 167 * @stable ICU 67 168 */ getVariantSymbol(String isoCode)169 public abstract String getVariantSymbol(String isoCode); 170 171 /** 172 * Returns the 'long name' for the currency with the provided ISO code. 173 * If there is no data for the ISO code, substitutes isoCode, or returns null 174 * if noSubstitute was set in the factory method. 175 * 176 * @param isoCode the three-letter ISO code 177 * @return the display name 178 * @stable ICU 4.4 179 */ getName(String isoCode)180 public abstract String getName(String isoCode); 181 182 /** 183 * Returns a 'plural name' for the currency with the provided ISO code corresponding to 184 * the pluralKey. If there is no data for the ISO code, substitutes isoCode or 185 * returns null. If there is data for the ISO code but no data for the plural key, 186 * substitutes the 'other' value (and failing that the isoCode) or returns null. 187 * 188 * @param isoCode the three-letter ISO code 189 * @param pluralKey the plural key, for example "one", "other" 190 * @return the display name 191 * @see com.ibm.icu.text.PluralRules 192 * @stable ICU 4.4 193 */ getPluralName(String isoCode, String pluralKey)194 public abstract String getPluralName(String isoCode, String pluralKey); 195 196 /** 197 * Returns a mapping from localized symbols and currency codes to currency codes. 198 * The returned map is unmodifiable. 199 * @return the map 200 * @stable ICU 4.4 201 */ symbolMap()202 public abstract Map<String, String> symbolMap(); 203 204 /** 205 * Returns a mapping from localized names (standard and plural) to currency codes. 206 * The returned map is unmodifiable. 207 * @return the map 208 * @stable ICU 4.4 209 */ nameMap()210 public abstract Map<String, String> nameMap(); 211 212 /** 213 * Sole constructor. (For invocation by subclass constructors, 214 * typically implicit.) 215 * @internal 216 * @deprecated This API is ICU internal only. 217 */ 218 @Deprecated CurrencyDisplayNames()219 protected CurrencyDisplayNames() { 220 } 221 } 222