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