1 /* 2 ********************************************************************** 3 * Copyright (c) 2002-2010, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ********************************************************************** 6 */ 7 #ifndef _UCURR_H_ 8 #define _UCURR_H_ 9 10 #include "unicode/utypes.h" 11 #include "unicode/uenum.h" 12 13 /** 14 * \file 15 * \brief C API: Encapsulates information about a currency. 16 */ 17 18 #if !UCONFIG_NO_FORMATTING 19 20 /** 21 * The ucurr API encapsulates information about a currency, as defined by 22 * ISO 4217. A currency is represented by a 3-character string 23 * containing its ISO 4217 code. This API can return various data 24 * necessary the proper display of a currency: 25 * 26 * <ul><li>A display symbol, for a specific locale 27 * <li>The number of fraction digits to display 28 * <li>A rounding increment 29 * </ul> 30 * 31 * The <tt>DecimalFormat</tt> class uses these data to display 32 * currencies. 33 * @author Alan Liu 34 * @since ICU 2.2 35 */ 36 37 /** 38 * Finds a currency code for the given locale. 39 * @param locale the locale for which to retrieve a currency code. 40 * Currency can be specified by the "currency" keyword 41 * in which case it overrides the default currency code 42 * @param buff fill in buffer. Can be NULL for preflighting. 43 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 44 * preflighting. If it is non-zero, the buff parameter 45 * must not be NULL. 46 * @param ec error code 47 * @return length of the currency string. It should always be 3. If 0, 48 * currency couldn't be found or the input values are 49 * invalid. 50 * @stable ICU 2.8 51 */ 52 U_STABLE int32_t U_EXPORT2 53 ucurr_forLocale(const char* locale, 54 UChar* buff, 55 int32_t buffCapacity, 56 UErrorCode* ec); 57 58 /** 59 * Selector constants for ucurr_getName(). 60 * 61 * @see ucurr_getName 62 * @stable ICU 2.6 63 */ 64 typedef enum UCurrNameStyle { 65 /** 66 * Selector for ucurr_getName indicating a symbolic name for a 67 * currency, such as "$" for USD. 68 * @stable ICU 2.6 69 */ 70 UCURR_SYMBOL_NAME, 71 72 /** 73 * Selector for ucurr_getName indicating the long name for a 74 * currency, such as "US Dollar" for USD. 75 * @stable ICU 2.6 76 */ 77 UCURR_LONG_NAME 78 } UCurrNameStyle; 79 80 #if !UCONFIG_NO_SERVICE 81 /** 82 * @stable ICU 2.6 83 */ 84 typedef const void* UCurrRegistryKey; 85 86 /** 87 * Register an (existing) ISO 4217 currency code for the given locale. 88 * Only the country code and the two variants EURO and PRE_EURO are 89 * recognized. 90 * @param isoCode the three-letter ISO 4217 currency code 91 * @param locale the locale for which to register this currency code 92 * @param status the in/out status code 93 * @return a registry key that can be used to unregister this currency code, or NULL 94 * if there was an error. 95 * @stable ICU 2.6 96 */ 97 U_STABLE UCurrRegistryKey U_EXPORT2 98 ucurr_register(const UChar* isoCode, 99 const char* locale, 100 UErrorCode* status); 101 /** 102 * Unregister the previously-registered currency definitions using the 103 * URegistryKey returned from ucurr_register. Key becomes invalid after 104 * a successful call and should not be used again. Any currency 105 * that might have been hidden by the original ucurr_register call is 106 * restored. 107 * @param key the registry key returned by a previous call to ucurr_register 108 * @param status the in/out status code, no special meanings are assigned 109 * @return TRUE if the currency for this key was successfully unregistered 110 * @stable ICU 2.6 111 */ 112 U_STABLE UBool U_EXPORT2 113 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status); 114 #endif /* UCONFIG_NO_SERVICE */ 115 116 /** 117 * Returns the display name for the given currency in the 118 * given locale. For example, the display name for the USD 119 * currency object in the en_US locale is "$". 120 * @param currency null-terminated 3-letter ISO 4217 code 121 * @param locale locale in which to display currency 122 * @param nameStyle selector for which kind of name to return 123 * @param isChoiceFormat fill-in set to TRUE if the returned value 124 * is a ChoiceFormat pattern; otherwise it is a static string 125 * @param len fill-in parameter to receive length of result 126 * @param ec error code 127 * @return pointer to display string of 'len' UChars. If the resource 128 * data contains no entry for 'currency', then 'currency' itself is 129 * returned. If *isChoiceFormat is TRUE, then the result is a 130 * ChoiceFormat pattern. Otherwise it is a static string. 131 * @stable ICU 2.6 132 */ 133 U_STABLE const UChar* U_EXPORT2 134 ucurr_getName(const UChar* currency, 135 const char* locale, 136 UCurrNameStyle nameStyle, 137 UBool* isChoiceFormat, 138 int32_t* len, 139 UErrorCode* ec); 140 141 /** 142 * Returns the plural name for the given currency in the 143 * given locale. For example, the plural name for the USD 144 * currency object in the en_US locale is "US dollar" or "US dollars". 145 * @param currency null-terminated 3-letter ISO 4217 code 146 * @param locale locale in which to display currency 147 * @param isChoiceFormat fill-in set to TRUE if the returned value 148 * is a ChoiceFormat pattern; otherwise it is a static string 149 * @param pluralCount plural count 150 * @param len fill-in parameter to receive length of result 151 * @param ec error code 152 * @return pointer to display string of 'len' UChars. If the resource 153 * data contains no entry for 'currency', then 'currency' itself is 154 * returned. 155 * @stable ICU 4.2 156 */ 157 U_STABLE const UChar* U_EXPORT2 158 ucurr_getPluralName(const UChar* currency, 159 const char* locale, 160 UBool* isChoiceFormat, 161 const char* pluralCount, 162 int32_t* len, 163 UErrorCode* ec); 164 165 /** 166 * Returns the number of the number of fraction digits that should 167 * be displayed for the given currency. 168 * @param currency null-terminated 3-letter ISO 4217 code 169 * @param ec input-output error code 170 * @return a non-negative number of fraction digits to be 171 * displayed, or 0 if there is an error 172 * @stable ICU 3.0 173 */ 174 U_STABLE int32_t U_EXPORT2 175 ucurr_getDefaultFractionDigits(const UChar* currency, 176 UErrorCode* ec); 177 178 /** 179 * Returns the rounding increment for the given currency, or 0.0 if no 180 * rounding is done by the currency. 181 * @param currency null-terminated 3-letter ISO 4217 code 182 * @param ec input-output error code 183 * @return the non-negative rounding increment, or 0.0 if none, 184 * or 0.0 if there is an error 185 * @stable ICU 3.0 186 */ 187 U_STABLE double U_EXPORT2 188 ucurr_getRoundingIncrement(const UChar* currency, 189 UErrorCode* ec); 190 191 /** 192 * Selector constants for ucurr_openCurrencies(). 193 * 194 * @see ucurr_openCurrencies 195 * @stable ICU 3.2 196 */ 197 typedef enum UCurrCurrencyType { 198 /** 199 * Select all ISO-4217 currency codes. 200 * @stable ICU 3.2 201 */ 202 UCURR_ALL = INT32_MAX, 203 /** 204 * Select only ISO-4217 commonly used currency codes. 205 * These currencies can be found in common use, and they usually have 206 * bank notes or coins associated with the currency code. 207 * This does not include fund codes, precious metals and other 208 * various ISO-4217 codes limited to special financial products. 209 * @stable ICU 3.2 210 */ 211 UCURR_COMMON = 1, 212 /** 213 * Select ISO-4217 uncommon currency codes. 214 * These codes respresent fund codes, precious metals and other 215 * various ISO-4217 codes limited to special financial products. 216 * A fund code is a monetary resource associated with a currency. 217 * @stable ICU 3.2 218 */ 219 UCURR_UNCOMMON = 2, 220 /** 221 * Select only deprecated ISO-4217 codes. 222 * These codes are no longer in general public use. 223 * @stable ICU 3.2 224 */ 225 UCURR_DEPRECATED = 4, 226 /** 227 * Select only non-deprecated ISO-4217 codes. 228 * These codes are in general public use. 229 * @stable ICU 3.2 230 */ 231 UCURR_NON_DEPRECATED = 8 232 } UCurrCurrencyType; 233 234 /** 235 * Provides a UEnumeration object for listing ISO-4217 codes. 236 * @param currType You can use one of several UCurrCurrencyType values for this 237 * variable. You can also | (or) them together to get a specific list of 238 * currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to 239 * get a list of current currencies. 240 * @param pErrorCode Error code 241 * @stable ICU 3.2 242 */ 243 U_STABLE UEnumeration * U_EXPORT2 244 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode); 245 246 /** 247 * Finds the number of valid currency codes for the 248 * given locale and date. 249 * @param locale the locale for which to retrieve the 250 * currency count. 251 * @param date the date for which to retrieve the 252 * currency count for the given locale. 253 * @param ec error code 254 * @return the number of currency codes for the 255 * given locale and date. If 0, currency 256 * codes couldn't be found for the input 257 * values are invalid. 258 * @stable ICU 4.0 259 */ 260 U_STABLE int32_t U_EXPORT2 261 ucurr_countCurrencies(const char* locale, 262 UDate date, 263 UErrorCode* ec); 264 265 /** 266 * Finds a currency code for the given locale and date 267 * @param locale the locale for which to retrieve a currency code. 268 * Currency can be specified by the "currency" keyword 269 * in which case it overrides the default currency code 270 * @param date the date for which to retrieve a currency code for 271 * the given locale. 272 * @param index the index within the available list of currency codes 273 * for the given locale on the given date. 274 * @param buff fill in buffer. Can be NULL for preflighting. 275 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 276 * preflighting. If it is non-zero, the buff parameter 277 * must not be NULL. 278 * @param ec error code 279 * @return length of the currency string. It should always be 3. 280 * If 0, currency couldn't be found or the input values are 281 * invalid. 282 * @stable ICU 4.0 283 */ 284 U_STABLE int32_t U_EXPORT2 285 ucurr_forLocaleAndDate(const char* locale, 286 UDate date, 287 int32_t index, 288 UChar* buff, 289 int32_t buffCapacity, 290 UErrorCode* ec); 291 292 /** 293 * Given a key and a locale, returns an array of string values in a preferred 294 * order that would make a difference. These are all and only those values where 295 * the open (creation) of the service with the locale formed from the input locale 296 * plus input keyword and that value has different behavior than creation with the 297 * input locale alone. 298 * @param key one of the keys supported by this service. For now, only 299 * "currency" is supported. 300 * @param locale the locale 301 * @param commonlyUsed if set to true it will return only commonly used values 302 * with the given locale in preferred order. Otherwise, 303 * it will return all the available values for the locale. 304 * @param status error status 305 * @return a string enumeration over keyword values for the given key and the locale. 306 * @stable ICU 4.2 307 */ 308 U_STABLE UEnumeration* U_EXPORT2 309 ucurr_getKeywordValuesForLocale(const char* key, 310 const char* locale, 311 UBool commonlyUsed, 312 UErrorCode* status); 313 314 #endif /* #if !UCONFIG_NO_FORMATTING */ 315 316 #endif 317
