1 /* 2 ********************************************************************** 3 * Copyright (c) 2002-2006, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ********************************************************************** 6 */ 7 #ifndef _UCURR_H_ 8 #define _UCURR_H_ 9 10 #include "unicode/utypes.h" 11 #include "unicode/uenum.h" 12 13 /** 14 * \file 15 * \brief C API: Encapsulates information about a currency. 16 */ 17 18 #if !UCONFIG_NO_FORMATTING 19 20 /** 21 * The ucurr API encapsulates information about a currency, as defined by 22 * ISO 4217. A currency is represented by a 3-character string 23 * containing its ISO 4217 code. This API can return various data 24 * necessary the proper display of a currency: 25 * 26 * <ul><li>A display symbol, for a specific locale 27 * <li>The number of fraction digits to display 28 * <li>A rounding increment 29 * </ul> 30 * 31 * The <tt>DecimalFormat</tt> class uses these data to display 32 * currencies. 33 * @author Alan Liu 34 * @since ICU 2.2 35 */ 36 37 /** 38 * Finds a currency code for the given locale. 39 * @param locale the locale for which to retrieve a currency code. 40 * Currency can be specified by the "currency" keyword 41 * in which case it overrides the default currency code 42 * @param buff fill in buffer. Can be NULL for preflighting. 43 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 44 * preflighting. If it is non-zero, the buff parameter 45 * must not be NULL. 46 * @param ec error code 47 * @return length of the currency string. It should always be 3. If 0, 48 * currency couldn't be found or the input values are 49 * invalid. 50 * @stable ICU 2.8 51 */ 52 U_STABLE int32_t U_EXPORT2 53 ucurr_forLocale(const char* locale, 54 UChar* buff, 55 int32_t buffCapacity, 56 UErrorCode* ec); 57 58 /** 59 * Selector constants for ucurr_getName(). 60 * 61 * @see ucurr_getName 62 * @stable ICU 2.6 63 */ 64 typedef enum UCurrNameStyle { 65 /** 66 * Selector for ucurr_getName indicating a symbolic name for a 67 * currency, such as "$" for USD. 68 * @stable ICU 2.6 69 */ 70 UCURR_SYMBOL_NAME, 71 72 /** 73 * Selector for ucurr_getName indicating the long name for a 74 * currency, such as "US Dollar" for USD. 75 * @stable ICU 2.6 76 */ 77 UCURR_LONG_NAME 78 } UCurrNameStyle; 79 80 #if !UCONFIG_NO_SERVICE 81 /** 82 * @stable ICU 2.6 83 */ 84 typedef const void* UCurrRegistryKey; 85 86 /** 87 * Register an (existing) ISO 4217 currency code for the given locale. 88 * Only the country code and the two variants EURO and PRE_EURO are 89 * recognized. 90 * @param isoCode the three-letter ISO 4217 currency code 91 * @param locale the locale for which to register this currency code 92 * @param status the in/out status code 93 * @return a registry key that can be used to unregister this currency code, or NULL 94 * if there was an error. 95 * @stable ICU 2.6 96 */ 97 U_STABLE UCurrRegistryKey U_EXPORT2 98 ucurr_register(const UChar* isoCode, 99 const char* locale, 100 UErrorCode* status); 101 /** 102 * Unregister the previously-registered currency definitions using the 103 * URegistryKey returned from ucurr_register. Key becomes invalid after 104 * a successful call and should not be used again. Any currency 105 * that might have been hidden by the original ucurr_register call is 106 * restored. 107 * @param key the registry key returned by a previous call to ucurr_register 108 * @param status the in/out status code, no special meanings are assigned 109 * @return TRUE if the currency for this key was successfully unregistered 110 * @stable ICU 2.6 111 */ 112 U_STABLE UBool U_EXPORT2 113 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status); 114 #endif /* UCONFIG_NO_SERVICE */ 115 116 /** 117 * Returns the display name for the given currency in the 118 * given locale. For example, the display name for the USD 119 * currency object in the en_US locale is "$". 120 * @param currency null-terminated 3-letter ISO 4217 code 121 * @param locale locale in which to display currency 122 * @param nameStyle selector for which kind of name to return 123 * @param isChoiceFormat fill-in set to TRUE if the returned value 124 * is a ChoiceFormat pattern; otherwise it is a static string 125 * @param len fill-in parameter to receive length of result 126 * @param ec error code 127 * @return pointer to display string of 'len' UChars. If the resource 128 * data contains no entry for 'currency', then 'currency' itself is 129 * returned. If *isChoiceFormat is TRUE, then the result is a 130 * ChoiceFormat pattern. Otherwise it is a static string. 131 * @stable ICU 2.6 132 */ 133 U_STABLE const UChar* U_EXPORT2 134 ucurr_getName(const UChar* currency, 135 const char* locale, 136 UCurrNameStyle nameStyle, 137 UBool* isChoiceFormat, 138 int32_t* len, 139 UErrorCode* ec); 140 141 /** 142 * Returns the number of the number of fraction digits that should 143 * be displayed for the given currency. 144 * @param currency null-terminated 3-letter ISO 4217 code 145 * @param ec input-output error code 146 * @return a non-negative number of fraction digits to be 147 * displayed, or 0 if there is an error 148 * @stable ICU 3.0 149 */ 150 U_STABLE int32_t U_EXPORT2 151 ucurr_getDefaultFractionDigits(const UChar* currency, 152 UErrorCode* ec); 153 154 /** 155 * Returns the rounding increment for the given currency, or 0.0 if no 156 * rounding is done by the currency. 157 * @param currency null-terminated 3-letter ISO 4217 code 158 * @param ec input-output error code 159 * @return the non-negative rounding increment, or 0.0 if none, 160 * or 0.0 if there is an error 161 * @stable ICU 3.0 162 */ 163 U_STABLE double U_EXPORT2 164 ucurr_getRoundingIncrement(const UChar* currency, 165 UErrorCode* ec); 166 167 /** 168 * Selector constants for ucurr_openCurrencies(). 169 * 170 * @see ucurr_openCurrencies 171 * @stable ICU 3.2 172 */ 173 typedef enum UCurrCurrencyType { 174 /** 175 * Select all ISO-4217 currency codes. 176 * @stable ICU 3.2 177 */ 178 UCURR_ALL = INT32_MAX, 179 /** 180 * Select only ISO-4217 commonly used currency codes. 181 * These currencies can be found in common use, and they usually have 182 * bank notes or coins associated with the currency code. 183 * This does not include fund codes, precious metals and other 184 * various ISO-4217 codes limited to special financial products. 185 * @stable ICU 3.2 186 */ 187 UCURR_COMMON = 1, 188 /** 189 * Select ISO-4217 uncommon currency codes. 190 * These codes respresent fund codes, precious metals and other 191 * various ISO-4217 codes limited to special financial products. 192 * A fund code is a monetary resource associated with a currency. 193 * @stable ICU 3.2 194 */ 195 UCURR_UNCOMMON = 2, 196 /** 197 * Select only deprecated ISO-4217 codes. 198 * These codes are no longer in general public use. 199 * @stable ICU 3.2 200 */ 201 UCURR_DEPRECATED = 4, 202 /** 203 * Select only non-deprecated ISO-4217 codes. 204 * These codes are in general public use. 205 * @stable ICU 3.2 206 */ 207 UCURR_NON_DEPRECATED = 8 208 } UCurrCurrencyType; 209 210 /** 211 * Provides a UEnumeration object for listing ISO-4217 codes. 212 * @param currType You can use one of several UCurrCurrencyType values for this 213 * variable. You can also | (or) them together to get a specific list of 214 * currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to 215 * get a list of current currencies. 216 * @param pErrorCode Error code 217 * @stable ICU 3.2 218 */ 219 U_STABLE UEnumeration * U_EXPORT2 220 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode); 221 222 223 #endif /* #if !UCONFIG_NO_FORMATTING */ 224 225 #endif 226