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

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