icuSources/common/unicode/ucurr.h

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