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