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