/* ********************************************************************** * Copyright (c) 2002-2013, 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. */ #if !UCONFIG_NO_FORMATTING /** * 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 */ /** * 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_STABLE 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 } 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_STABLE 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_STABLE 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 fill-in set to TRUE if the returned value * is a ChoiceFormat pattern; otherwise it is a static string * @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. If *isChoiceFormat is TRUE, then the result is a * ChoiceFormat pattern. Otherwise it is a static string. * @stable ICU 2.6 */ U_STABLE 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 fill-in set to TRUE if the returned value * is a ChoiceFormat pattern; otherwise it is a static string * @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_STABLE 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. * @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_STABLE int32_t U_EXPORT2 ucurr_getDefaultFractionDigits(const UChar* currency, UErrorCode* ec); /** * Returns the rounding increment for the given currency, or 0.0 if no * rounding is done by the currency. * @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_STABLE double U_EXPORT2 ucurr_getRoundingIncrement(const UChar* currency, 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_CURRENCY|UCURR_NON_DEPRECATED) value to * get a list of current currencies. * @param pErrorCode Error code * @stable ICU 3.2 */ U_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE 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_STABLE int32_t U_EXPORT2 ucurr_getNumericCode(const UChar* currency); #endif /* #if !UCONFIG_NO_FORMATTING */ #endif