1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ********************************************************************** 5 * Copyright (c) 2002-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ********************************************************************** 8 */ 9 #ifndef _UCURR_H_ 10 #define _UCURR_H_ 11 12 #include "unicode/utypes.h" 13 #include "unicode/uenum.h" 14 15 /** 16 * \file 17 * \brief C API: Encapsulates information about a currency. 18 * 19 * The ucurr API encapsulates information about a currency, as defined by 20 * ISO 4217. A currency is represented by a 3-character string 21 * containing its ISO 4217 code. This API can return various data 22 * necessary the proper display of a currency: 23 * 24 * <ul><li>A display symbol, for a specific locale 25 * <li>The number of fraction digits to display 26 * <li>A rounding increment 27 * </ul> 28 * 29 * The <tt>DecimalFormat</tt> class uses these data to display 30 * currencies. 31 * @author Alan Liu 32 * @since ICU 2.2 33 */ 34 35 #if !UCONFIG_NO_FORMATTING 36 37 /** 38 * Currency Usage used for Decimal Format 39 * @stable ICU 54 40 */ 41 enum UCurrencyUsage { 42 /** 43 * a setting to specify currency usage which determines currency digit 44 * and rounding for standard usage, for example: "50.00 NT$" 45 * used as DEFAULT value 46 * @stable ICU 54 47 */ 48 UCURR_USAGE_STANDARD=0, 49 /** 50 * a setting to specify currency usage which determines currency digit 51 * and rounding for cash usage, for example: "50 NT$" 52 * @stable ICU 54 53 */ 54 UCURR_USAGE_CASH=1, 55 #ifndef U_HIDE_DEPRECATED_API 56 /** 57 * One higher than the last enum UCurrencyUsage constant. 58 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 59 */ 60 UCURR_USAGE_COUNT=2 61 #endif // U_HIDE_DEPRECATED_API 62 }; 63 typedef enum UCurrencyUsage UCurrencyUsage; 64 65 /** 66 * Finds a currency code for the given locale. 67 * @param locale the locale for which to retrieve a currency code. 68 * Currency can be specified by the "currency" keyword 69 * in which case it overrides the default currency code 70 * @param buff fill in buffer. Can be NULL for preflighting. 71 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 72 * preflighting. If it is non-zero, the buff parameter 73 * must not be NULL. 74 * @param ec error code 75 * @return length of the currency string. It should always be 3. If 0, 76 * currency couldn't be found or the input values are 77 * invalid. 78 * @stable ICU 2.8 79 */ 80 U_STABLE int32_t U_EXPORT2 81 ucurr_forLocale(const char* locale, 82 UChar* buff, 83 int32_t buffCapacity, 84 UErrorCode* ec); 85 86 /** 87 * Selector constants for ucurr_getName(). 88 * 89 * @see ucurr_getName 90 * @stable ICU 2.6 91 */ 92 typedef enum UCurrNameStyle { 93 /** 94 * Selector for ucurr_getName indicating a symbolic name for a 95 * currency, such as "$" for USD. 96 * @stable ICU 2.6 97 */ 98 UCURR_SYMBOL_NAME, 99 100 /** 101 * Selector for ucurr_getName indicating the long name for a 102 * currency, such as "US Dollar" for USD. 103 * @stable ICU 2.6 104 */ 105 UCURR_LONG_NAME 106 } UCurrNameStyle; 107 108 #if !UCONFIG_NO_SERVICE 109 /** 110 * @stable ICU 2.6 111 */ 112 typedef const void* UCurrRegistryKey; 113 114 /** 115 * Register an (existing) ISO 4217 currency code for the given locale. 116 * Only the country code and the two variants EURO and PRE_EURO are 117 * recognized. 118 * @param isoCode the three-letter ISO 4217 currency code 119 * @param locale the locale for which to register this currency code 120 * @param status the in/out status code 121 * @return a registry key that can be used to unregister this currency code, or NULL 122 * if there was an error. 123 * @stable ICU 2.6 124 */ 125 U_STABLE UCurrRegistryKey U_EXPORT2 126 ucurr_register(const UChar* isoCode, 127 const char* locale, 128 UErrorCode* status); 129 /** 130 * Unregister the previously-registered currency definitions using the 131 * URegistryKey returned from ucurr_register. Key becomes invalid after 132 * a successful call and should not be used again. Any currency 133 * that might have been hidden by the original ucurr_register call is 134 * restored. 135 * @param key the registry key returned by a previous call to ucurr_register 136 * @param status the in/out status code, no special meanings are assigned 137 * @return TRUE if the currency for this key was successfully unregistered 138 * @stable ICU 2.6 139 */ 140 U_STABLE UBool U_EXPORT2 141 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status); 142 #endif /* UCONFIG_NO_SERVICE */ 143 144 /** 145 * Returns the display name for the given currency in the 146 * given locale. For example, the display name for the USD 147 * currency object in the en_US locale is "$". 148 * @param currency null-terminated 3-letter ISO 4217 code 149 * @param locale locale in which to display currency 150 * @param nameStyle selector for which kind of name to return 151 * @param isChoiceFormat fill-in set to TRUE if the returned value 152 * is a ChoiceFormat pattern; otherwise it is a static string 153 * @param len fill-in parameter to receive length of result 154 * @param ec error code 155 * @return pointer to display string of 'len' UChars. If the resource 156 * data contains no entry for 'currency', then 'currency' itself is 157 * returned. If *isChoiceFormat is TRUE, then the result is a 158 * ChoiceFormat pattern. Otherwise it is a static string. 159 * @stable ICU 2.6 160 */ 161 U_STABLE const UChar* U_EXPORT2 162 ucurr_getName(const UChar* currency, 163 const char* locale, 164 UCurrNameStyle nameStyle, 165 UBool* isChoiceFormat, 166 int32_t* len, 167 UErrorCode* ec); 168 169 /** 170 * Returns the plural name for the given currency in the 171 * given locale. For example, the plural name for the USD 172 * currency object in the en_US locale is "US dollar" or "US dollars". 173 * @param currency null-terminated 3-letter ISO 4217 code 174 * @param locale locale in which to display currency 175 * @param isChoiceFormat fill-in set to TRUE if the returned value 176 * is a ChoiceFormat pattern; otherwise it is a static string 177 * @param pluralCount plural count 178 * @param len fill-in parameter to receive length of result 179 * @param ec error code 180 * @return pointer to display string of 'len' UChars. If the resource 181 * data contains no entry for 'currency', then 'currency' itself is 182 * returned. 183 * @stable ICU 4.2 184 */ 185 U_STABLE const UChar* U_EXPORT2 186 ucurr_getPluralName(const UChar* currency, 187 const char* locale, 188 UBool* isChoiceFormat, 189 const char* pluralCount, 190 int32_t* len, 191 UErrorCode* ec); 192 193 /** 194 * Returns the number of the number of fraction digits that should 195 * be displayed for the given currency. 196 * This is equivalent to ucurr_getDefaultFractionDigitsForUsage(currency,UCURR_USAGE_STANDARD,ec); 197 * @param currency null-terminated 3-letter ISO 4217 code 198 * @param ec input-output error code 199 * @return a non-negative number of fraction digits to be 200 * displayed, or 0 if there is an error 201 * @stable ICU 3.0 202 */ 203 U_STABLE int32_t U_EXPORT2 204 ucurr_getDefaultFractionDigits(const UChar* currency, 205 UErrorCode* ec); 206 207 /** 208 * Returns the number of the number of fraction digits that should 209 * be displayed for the given currency with usage. 210 * @param currency null-terminated 3-letter ISO 4217 code 211 * @param usage enum usage for the currency 212 * @param ec input-output error code 213 * @return a non-negative number of fraction digits to be 214 * displayed, or 0 if there is an error 215 * @stable ICU 54 216 */ 217 U_STABLE int32_t U_EXPORT2 218 ucurr_getDefaultFractionDigitsForUsage(const UChar* currency, 219 const UCurrencyUsage usage, 220 UErrorCode* ec); 221 222 /** 223 * Returns the rounding increment for the given currency, or 0.0 if no 224 * rounding is done by the currency. 225 * This is equivalent to ucurr_getRoundingIncrementForUsage(currency,UCURR_USAGE_STANDARD,ec); 226 * @param currency null-terminated 3-letter ISO 4217 code 227 * @param ec input-output error code 228 * @return the non-negative rounding increment, or 0.0 if none, 229 * or 0.0 if there is an error 230 * @stable ICU 3.0 231 */ 232 U_STABLE double U_EXPORT2 233 ucurr_getRoundingIncrement(const UChar* currency, 234 UErrorCode* ec); 235 236 /** 237 * Returns the rounding increment for the given currency, or 0.0 if no 238 * rounding is done by the currency given usage. 239 * @param currency null-terminated 3-letter ISO 4217 code 240 * @param usage enum usage for the currency 241 * @param ec input-output error code 242 * @return the non-negative rounding increment, or 0.0 if none, 243 * or 0.0 if there is an error 244 * @stable ICU 54 245 */ 246 U_STABLE double U_EXPORT2 247 ucurr_getRoundingIncrementForUsage(const UChar* currency, 248 const UCurrencyUsage usage, 249 UErrorCode* ec); 250 251 /** 252 * Selector constants for ucurr_openCurrencies(). 253 * 254 * @see ucurr_openCurrencies 255 * @stable ICU 3.2 256 */ 257 typedef enum UCurrCurrencyType { 258 /** 259 * Select all ISO-4217 currency codes. 260 * @stable ICU 3.2 261 */ 262 UCURR_ALL = INT32_MAX, 263 /** 264 * Select only ISO-4217 commonly used currency codes. 265 * These currencies can be found in common use, and they usually have 266 * bank notes or coins associated with the currency code. 267 * This does not include fund codes, precious metals and other 268 * various ISO-4217 codes limited to special financial products. 269 * @stable ICU 3.2 270 */ 271 UCURR_COMMON = 1, 272 /** 273 * Select ISO-4217 uncommon currency codes. 274 * These codes respresent fund codes, precious metals and other 275 * various ISO-4217 codes limited to special financial products. 276 * A fund code is a monetary resource associated with a currency. 277 * @stable ICU 3.2 278 */ 279 UCURR_UNCOMMON = 2, 280 /** 281 * Select only deprecated ISO-4217 codes. 282 * These codes are no longer in general public use. 283 * @stable ICU 3.2 284 */ 285 UCURR_DEPRECATED = 4, 286 /** 287 * Select only non-deprecated ISO-4217 codes. 288 * These codes are in general public use. 289 * @stable ICU 3.2 290 */ 291 UCURR_NON_DEPRECATED = 8 292 } UCurrCurrencyType; 293 294 /** 295 * Provides a UEnumeration object for listing ISO-4217 codes. 296 * @param currType You can use one of several UCurrCurrencyType values for this 297 * variable. You can also | (or) them together to get a specific list of 298 * currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to 299 * get a list of current currencies. 300 * @param pErrorCode Error code 301 * @stable ICU 3.2 302 */ 303 U_STABLE UEnumeration * U_EXPORT2 304 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode); 305 306 /** 307 * Queries if the given ISO 4217 3-letter code is available on the specified date range. 308 * 309 * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to' 310 * 311 * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time. 312 * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date. 313 * 314 * @param isoCode 315 * The ISO 4217 3-letter code. 316 * 317 * @param from 318 * The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability 319 * of the currency any date before 'to' 320 * 321 * @param to 322 * The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of 323 * the currency any date after 'from' 324 * 325 * @param errorCode 326 * ICU error code 327 * 328 * @return TRUE if the given ISO 4217 3-letter code is supported on the specified date range. 329 * 330 * @stable ICU 4.8 331 */ 332 U_STABLE UBool U_EXPORT2 333 ucurr_isAvailable(const UChar* isoCode, 334 UDate from, 335 UDate to, 336 UErrorCode* errorCode); 337 338 /** 339 * Finds the number of valid currency codes for the 340 * given locale and date. 341 * @param locale the locale for which to retrieve the 342 * currency count. 343 * @param date the date for which to retrieve the 344 * currency count for the given locale. 345 * @param ec error code 346 * @return the number of currency codes for the 347 * given locale and date. If 0, currency 348 * codes couldn't be found for the input 349 * values are invalid. 350 * @stable ICU 4.0 351 */ 352 U_STABLE int32_t U_EXPORT2 353 ucurr_countCurrencies(const char* locale, 354 UDate date, 355 UErrorCode* ec); 356 357 /** 358 * Finds a currency code for the given locale and date 359 * @param locale the locale for which to retrieve a currency code. 360 * Currency can be specified by the "currency" keyword 361 * in which case it overrides the default currency code 362 * @param date the date for which to retrieve a currency code for 363 * the given locale. 364 * @param index the index within the available list of currency codes 365 * for the given locale on the given date. 366 * @param buff fill in buffer. Can be NULL for preflighting. 367 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 368 * preflighting. If it is non-zero, the buff parameter 369 * must not be NULL. 370 * @param ec error code 371 * @return length of the currency string. It should always be 3. 372 * If 0, currency couldn't be found or the input values are 373 * invalid. 374 * @stable ICU 4.0 375 */ 376 U_STABLE int32_t U_EXPORT2 377 ucurr_forLocaleAndDate(const char* locale, 378 UDate date, 379 int32_t index, 380 UChar* buff, 381 int32_t buffCapacity, 382 UErrorCode* ec); 383 384 /** 385 * Given a key and a locale, returns an array of string values in a preferred 386 * order that would make a difference. These are all and only those values where 387 * the open (creation) of the service with the locale formed from the input locale 388 * plus input keyword and that value has different behavior than creation with the 389 * input locale alone. 390 * @param key one of the keys supported by this service. For now, only 391 * "currency" is supported. 392 * @param locale the locale 393 * @param commonlyUsed if set to true it will return only commonly used values 394 * with the given locale in preferred order. Otherwise, 395 * it will return all the available values for the locale. 396 * @param status error status 397 * @return a string enumeration over keyword values for the given key and the locale. 398 * @stable ICU 4.2 399 */ 400 U_STABLE UEnumeration* U_EXPORT2 401 ucurr_getKeywordValuesForLocale(const char* key, 402 const char* locale, 403 UBool commonlyUsed, 404 UErrorCode* status); 405 406 /** 407 * Returns the ISO 4217 numeric code for the currency. 408 * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or 409 * the currency is unknown, this function returns 0. 410 * 411 * @param currency null-terminated 3-letter ISO 4217 code 412 * @return The ISO 4217 numeric code of the currency 413 * @stable ICU 49 414 */ 415 U_STABLE int32_t U_EXPORT2 416 ucurr_getNumericCode(const UChar* currency); 417 418 #endif /* #if !UCONFIG_NO_FORMATTING */ 419 420 #endif 421