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 /** Currency Usage used for Decimal Format */ 64 typedef enum UCurrencyUsage UCurrencyUsage; 65 66 /** 67 * Finds a currency code for the given locale. 68 * @param locale the locale for which to retrieve a currency code. 69 * Currency can be specified by the "currency" keyword 70 * in which case it overrides the default currency code 71 * @param buff fill in buffer. Can be NULL for preflighting. 72 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 73 * preflighting. If it is non-zero, the buff parameter 74 * must not be NULL. 75 * @param ec error code 76 * @return length of the currency string. It should always be 3. If 0, 77 * currency couldn't be found or the input values are 78 * invalid. 79 * @stable ICU 2.8 80 */ 81 U_STABLE int32_t U_EXPORT2 82 ucurr_forLocale(const char* locale, 83 UChar* buff, 84 int32_t buffCapacity, 85 UErrorCode* ec); 86 87 /** 88 * Selector constants for ucurr_getName(). 89 * 90 * @see ucurr_getName 91 * @stable ICU 2.6 92 */ 93 typedef enum UCurrNameStyle { 94 /** 95 * Selector for ucurr_getName indicating a symbolic name for a 96 * currency, such as "$" for USD. 97 * @stable ICU 2.6 98 */ 99 UCURR_SYMBOL_NAME, 100 101 /** 102 * Selector for ucurr_getName indicating the long name for a 103 * currency, such as "US Dollar" for USD. 104 * @stable ICU 2.6 105 */ 106 UCURR_LONG_NAME, 107 108 /** 109 * Selector for getName() indicating the narrow currency symbol. 110 * The narrow currency symbol is similar to the regular currency 111 * symbol, but it always takes the shortest form: for example, 112 * "$" instead of "US$" for USD in en-CA. 113 * 114 * @stable ICU 61 115 */ 116 UCURR_NARROW_SYMBOL_NAME 117 } UCurrNameStyle; 118 119 #if !UCONFIG_NO_SERVICE 120 /** 121 * @stable ICU 2.6 122 */ 123 typedef const void* UCurrRegistryKey; 124 125 /** 126 * Register an (existing) ISO 4217 currency code for the given locale. 127 * Only the country code and the two variants EURO and PRE_EURO are 128 * recognized. 129 * @param isoCode the three-letter ISO 4217 currency code 130 * @param locale the locale for which to register this currency code 131 * @param status the in/out status code 132 * @return a registry key that can be used to unregister this currency code, or NULL 133 * if there was an error. 134 * @stable ICU 2.6 135 */ 136 U_STABLE UCurrRegistryKey U_EXPORT2 137 ucurr_register(const UChar* isoCode, 138 const char* locale, 139 UErrorCode* status); 140 /** 141 * Unregister the previously-registered currency definitions using the 142 * URegistryKey returned from ucurr_register. Key becomes invalid after 143 * a successful call and should not be used again. Any currency 144 * that might have been hidden by the original ucurr_register call is 145 * restored. 146 * @param key the registry key returned by a previous call to ucurr_register 147 * @param status the in/out status code, no special meanings are assigned 148 * @return TRUE if the currency for this key was successfully unregistered 149 * @stable ICU 2.6 150 */ 151 U_STABLE UBool U_EXPORT2 152 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status); 153 #endif /* UCONFIG_NO_SERVICE */ 154 155 /** 156 * Returns the display name for the given currency in the 157 * given locale. For example, the display name for the USD 158 * currency object in the en_US locale is "$". 159 * @param currency null-terminated 3-letter ISO 4217 code 160 * @param locale locale in which to display currency 161 * @param nameStyle selector for which kind of name to return 162 * @param isChoiceFormat always set to FALSE, or can be NULL; 163 * display names are static strings; 164 * since ICU 4.4, ChoiceFormat patterns are no longer supported 165 * @param len fill-in parameter to receive length of result 166 * @param ec error code 167 * @return pointer to display string of 'len' UChars. If the resource 168 * data contains no entry for 'currency', then 'currency' itself is 169 * returned. 170 * @stable ICU 2.6 171 */ 172 U_STABLE const UChar* U_EXPORT2 173 ucurr_getName(const UChar* currency, 174 const char* locale, 175 UCurrNameStyle nameStyle, 176 UBool* isChoiceFormat, 177 int32_t* len, 178 UErrorCode* ec); 179 180 /** 181 * Returns the plural name for the given currency in the 182 * given locale. For example, the plural name for the USD 183 * currency object in the en_US locale is "US dollar" or "US dollars". 184 * @param currency null-terminated 3-letter ISO 4217 code 185 * @param locale locale in which to display currency 186 * @param isChoiceFormat always set to FALSE, or can be NULL; 187 * display names are static strings; 188 * since ICU 4.4, ChoiceFormat patterns are no longer supported 189 * @param pluralCount plural count 190 * @param len fill-in parameter to receive length of result 191 * @param ec error code 192 * @return pointer to display string of 'len' UChars. If the resource 193 * data contains no entry for 'currency', then 'currency' itself is 194 * returned. 195 * @stable ICU 4.2 196 */ 197 U_STABLE const UChar* U_EXPORT2 198 ucurr_getPluralName(const UChar* currency, 199 const char* locale, 200 UBool* isChoiceFormat, 201 const char* pluralCount, 202 int32_t* len, 203 UErrorCode* ec); 204 205 /** 206 * Returns the number of the number of fraction digits that should 207 * be displayed for the given currency. 208 * This is equivalent to ucurr_getDefaultFractionDigitsForUsage(currency,UCURR_USAGE_STANDARD,ec); 209 * 210 * Important: The number of fraction digits for a given currency is NOT 211 * guaranteed to be constant across versions of ICU or CLDR. For example, 212 * do NOT use this value as a mechanism for deciding the magnitude used 213 * to store currency values in a database. You should use this value for 214 * display purposes only. 215 * 216 * @param currency null-terminated 3-letter ISO 4217 code 217 * @param ec input-output error code 218 * @return a non-negative number of fraction digits to be 219 * displayed, or 0 if there is an error 220 * @stable ICU 3.0 221 */ 222 U_STABLE int32_t U_EXPORT2 223 ucurr_getDefaultFractionDigits(const UChar* currency, 224 UErrorCode* ec); 225 226 /** 227 * Returns the number of the number of fraction digits that should 228 * be displayed for the given currency with usage. 229 * 230 * Important: The number of fraction digits for a given currency is NOT 231 * guaranteed to be constant across versions of ICU or CLDR. For example, 232 * do NOT use this value as a mechanism for deciding the magnitude used 233 * to store currency values in a database. You should use this value for 234 * display purposes only. 235 * 236 * @param currency null-terminated 3-letter ISO 4217 code 237 * @param usage enum usage for the currency 238 * @param ec input-output error code 239 * @return a non-negative number of fraction digits to be 240 * displayed, or 0 if there is an error 241 * @stable ICU 54 242 */ 243 U_STABLE int32_t U_EXPORT2 244 ucurr_getDefaultFractionDigitsForUsage(const UChar* currency, 245 const UCurrencyUsage usage, 246 UErrorCode* ec); 247 248 /** 249 * Returns the rounding increment for the given currency, or 0.0 if no 250 * rounding is done by the currency. 251 * This is equivalent to ucurr_getRoundingIncrementForUsage(currency,UCURR_USAGE_STANDARD,ec); 252 * @param currency null-terminated 3-letter ISO 4217 code 253 * @param ec input-output error code 254 * @return the non-negative rounding increment, or 0.0 if none, 255 * or 0.0 if there is an error 256 * @stable ICU 3.0 257 */ 258 U_STABLE double U_EXPORT2 259 ucurr_getRoundingIncrement(const UChar* currency, 260 UErrorCode* ec); 261 262 /** 263 * Returns the rounding increment for the given currency, or 0.0 if no 264 * rounding is done by the currency given usage. 265 * @param currency null-terminated 3-letter ISO 4217 code 266 * @param usage enum usage for the currency 267 * @param ec input-output error code 268 * @return the non-negative rounding increment, or 0.0 if none, 269 * or 0.0 if there is an error 270 * @stable ICU 54 271 */ 272 U_STABLE double U_EXPORT2 273 ucurr_getRoundingIncrementForUsage(const UChar* currency, 274 const UCurrencyUsage usage, 275 UErrorCode* ec); 276 277 /** 278 * Selector constants for ucurr_openCurrencies(). 279 * 280 * @see ucurr_openCurrencies 281 * @stable ICU 3.2 282 */ 283 typedef enum UCurrCurrencyType { 284 /** 285 * Select all ISO-4217 currency codes. 286 * @stable ICU 3.2 287 */ 288 UCURR_ALL = INT32_MAX, 289 /** 290 * Select only ISO-4217 commonly used currency codes. 291 * These currencies can be found in common use, and they usually have 292 * bank notes or coins associated with the currency code. 293 * This does not include fund codes, precious metals and other 294 * various ISO-4217 codes limited to special financial products. 295 * @stable ICU 3.2 296 */ 297 UCURR_COMMON = 1, 298 /** 299 * Select ISO-4217 uncommon currency codes. 300 * These codes respresent fund codes, precious metals and other 301 * various ISO-4217 codes limited to special financial products. 302 * A fund code is a monetary resource associated with a currency. 303 * @stable ICU 3.2 304 */ 305 UCURR_UNCOMMON = 2, 306 /** 307 * Select only deprecated ISO-4217 codes. 308 * These codes are no longer in general public use. 309 * @stable ICU 3.2 310 */ 311 UCURR_DEPRECATED = 4, 312 /** 313 * Select only non-deprecated ISO-4217 codes. 314 * These codes are in general public use. 315 * @stable ICU 3.2 316 */ 317 UCURR_NON_DEPRECATED = 8 318 } UCurrCurrencyType; 319 320 /** 321 * Provides a UEnumeration object for listing ISO-4217 codes. 322 * @param currType You can use one of several UCurrCurrencyType values for this 323 * variable. You can also | (or) them together to get a specific list of 324 * currencies. Most people will want to use the (UCURR_COMMON|UCURR_NON_DEPRECATED) value to 325 * get a list of current currencies. 326 * @param pErrorCode Error code 327 * @stable ICU 3.2 328 */ 329 U_STABLE UEnumeration * U_EXPORT2 330 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode); 331 332 /** 333 * Queries if the given ISO 4217 3-letter code is available on the specified date range. 334 * 335 * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to' 336 * 337 * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time. 338 * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date. 339 * 340 * @param isoCode 341 * The ISO 4217 3-letter code. 342 * 343 * @param from 344 * The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability 345 * of the currency any date before 'to' 346 * 347 * @param to 348 * The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of 349 * the currency any date after 'from' 350 * 351 * @param errorCode 352 * ICU error code 353 * 354 * @return TRUE if the given ISO 4217 3-letter code is supported on the specified date range. 355 * 356 * @stable ICU 4.8 357 */ 358 U_STABLE UBool U_EXPORT2 359 ucurr_isAvailable(const UChar* isoCode, 360 UDate from, 361 UDate to, 362 UErrorCode* errorCode); 363 364 /** 365 * Finds the number of valid currency codes for the 366 * given locale and date. 367 * @param locale the locale for which to retrieve the 368 * currency count. 369 * @param date the date for which to retrieve the 370 * currency count for the given locale. 371 * @param ec error code 372 * @return the number of currency codes for the 373 * given locale and date. If 0, currency 374 * codes couldn't be found for the input 375 * values are invalid. 376 * @stable ICU 4.0 377 */ 378 U_STABLE int32_t U_EXPORT2 379 ucurr_countCurrencies(const char* locale, 380 UDate date, 381 UErrorCode* ec); 382 383 /** 384 * Finds a currency code for the given locale and date 385 * @param locale the locale for which to retrieve a currency code. 386 * Currency can be specified by the "currency" keyword 387 * in which case it overrides the default currency code 388 * @param date the date for which to retrieve a currency code for 389 * the given locale. 390 * @param index the index within the available list of currency codes 391 * for the given locale on the given date. 392 * @param buff fill in buffer. Can be NULL for preflighting. 393 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 394 * preflighting. If it is non-zero, the buff parameter 395 * must not be NULL. 396 * @param ec error code 397 * @return length of the currency string. It should always be 3. 398 * If 0, currency couldn't be found or the input values are 399 * invalid. 400 * @stable ICU 4.0 401 */ 402 U_STABLE int32_t U_EXPORT2 403 ucurr_forLocaleAndDate(const char* locale, 404 UDate date, 405 int32_t index, 406 UChar* buff, 407 int32_t buffCapacity, 408 UErrorCode* ec); 409 410 /** 411 * Given a key and a locale, returns an array of string values in a preferred 412 * order that would make a difference. These are all and only those values where 413 * the open (creation) of the service with the locale formed from the input locale 414 * plus input keyword and that value has different behavior than creation with the 415 * input locale alone. 416 * @param key one of the keys supported by this service. For now, only 417 * "currency" is supported. 418 * @param locale the locale 419 * @param commonlyUsed if set to true it will return only commonly used values 420 * with the given locale in preferred order. Otherwise, 421 * it will return all the available values for the locale. 422 * @param status error status 423 * @return a string enumeration over keyword values for the given key and the locale. 424 * @stable ICU 4.2 425 */ 426 U_STABLE UEnumeration* U_EXPORT2 427 ucurr_getKeywordValuesForLocale(const char* key, 428 const char* locale, 429 UBool commonlyUsed, 430 UErrorCode* status); 431 432 /** 433 * Returns the ISO 4217 numeric code for the currency. 434 * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or 435 * the currency is unknown, this function returns 0. 436 * 437 * @param currency null-terminated 3-letter ISO 4217 code 438 * @return The ISO 4217 numeric code of the currency 439 * @stable ICU 49 440 */ 441 U_STABLE int32_t U_EXPORT2 442 ucurr_getNumericCode(const UChar* currency); 443 444 #endif /* #if !UCONFIG_NO_FORMATTING */ 445 446 #endif 447