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 */ 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. If 114 * there is no data for the ISO code, substitutes isoCode, or returns null 115 * if noSubstitute was set in the factory method. 116 * 117 * @param isoCode the three-letter ISO code. 118 * @return the symbol. 119 * @stable ICU 4.4 120 */ getSymbol(String isoCode)121 public abstract String getSymbol(String isoCode); 122 123 /** 124 * Returns the narrow symbol for the currency with the provided ISO code. 125 * If there is no data for narrow symbol, substitutes isoCode, or returns 126 * null if noSubstitute was set in the factory method. 127 * 128 * @param isoCode the three-letter ISO code. 129 * @return the narrow symbol. 130 * @draft ICU 61 131 * @provisional This API might change or be removed in a future release. 132 */ getNarrowSymbol(String isoCode)133 public abstract String getNarrowSymbol(String isoCode); 134 135 /** 136 * Returns the 'long name' for the currency with the provided ISO code. 137 * If there is no data for the ISO code, substitutes isoCode, or returns null 138 * if noSubstitute was set in the factory method. 139 * 140 * @param isoCode the three-letter ISO code 141 * @return the display name 142 * @stable ICU 4.4 143 */ getName(String isoCode)144 public abstract String getName(String isoCode); 145 146 /** 147 * Returns a 'plural name' for the currency with the provided ISO code corresponding to 148 * the pluralKey. If there is no data for the ISO code, substitutes isoCode or 149 * returns null. If there is data for the ISO code but no data for the plural key, 150 * substitutes the 'other' value (and failing that the isoCode) or returns null. 151 * 152 * @param isoCode the three-letter ISO code 153 * @param pluralKey the plural key, for example "one", "other" 154 * @return the display name 155 * @see com.ibm.icu.text.PluralRules 156 * @stable ICU 4.4 157 */ getPluralName(String isoCode, String pluralKey)158 public abstract String getPluralName(String isoCode, String pluralKey); 159 160 /** 161 * Returns a mapping from localized symbols and currency codes to currency codes. 162 * The returned map is unmodifiable. 163 * @return the map 164 * @stable ICU 4.4 165 */ symbolMap()166 public abstract Map<String, String> symbolMap(); 167 168 /** 169 * Returns a mapping from localized names (standard and plural) to currency codes. 170 * The returned map is unmodifiable. 171 * @return the map 172 * @stable ICU 4.4 173 */ nameMap()174 public abstract Map<String, String> nameMap(); 175 176 /** 177 * Sole constructor. (For invocation by subclass constructors, 178 * typically implicit.) 179 * @internal 180 * @deprecated This API is ICU internal only. 181 */ 182 @Deprecated CurrencyDisplayNames()183 protected CurrencyDisplayNames() { 184 } 185 } 186