text: // © 2016 and later: Unicode, Inc. and others.
  // License & terms of use: http://www.unicode.org/copyright.html
  /*
  **********************************************************************
  * Copyright (c) 2002-2016, International Business Machines
  * Corporation and others.  All Rights Reserved.
  **********************************************************************
  */
  #ifndef _UCURR_H_
  #define _UCURR_H_
  
  #include "unicode/utypes.h"
  #include "unicode/uenum.h"
  
  /**
   * \file 
   * \brief C API: Encapsulates information about a currency.
   *
   * The ucurr API encapsulates information about a currency, as defined by
   * ISO 4217.  A currency is represented by a 3-character string
   * containing its ISO 4217 code.  This API can return various data
   * necessary the proper display of a currency:
   *
   * <ul><li>A display symbol, for a specific locale
   * <li>The number of fraction digits to display
   * <li>A rounding increment
   * </ul>
   *
   * The <tt>DecimalFormat</tt> class uses these data to display
   * currencies.
   * @author Alan Liu
   * @since ICU 2.2
   */
  
  #if !UCONFIG_NO_FORMATTING
  
  /**
   * Currency Usage used for Decimal Format
   * @stable ICU 54
   */
  enum UCurrencyUsage {
      /**
       * a setting to specify currency usage which determines currency digit
       * and rounding for standard usage, for example: "50.00 NT$"
       * used as DEFAULT value
       * @stable ICU 54
       */
      UCURR_USAGE_STANDARD=0,
      /**
       * a setting to specify currency usage which determines currency digit
       * and rounding for cash usage, for example: "50 NT$"
       * @stable ICU 54
       */
      UCURR_USAGE_CASH=1,
  #ifndef U_HIDE_DEPRECATED_API
      /**
       * One higher than the last enum UCurrencyUsage constant.
       * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
       */
      UCURR_USAGE_COUNT=2
  #endif  // U_HIDE_DEPRECATED_API
  };
  /** Currency Usage used for Decimal Format */
  typedef enum UCurrencyUsage UCurrencyUsage; 
  
  /**
   * Finds a currency code for the given locale.
   * @param locale the locale for which to retrieve a currency code. 
   *               Currency can be specified by the "currency" keyword
   *               in which case it overrides the default currency code
   * @param buff   fill in buffer. Can be NULL for preflighting.
   * @param buffCapacity capacity of the fill in buffer. Can be 0 for
   *               preflighting. If it is non-zero, the buff parameter
   *               must not be NULL.
   * @param ec error code
   * @return length of the currency string. It should always be 3. If 0,
   *                currency couldn't be found or the input values are 
   *                invalid. 
   * @stable ICU 2.8
   */
  U_CAPI int32_t U_EXPORT2
  ucurr_forLocale(const char* locale,
                  UChar* buff,
                  int32_t buffCapacity,
                  UErrorCode* ec);
  
  /**
   * Selector constants for ucurr_getName().
   *
   * @see ucurr_getName
   * @stable ICU 2.6
   */
  typedef enum UCurrNameStyle {
      /**
       * Selector for ucurr_getName indicating a symbolic name for a
       * currency, such as "$" for USD.
       * @stable ICU 2.6
       */
      UCURR_SYMBOL_NAME,
  
      /**
       * Selector for ucurr_getName indicating the long name for a
       * currency, such as "US Dollar" for USD.
       * @stable ICU 2.6
       */
      UCURR_LONG_NAME,
  
      /**
       * Selector for getName() indicating the narrow currency symbol.
       * The narrow currency symbol is similar to the regular currency
       * symbol, but it always takes the shortest form: for example,
       * "$" instead of "US$" for USD in en-CA.
       *
       * @stable ICU 61
       */
      UCURR_NARROW_SYMBOL_NAME,
  
  #ifndef U_HIDE_DRAFT_API
      /**
       * Selector for getName() indicating the formal currency symbol.
       * The formal currency symbol is similar to the regular currency
       * symbol, but it always takes the form used in formal settings
       * such as banking; for example, "NT$" instead of "$" for TWD in zh-TW.
       *
       * @draft ICU 68
       */
      UCURR_FORMAL_SYMBOL_NAME,
  
      /**
       * Selector for getName() indicating the variant currency symbol.
       * The variant symbol for a currency is an alternative symbol
       * that is not necessarily as widely used as the regular symbol.
       *
       * @draft ICU 68
       */
      UCURR_VARIANT_SYMBOL_NAME
  #endif  // U_HIDE_DRAFT_API
      
  } UCurrNameStyle;
  
  #if !UCONFIG_NO_SERVICE
  /**
   * @stable ICU 2.6
   */
  typedef const void* UCurrRegistryKey;
  
  /**
   * Register an (existing) ISO 4217 currency code for the given locale.
   * Only the country code and the two variants EURO and PRE_EURO are
   * recognized.
   * @param isoCode the three-letter ISO 4217 currency code
   * @param locale  the locale for which to register this currency code
   * @param status the in/out status code
   * @return a registry key that can be used to unregister this currency code, or NULL
   * if there was an error.
   * @stable ICU 2.6
   */
  U_CAPI UCurrRegistryKey U_EXPORT2
  ucurr_register(const UChar* isoCode, 
                     const char* locale,  
                     UErrorCode* status);
  /**
   * Unregister the previously-registered currency definitions using the
   * URegistryKey returned from ucurr_register.  Key becomes invalid after
   * a successful call and should not be used again.  Any currency 
   * that might have been hidden by the original ucurr_register call is 
   * restored.
   * @param key the registry key returned by a previous call to ucurr_register
   * @param status the in/out status code, no special meanings are assigned
   * @return true if the currency for this key was successfully unregistered
   * @stable ICU 2.6
   */
  U_CAPI UBool U_EXPORT2
  ucurr_unregister(UCurrRegistryKey key, UErrorCode* status);
  #endif /* UCONFIG_NO_SERVICE */
  
  /**
   * Returns the display name for the given currency in the
   * given locale.  For example, the display name for the USD
   * currency object in the en_US locale is "$".
   * @param currency null-terminated 3-letter ISO 4217 code
   * @param locale locale in which to display currency
   * @param nameStyle selector for which kind of name to return
   * @param isChoiceFormat always set to false, or can be NULL;
   *     display names are static strings;
   *     since ICU 4.4, ChoiceFormat patterns are no longer supported
   * @param len fill-in parameter to receive length of result
   * @param ec error code
   * @return pointer to display string of 'len' UChars.  If the resource
   * data contains no entry for 'currency', then 'currency' itself is
   * returned.
   * @stable ICU 2.6
   */
  U_CAPI const UChar* U_EXPORT2
  ucurr_getName(const UChar* currency,
                const char* locale,
                UCurrNameStyle nameStyle,
                UBool* isChoiceFormat,
                int32_t* len,
                UErrorCode* ec);
  
  /**
   * Returns the plural name for the given currency in the
   * given locale.  For example, the plural name for the USD
   * currency object in the en_US locale is "US dollar" or "US dollars".
   * @param currency null-terminated 3-letter ISO 4217 code
   * @param locale locale in which to display currency
   * @param isChoiceFormat always set to false, or can be NULL;
   *     display names are static strings;
   *     since ICU 4.4, ChoiceFormat patterns are no longer supported
   * @param pluralCount plural count
   * @param len fill-in parameter to receive length of result
   * @param ec error code
   * @return pointer to display string of 'len' UChars.  If the resource
   * data contains no entry for 'currency', then 'currency' itself is
   * returned.
   * @stable ICU 4.2
   */
  U_CAPI const UChar* U_EXPORT2
  ucurr_getPluralName(const UChar* currency,
                      const char* locale,
                      UBool* isChoiceFormat,
                      const char* pluralCount,
                      int32_t* len,
                      UErrorCode* ec);
  
  /**
   * Returns the number of the number of fraction digits that should
   * be displayed for the given currency.
   * This is equivalent to ucurr_getDefaultFractionDigitsForUsage(currency,UCURR_USAGE_STANDARD,ec);
   *
   * Important: The number of fraction digits for a given currency is NOT
   * guaranteed to be constant across versions of ICU or CLDR. For example,
   * do NOT use this value as a mechanism for deciding the magnitude used
   * to store currency values in a database. You should use this value for
   * display purposes only.
   *
   * @param currency null-terminated 3-letter ISO 4217 code
   * @param ec input-output error code
   * @return a non-negative number of fraction digits to be
   * displayed, or 0 if there is an error
   * @stable ICU 3.0
   */
  U_CAPI int32_t U_EXPORT2
  ucurr_getDefaultFractionDigits(const UChar* currency,
                                 UErrorCode* ec);
  
  /**
   * Returns the number of the number of fraction digits that should
   * be displayed for the given currency with usage.
   *
   * Important: The number of fraction digits for a given currency is NOT
   * guaranteed to be constant across versions of ICU or CLDR. For example,
   * do NOT use this value as a mechanism for deciding the magnitude used
   * to store currency values in a database. You should use this value for
   * display purposes only.
   *
   * @param currency null-terminated 3-letter ISO 4217 code
   * @param usage enum usage for the currency
   * @param ec input-output error code
   * @return a non-negative number of fraction digits to be
   * displayed, or 0 if there is an error
   * @stable ICU 54
   */
  U_CAPI int32_t U_EXPORT2
  ucurr_getDefaultFractionDigitsForUsage(const UChar* currency, 
                                         const UCurrencyUsage usage,
                                         UErrorCode* ec);
  
  /**
   * Returns the rounding increment for the given currency, or 0.0 if no
   * rounding is done by the currency.
   * This is equivalent to ucurr_getRoundingIncrementForUsage(currency,UCURR_USAGE_STANDARD,ec);
   * @param currency null-terminated 3-letter ISO 4217 code
   * @param ec input-output error code
   * @return the non-negative rounding increment, or 0.0 if none,
   * or 0.0 if there is an error
   * @stable ICU 3.0
   */
  U_CAPI double U_EXPORT2
  ucurr_getRoundingIncrement(const UChar* currency,
                             UErrorCode* ec);
  
  /**
   * Returns the rounding increment for the given currency, or 0.0 if no
   * rounding is done by the currency given usage.
   * @param currency null-terminated 3-letter ISO 4217 code
   * @param usage enum usage for the currency
   * @param ec input-output error code
   * @return the non-negative rounding increment, or 0.0 if none,
   * or 0.0 if there is an error
   * @stable ICU 54
   */
  U_CAPI double U_EXPORT2
  ucurr_getRoundingIncrementForUsage(const UChar* currency,
                                     const UCurrencyUsage usage,
                                     UErrorCode* ec);
  
  /**
   * Selector constants for ucurr_openCurrencies().
   *
   * @see ucurr_openCurrencies
   * @stable ICU 3.2
   */
  typedef enum UCurrCurrencyType {
      /**
       * Select all ISO-4217 currency codes.
       * @stable ICU 3.2
       */
      UCURR_ALL = INT32_MAX,
      /**
       * Select only ISO-4217 commonly used currency codes.
       * These currencies can be found in common use, and they usually have
       * bank notes or coins associated with the currency code.
       * This does not include fund codes, precious metals and other
       * various ISO-4217 codes limited to special financial products.
       * @stable ICU 3.2
       */
      UCURR_COMMON = 1,
      /**
       * Select ISO-4217 uncommon currency codes.
       * These codes respresent fund codes, precious metals and other
       * various ISO-4217 codes limited to special financial products.
       * A fund code is a monetary resource associated with a currency.
       * @stable ICU 3.2
       */
      UCURR_UNCOMMON = 2,
      /**
       * Select only deprecated ISO-4217 codes.
       * These codes are no longer in general public use.
       * @stable ICU 3.2
       */
      UCURR_DEPRECATED = 4,
      /**
       * Select only non-deprecated ISO-4217 codes.
       * These codes are in general public use.
       * @stable ICU 3.2
       */
      UCURR_NON_DEPRECATED = 8
  } UCurrCurrencyType;
  
  /**
   * Provides a UEnumeration object for listing ISO-4217 codes.
   * @param currType You can use one of several UCurrCurrencyType values for this
   *      variable. You can also | (or) them together to get a specific list of
   *      currencies. Most people will want to use the (UCURR_COMMON|UCURR_NON_DEPRECATED) value to
   *      get a list of current currencies.
   * @param pErrorCode Error code
   * @stable ICU 3.2
   */
  U_CAPI UEnumeration * U_EXPORT2
  ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode);
  
  /**
    * Queries if the given ISO 4217 3-letter code is available on the specified date range. 
    * 
    * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to' 
    * 
    * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time. 
    * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date.
    * 
    * @param isoCode 
    *            The ISO 4217 3-letter code. 
    * 
    * @param from 
    *            The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability 
    *            of the currency any date before 'to' 
    * 
    * @param to 
    *            The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of 
    *            the currency any date after 'from' 
    * 
    * @param errorCode 
    *            ICU error code 
     * 
    * @return true if the given ISO 4217 3-letter code is supported on the specified date range. 
    * 
    * @stable ICU 4.8 
    */ 
  U_CAPI UBool U_EXPORT2
  ucurr_isAvailable(const UChar* isoCode, 
               UDate from, 
               UDate to, 
               UErrorCode* errorCode);
  
  /** 
   * Finds the number of valid currency codes for the
   * given locale and date.
   * @param locale the locale for which to retrieve the
   *               currency count.
   * @param date   the date for which to retrieve the
   *               currency count for the given locale.
   * @param ec     error code
   * @return       the number of currency codes for the
   *               given locale and date.  If 0, currency
   *               codes couldn't be found for the input
   *               values are invalid.
   * @stable ICU 4.0
   */
  U_CAPI int32_t U_EXPORT2
  ucurr_countCurrencies(const char* locale, 
                   UDate date, 
                   UErrorCode* ec); 
  
  /** 
   * Finds a currency code for the given locale and date 
   * @param locale the locale for which to retrieve a currency code.  
   *               Currency can be specified by the "currency" keyword 
   *               in which case it overrides the default currency code 
   * @param date   the date for which to retrieve a currency code for 
   *               the given locale. 
   * @param index  the index within the available list of currency codes
   *               for the given locale on the given date.
   * @param buff   fill in buffer. Can be NULL for preflighting. 
   * @param buffCapacity capacity of the fill in buffer. Can be 0 for 
   *               preflighting. If it is non-zero, the buff parameter 
   *               must not be NULL. 
   * @param ec     error code 
   * @return       length of the currency string. It should always be 3. 
   *               If 0, currency couldn't be found or the input values are  
   *               invalid.  
   * @stable ICU 4.0 
   */ 
  U_CAPI int32_t U_EXPORT2 
  ucurr_forLocaleAndDate(const char* locale, 
                  UDate date, 
                  int32_t index,
                  UChar* buff, 
                  int32_t buffCapacity, 
                  UErrorCode* ec); 
  
  /**
   * Given a key and a locale, returns an array of string values in a preferred
   * order that would make a difference. These are all and only those values where
   * the open (creation) of the service with the locale formed from the input locale
   * plus input keyword and that value has different behavior than creation with the
   * input locale alone.
   * @param key           one of the keys supported by this service.  For now, only
   *                      "currency" is supported.
   * @param locale        the locale
   * @param commonlyUsed  if set to true it will return only commonly used values
   *                      with the given locale in preferred order.  Otherwise,
   *                      it will return all the available values for the locale.
   * @param status error status
   * @return a string enumeration over keyword values for the given key and the locale.
   * @stable ICU 4.2
   */
  U_CAPI UEnumeration* U_EXPORT2
  ucurr_getKeywordValuesForLocale(const char* key,
                                  const char* locale,
                                  UBool commonlyUsed,
                                  UErrorCode* status);
  
  /**
   * Returns the ISO 4217 numeric code for the currency.
   * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
   * the currency is unknown, this function returns 0.
   *
   * @param currency null-terminated 3-letter ISO 4217 code
   * @return The ISO 4217 numeric code of the currency
   * @stable ICU 49
   */
  U_CAPI int32_t U_EXPORT2
  ucurr_getNumericCode(const UChar* currency);
  
  #endif /* #if !UCONFIG_NO_FORMATTING */
  
  #endif
  