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

Note: If the ISO 4217 numeric code is not assigned for the currency or jpayne@69: * the currency is unknown, this function returns 0. jpayne@69: * jpayne@69: * @param currency null-terminated 3-letter ISO 4217 code jpayne@69: * @return The ISO 4217 numeric code of the currency jpayne@69: * @stable ICU 49 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ucurr_getNumericCode(const UChar* currency); jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */ jpayne@69: jpayne@69: #endif