icuSources/common/unicode/ucurr.h

   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