icuSources/i18n/unicode/ucurr.h

   1 /*
   2 **********************************************************************
   3 * Copyright (c) 2002-2013, 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 /**
 347  * Returns the ISO 4217 numeric code for the currency.
 348  * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
 349  * the currency is unknown, this function returns 0.
 350  *
 351  * @param currency null-terminated 3-letter ISO 4217 code
 352  * @return The ISO 4217 numeric code of the currency
 353  * @stable ICU 49
 354  */
 355 U_STABLE int32_t U_EXPORT2
 356 ucurr_getNumericCode(const UChar* currency);
 357
 358 #endif /* #if !UCONFIG_NO_FORMATTING */
 359
 360 #endif