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