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