include/unicode/ucurr.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 **********************************************************************
0005 * Copyright (c) 2002-2016, International Business Machines
0006 * Corporation and others.  All Rights Reserved.
0007 **********************************************************************
0008 */
0009 #ifndef _UCURR_H_
0010 #define _UCURR_H_
0011
0012 #include "unicode/utypes.h"
0013 #include "unicode/uenum.h"
0014
0015 /**
0016  * \file
0017  * \brief C API: Encapsulates information about a currency.
0018  *
0019  * The ucurr API encapsulates information about a currency, as defined by
0020  * ISO 4217.  A currency is represented by a 3-character string
0021  * containing its ISO 4217 code.  This API can return various data
0022  * necessary the proper display of a currency:
0023  *
0024  * <ul><li>A display symbol, for a specific locale
0025  * <li>The number of fraction digits to display
0026  * <li>A rounding increment
0027  * </ul>
0028  *
0029  * The <tt>DecimalFormat</tt> class uses these data to display
0030  * currencies.
0031  * @author Alan Liu
0032  * @since ICU 2.2
0033  */
0034
0035 #if !UCONFIG_NO_FORMATTING
0036
0037 /**
0038  * Currency Usage used for Decimal Format
0039  * @stable ICU 54
0040  */
0041 enum UCurrencyUsage {
0042     /**
0043      * a setting to specify currency usage which determines currency digit
0044      * and rounding for standard usage, for example: "50.00 NT$"
0045      * used as DEFAULT value
0046      * @stable ICU 54
0047      */
0048     UCURR_USAGE_STANDARD=0,
0049     /**
0050      * a setting to specify currency usage which determines currency digit
0051      * and rounding for cash usage, for example: "50 NT$"
0052      * @stable ICU 54
0053      */
0054     UCURR_USAGE_CASH=1,
0055 #ifndef U_HIDE_DEPRECATED_API
0056     /**
0057      * One higher than the last enum UCurrencyUsage constant.
0058      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
0059      */
0060     UCURR_USAGE_COUNT=2
0061 #endif  // U_HIDE_DEPRECATED_API
0062 };
0063 /** Currency Usage used for Decimal Format */
0064 typedef enum UCurrencyUsage UCurrencyUsage;
0065
0066 /**
0067  * Finds a currency code for the given locale.
0068  * @param locale the locale for which to retrieve a currency code.
0069  *               Currency can be specified by the "currency" keyword
0070  *               in which case it overrides the default currency code
0071  * @param buff   fill in buffer. Can be NULL for preflighting.
0072  * @param buffCapacity capacity of the fill in buffer. Can be 0 for
0073  *               preflighting. If it is non-zero, the buff parameter
0074  *               must not be NULL.
0075  * @param ec error code
0076  * @return length of the currency string. It should always be 3. If 0,
0077  *                currency couldn't be found or the input values are
0078  *                invalid.
0079  * @stable ICU 2.8
0080  */
0081 U_CAPI int32_t U_EXPORT2
0082 ucurr_forLocale(const char* locale,
0083                 UChar* buff,
0084                 int32_t buffCapacity,
0085                 UErrorCode* ec);
0086
0087 /**
0088  * Selector constants for ucurr_getName().
0089  *
0090  * @see ucurr_getName
0091  * @stable ICU 2.6
0092  */
0093 typedef enum UCurrNameStyle {
0094     /**
0095      * Selector for ucurr_getName indicating a symbolic name for a
0096      * currency, such as "$" for USD.
0097      * @stable ICU 2.6
0098      */
0099     UCURR_SYMBOL_NAME,
0100
0101     /**
0102      * Selector for ucurr_getName indicating the long name for a
0103      * currency, such as "US Dollar" for USD.
0104      * @stable ICU 2.6
0105      */
0106     UCURR_LONG_NAME,
0107
0108     /**
0109      * Selector for getName() indicating the narrow currency symbol.
0110      * The narrow currency symbol is similar to the regular currency
0111      * symbol, but it always takes the shortest form: for example,
0112      * "$" instead of "US$" for USD in en-CA.
0113      *
0114      * @stable ICU 61
0115      */
0116     UCURR_NARROW_SYMBOL_NAME,
0117
0118     /**
0119      * Selector for getName() indicating the formal currency symbol.
0120      * The formal currency symbol is similar to the regular currency
0121      * symbol, but it always takes the form used in formal settings
0122      * such as banking; for example, "NT$" instead of "$" for TWD in zh-TW.
0123      *
0124      * @stable ICU 68
0125      */
0126     UCURR_FORMAL_SYMBOL_NAME,
0127
0128     /**
0129      * Selector for getName() indicating the variant currency symbol.
0130      * The variant symbol for a currency is an alternative symbol
0131      * that is not necessarily as widely used as the regular symbol.
0132      *
0133      * @stable ICU 68
0134      */
0135     UCURR_VARIANT_SYMBOL_NAME
0136
0137 } UCurrNameStyle;
0138
0139 #if !UCONFIG_NO_SERVICE
0140 /**
0141  * @stable ICU 2.6
0142  */
0143 typedef const void* UCurrRegistryKey;
0144
0145 /**
0146  * Register an (existing) ISO 4217 currency code for the given locale.
0147  * Only the country code and the two variants EURO and PRE_EURO are
0148  * recognized.
0149  * @param isoCode the three-letter ISO 4217 currency code
0150  * @param locale  the locale for which to register this currency code
0151  * @param status the in/out status code
0152  * @return a registry key that can be used to unregister this currency code, or NULL
0153  * if there was an error.
0154  * @stable ICU 2.6
0155  */
0156 U_CAPI UCurrRegistryKey U_EXPORT2
0157 ucurr_register(const UChar* isoCode,
0158                    const char* locale,
0159                    UErrorCode* status);
0160 /**
0161  * Unregister the previously-registered currency definitions using the
0162  * URegistryKey returned from ucurr_register.  Key becomes invalid after
0163  * a successful call and should not be used again.  Any currency
0164  * that might have been hidden by the original ucurr_register call is
0165  * restored.
0166  * @param key the registry key returned by a previous call to ucurr_register
0167  * @param status the in/out status code, no special meanings are assigned
0168  * @return true if the currency for this key was successfully unregistered
0169  * @stable ICU 2.6
0170  */
0171 U_CAPI UBool U_EXPORT2
0172 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status);
0173 #endif /* UCONFIG_NO_SERVICE */
0174
0175 /**
0176  * Returns the display name for the given currency in the
0177  * given locale.  For example, the display name for the USD
0178  * currency object in the en_US locale is "$".
0179  * @param currency null-terminated 3-letter ISO 4217 code
0180  * @param locale locale in which to display currency
0181  * @param nameStyle selector for which kind of name to return
0182  * @param isChoiceFormat always set to false, or can be NULL;
0183  *     display names are static strings;
0184  *     since ICU 4.4, ChoiceFormat patterns are no longer supported
0185  * @param len fill-in parameter to receive length of result
0186  * @param ec error code
0187  * @return pointer to display string of 'len' UChars.  If the resource
0188  * data contains no entry for 'currency', then 'currency' itself is
0189  * returned.
0190  * @stable ICU 2.6
0191  */
0192 U_CAPI const UChar* U_EXPORT2
0193 ucurr_getName(const UChar* currency,
0194               const char* locale,
0195               UCurrNameStyle nameStyle,
0196               UBool* isChoiceFormat,
0197               int32_t* len,
0198               UErrorCode* ec);
0199
0200 /**
0201  * Returns the plural name for the given currency in the
0202  * given locale.  For example, the plural name for the USD
0203  * currency object in the en_US locale is "US dollar" or "US dollars".
0204  * @param currency null-terminated 3-letter ISO 4217 code
0205  * @param locale locale in which to display currency
0206  * @param isChoiceFormat always set to false, or can be NULL;
0207  *     display names are static strings;
0208  *     since ICU 4.4, ChoiceFormat patterns are no longer supported
0209  * @param pluralCount plural count
0210  * @param len fill-in parameter to receive length of result
0211  * @param ec error code
0212  * @return pointer to display string of 'len' UChars.  If the resource
0213  * data contains no entry for 'currency', then 'currency' itself is
0214  * returned.
0215  * @stable ICU 4.2
0216  */
0217 U_CAPI const UChar* U_EXPORT2
0218 ucurr_getPluralName(const UChar* currency,
0219                     const char* locale,
0220                     UBool* isChoiceFormat,
0221                     const char* pluralCount,
0222                     int32_t* len,
0223                     UErrorCode* ec);
0224
0225 /**
0226  * Returns the number of the number of fraction digits that should
0227  * be displayed for the given currency.
0228  * This is equivalent to ucurr_getDefaultFractionDigitsForUsage(currency,UCURR_USAGE_STANDARD,ec);
0229  *
0230  * Important: The number of fraction digits for a given currency is NOT
0231  * guaranteed to be constant across versions of ICU or CLDR. For example,
0232  * do NOT use this value as a mechanism for deciding the magnitude used
0233  * to store currency values in a database. You should use this value for
0234  * display purposes only.
0235  *
0236  * @param currency null-terminated 3-letter ISO 4217 code
0237  * @param ec input-output error code
0238  * @return a non-negative number of fraction digits to be
0239  * displayed, or 0 if there is an error
0240  * @stable ICU 3.0
0241  */
0242 U_CAPI int32_t U_EXPORT2
0243 ucurr_getDefaultFractionDigits(const UChar* currency,
0244                                UErrorCode* ec);
0245
0246 /**
0247  * Returns the number of the number of fraction digits that should
0248  * be displayed for the given currency with usage.
0249  *
0250  * Important: The number of fraction digits for a given currency is NOT
0251  * guaranteed to be constant across versions of ICU or CLDR. For example,
0252  * do NOT use this value as a mechanism for deciding the magnitude used
0253  * to store currency values in a database. You should use this value for
0254  * display purposes only.
0255  *
0256  * @param currency null-terminated 3-letter ISO 4217 code
0257  * @param usage enum usage for the currency
0258  * @param ec input-output error code
0259  * @return a non-negative number of fraction digits to be
0260  * displayed, or 0 if there is an error
0261  * @stable ICU 54
0262  */
0263 U_CAPI int32_t U_EXPORT2
0264 ucurr_getDefaultFractionDigitsForUsage(const UChar* currency,
0265                                        const UCurrencyUsage usage,
0266                                        UErrorCode* ec);
0267
0268 /**
0269  * Returns the rounding increment for the given currency, or 0.0 if no
0270  * rounding is done by the currency.
0271  * This is equivalent to ucurr_getRoundingIncrementForUsage(currency,UCURR_USAGE_STANDARD,ec);
0272  * @param currency null-terminated 3-letter ISO 4217 code
0273  * @param ec input-output error code
0274  * @return the non-negative rounding increment, or 0.0 if none,
0275  * or 0.0 if there is an error
0276  * @stable ICU 3.0
0277  */
0278 U_CAPI double U_EXPORT2
0279 ucurr_getRoundingIncrement(const UChar* currency,
0280                            UErrorCode* ec);
0281
0282 /**
0283  * Returns the rounding increment for the given currency, or 0.0 if no
0284  * rounding is done by the currency given usage.
0285  * @param currency null-terminated 3-letter ISO 4217 code
0286  * @param usage enum usage for the currency
0287  * @param ec input-output error code
0288  * @return the non-negative rounding increment, or 0.0 if none,
0289  * or 0.0 if there is an error
0290  * @stable ICU 54
0291  */
0292 U_CAPI double U_EXPORT2
0293 ucurr_getRoundingIncrementForUsage(const UChar* currency,
0294                                    const UCurrencyUsage usage,
0295                                    UErrorCode* ec);
0296
0297 /**
0298  * Selector constants for ucurr_openCurrencies().
0299  *
0300  * @see ucurr_openCurrencies
0301  * @stable ICU 3.2
0302  */
0303 typedef enum UCurrCurrencyType {
0304     /**
0305      * Select all ISO-4217 currency codes.
0306      * @stable ICU 3.2
0307      */
0308     UCURR_ALL = INT32_MAX,
0309     /**
0310      * Select only ISO-4217 commonly used currency codes.
0311      * These currencies can be found in common use, and they usually have
0312      * bank notes or coins associated with the currency code.
0313      * This does not include fund codes, precious metals and other
0314      * various ISO-4217 codes limited to special financial products.
0315      * @stable ICU 3.2
0316      */
0317     UCURR_COMMON = 1,
0318     /**
0319      * Select ISO-4217 uncommon currency codes.
0320      * These codes respresent fund codes, precious metals and other
0321      * various ISO-4217 codes limited to special financial products.
0322      * A fund code is a monetary resource associated with a currency.
0323      * @stable ICU 3.2
0324      */
0325     UCURR_UNCOMMON = 2,
0326     /**
0327      * Select only deprecated ISO-4217 codes.
0328      * These codes are no longer in general public use.
0329      * @stable ICU 3.2
0330      */
0331     UCURR_DEPRECATED = 4,
0332     /**
0333      * Select only non-deprecated ISO-4217 codes.
0334      * These codes are in general public use.
0335      * @stable ICU 3.2
0336      */
0337     UCURR_NON_DEPRECATED = 8
0338 } UCurrCurrencyType;
0339
0340 /**
0341  * Provides a UEnumeration object for listing ISO-4217 codes.
0342  * @param currType You can use one of several UCurrCurrencyType values for this
0343  *      variable. You can also | (or) them together to get a specific list of
0344  *      currencies. Most people will want to use the (UCURR_COMMON|UCURR_NON_DEPRECATED) value to
0345  *      get a list of current currencies.
0346  * @param pErrorCode Error code
0347  * @stable ICU 3.2
0348  */
0349 U_CAPI UEnumeration * U_EXPORT2
0350 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode);
0351
0352 /**
0353   * Queries if the given ISO 4217 3-letter code is available on the specified date range.
0354   *
0355   * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to'
0356   *
0357   * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time.
0358   * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date.
0359   *
0360   * @param isoCode
0361   *            The ISO 4217 3-letter code.
0362   *
0363   * @param from
0364   *            The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability
0365   *            of the currency any date before 'to'
0366   *
0367   * @param to
0368   *            The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of
0369   *            the currency any date after 'from'
0370   *
0371   * @param errorCode
0372   *            ICU error code
0373    *
0374   * @return true if the given ISO 4217 3-letter code is supported on the specified date range.
0375   *
0376   * @stable ICU 4.8
0377   */
0378 U_CAPI UBool U_EXPORT2
0379 ucurr_isAvailable(const UChar* isoCode,
0380              UDate from,
0381              UDate to,
0382              UErrorCode* errorCode);
0383
0384 /**
0385  * Finds the number of valid currency codes for the
0386  * given locale and date.
0387  * @param locale the locale for which to retrieve the
0388  *               currency count.
0389  * @param date   the date for which to retrieve the
0390  *               currency count for the given locale.
0391  * @param ec     error code
0392  * @return       the number of currency codes for the
0393  *               given locale and date.  If 0, currency
0394  *               codes couldn't be found for the input
0395  *               values are invalid.
0396  * @stable ICU 4.0
0397  */
0398 U_CAPI int32_t U_EXPORT2
0399 ucurr_countCurrencies(const char* locale,
0400                  UDate date,
0401                  UErrorCode* ec);
0402
0403 /**
0404  * Finds a currency code for the given locale and date
0405  * @param locale the locale for which to retrieve a currency code.
0406  *               Currency can be specified by the "currency" keyword
0407  *               in which case it overrides the default currency code
0408  * @param date   the date for which to retrieve a currency code for
0409  *               the given locale.
0410  * @param index  the index within the available list of currency codes
0411  *               for the given locale on the given date.
0412  * @param buff   fill in buffer. Can be NULL for preflighting.
0413  * @param buffCapacity capacity of the fill in buffer. Can be 0 for
0414  *               preflighting. If it is non-zero, the buff parameter
0415  *               must not be NULL.
0416  * @param ec     error code
0417  * @return       length of the currency string. It should always be 3.
0418  *               If 0, currency couldn't be found or the input values are
0419  *               invalid.
0420  * @stable ICU 4.0
0421  */
0422 U_CAPI int32_t U_EXPORT2
0423 ucurr_forLocaleAndDate(const char* locale,
0424                 UDate date,
0425                 int32_t index,
0426                 UChar* buff,
0427                 int32_t buffCapacity,
0428                 UErrorCode* ec);
0429
0430 /**
0431  * Given a key and a locale, returns an array of string values in a preferred
0432  * order that would make a difference. These are all and only those values where
0433  * the open (creation) of the service with the locale formed from the input locale
0434  * plus input keyword and that value has different behavior than creation with the
0435  * input locale alone.
0436  * @param key           one of the keys supported by this service.  For now, only
0437  *                      "currency" is supported.
0438  * @param locale        the locale
0439  * @param commonlyUsed  if set to true it will return only commonly used values
0440  *                      with the given locale in preferred order.  Otherwise,
0441  *                      it will return all the available values for the locale.
0442  * @param status error status
0443  * @return a string enumeration over keyword values for the given key and the locale.
0444  * @stable ICU 4.2
0445  */
0446 U_CAPI UEnumeration* U_EXPORT2
0447 ucurr_getKeywordValuesForLocale(const char* key,
0448                                 const char* locale,
0449                                 UBool commonlyUsed,
0450                                 UErrorCode* status);
0451
0452 /**
0453  * Returns the ISO 4217 numeric code for the currency.
0454  * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
0455  * the currency is unknown, this function returns 0.
0456  *
0457  * @param currency null-terminated 3-letter ISO 4217 code
0458  * @return The ISO 4217 numeric code of the currency
0459  * @stable ICU 49
0460  */
0461 U_CAPI int32_t U_EXPORT2
0462 ucurr_getNumericCode(const UChar* currency);
0463
0464 #endif /* #if !UCONFIG_NO_FORMATTING */
0465
0466 #endif