1 /* 2 ********************************************************************** 3 * Copyright (c) 2002-2012, 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 plural name for the given currency in the 143 * given locale. For example, the plural name for the USD 144 * currency object in the en_US locale is "US dollar" or "US dollars". 145 * @param currency null-terminated 3-letter ISO 4217 code 146 * @param locale locale in which to display currency 147 * @param isChoiceFormat fill-in set to TRUE if the returned value 148 * is a ChoiceFormat pattern; otherwise it is a static string 149 * @param pluralCount plural count 150 * @param len fill-in parameter to receive length of result 151 * @param ec error code 152 * @return pointer to display string of 'len' UChars. If the resource 153 * data contains no entry for 'currency', then 'currency' itself is 154 * returned. 155 * @stable ICU 4.2 156 */ 157 U_STABLE const UChar* U_EXPORT2 158 ucurr_getPluralName(const UChar* currency, 159 const char* locale, 160 UBool* isChoiceFormat, 161 const char* pluralCount, 162 int32_t* len, 163 UErrorCode* ec); 164 165 /** 166 * Returns the number of the number of fraction digits that should 167 * be displayed for the given currency. 168 * @param currency null-terminated 3-letter ISO 4217 code 169 * @param ec input-output error code 170 * @return a non-negative number of fraction digits to be 171 * displayed, or 0 if there is an error 172 * @stable ICU 3.0 173 */ 174 U_STABLE int32_t U_EXPORT2 175 ucurr_getDefaultFractionDigits(const UChar* currency, 176 UErrorCode* ec); 177 178 /** 179 * Returns the rounding increment for the given currency, or 0.0 if no 180 * rounding is done by the currency. 181 * @param currency null-terminated 3-letter ISO 4217 code 182 * @param ec input-output error code 183 * @return the non-negative rounding increment, or 0.0 if none, 184 * or 0.0 if there is an error 185 * @stable ICU 3.0 186 */ 187 U_STABLE double U_EXPORT2 188 ucurr_getRoundingIncrement(const UChar* currency, 189 UErrorCode* ec); 190 191 /** 192 * Selector constants for ucurr_openCurrencies(). 193 * 194 * @see ucurr_openCurrencies 195 * @stable ICU 3.2 196 */ 197 typedef enum UCurrCurrencyType { 198 /** 199 * Select all ISO-4217 currency codes. 200 * @stable ICU 3.2 201 */ 202 UCURR_ALL = INT32_MAX, 203 /** 204 * Select only ISO-4217 commonly used currency codes. 205 * These currencies can be found in common use, and they usually have 206 * bank notes or coins associated with the currency code. 207 * This does not include fund codes, precious metals and other 208 * various ISO-4217 codes limited to special financial products. 209 * @stable ICU 3.2 210 */ 211 UCURR_COMMON = 1, 212 /** 213 * Select ISO-4217 uncommon currency codes. 214 * These codes respresent fund codes, precious metals and other 215 * various ISO-4217 codes limited to special financial products. 216 * A fund code is a monetary resource associated with a currency. 217 * @stable ICU 3.2 218 */ 219 UCURR_UNCOMMON = 2, 220 /** 221 * Select only deprecated ISO-4217 codes. 222 * These codes are no longer in general public use. 223 * @stable ICU 3.2 224 */ 225 UCURR_DEPRECATED = 4, 226 /** 227 * Select only non-deprecated ISO-4217 codes. 228 * These codes are in general public use. 229 * @stable ICU 3.2 230 */ 231 UCURR_NON_DEPRECATED = 8 232 } UCurrCurrencyType; 233 234 /** 235 * Provides a UEnumeration object for listing ISO-4217 codes. 236 * @param currType You can use one of several UCurrCurrencyType values for this 237 * variable. You can also | (or) them together to get a specific list of 238 * currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to 239 * get a list of current currencies. 240 * @param pErrorCode Error code 241 * @stable ICU 3.2 242 */ 243 U_STABLE UEnumeration * U_EXPORT2 244 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode); 245 246 /** 247 * Queries if the given ISO 4217 3-letter code is available on the specified date range. 248 * 249 * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to' 250 * 251 * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time. 252 * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date. 253 * 254 * @param isoCode 255 * The ISO 4217 3-letter code. 256 * 257 * @param from 258 * The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability 259 * of the currency any date before 'to' 260 * 261 * @param to 262 * The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of 263 * the currency any date after 'from' 264 * 265 * @param errorCode 266 * ICU error code 267 * 268 * @return TRUE if the given ISO 4217 3-letter code is supported on the specified date range. 269 * 270 * @stable ICU 4.8 271 */ 272 U_STABLE UBool U_EXPORT2 273 ucurr_isAvailable(const UChar* isoCode, 274 UDate from, 275 UDate to, 276 UErrorCode* errorCode); 277 278 /** 279 * Finds the number of valid currency codes for the 280 * given locale and date. 281 * @param locale the locale for which to retrieve the 282 * currency count. 283 * @param date the date for which to retrieve the 284 * currency count for the given locale. 285 * @param ec error code 286 * @return the number of currency codes for the 287 * given locale and date. If 0, currency 288 * codes couldn't be found for the input 289 * values are invalid. 290 * @stable ICU 4.0 291 */ 292 U_STABLE int32_t U_EXPORT2 293 ucurr_countCurrencies(const char* locale, 294 UDate date, 295 UErrorCode* ec); 296 297 /** 298 * Finds a currency code for the given locale and date 299 * @param locale the locale for which to retrieve a currency code. 300 * Currency can be specified by the "currency" keyword 301 * in which case it overrides the default currency code 302 * @param date the date for which to retrieve a currency code for 303 * the given locale. 304 * @param index the index within the available list of currency codes 305 * for the given locale on the given date. 306 * @param buff fill in buffer. Can be NULL for preflighting. 307 * @param buffCapacity capacity of the fill in buffer. Can be 0 for 308 * preflighting. If it is non-zero, the buff parameter 309 * must not be NULL. 310 * @param ec error code 311 * @return length of the currency string. It should always be 3. 312 * If 0, currency couldn't be found or the input values are 313 * invalid. 314 * @stable ICU 4.0 315 */ 316 U_STABLE int32_t U_EXPORT2 317 ucurr_forLocaleAndDate(const char* locale, 318 UDate date, 319 int32_t index, 320 UChar* buff, 321 int32_t buffCapacity, 322 UErrorCode* ec); 323 324 /** 325 * Given a key and a locale, returns an array of string values in a preferred 326 * order that would make a difference. These are all and only those values where 327 * the open (creation) of the service with the locale formed from the input locale 328 * plus input keyword and that value has different behavior than creation with the 329 * input locale alone. 330 * @param key one of the keys supported by this service. For now, only 331 * "currency" is supported. 332 * @param locale the locale 333 * @param commonlyUsed if set to true it will return only commonly used values 334 * with the given locale in preferred order. Otherwise, 335 * it will return all the available values for the locale. 336 * @param status error status 337 * @return a string enumeration over keyword values for the given key and the locale. 338 * @stable ICU 4.2 339 */ 340 U_STABLE UEnumeration* U_EXPORT2 341 ucurr_getKeywordValuesForLocale(const char* key, 342 const char* locale, 343 UBool commonlyUsed, 344 UErrorCode* status); 345 346 #ifndef U_HIDE_DRAFT_API 347 /** 348 * Returns the ISO 4217 numeric code for the currency. 349 * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or 350 * the currency is unknown, this function returns 0. 351 * 352 * @param currency null-terminated 3-letter ISO 4217 code 353 * @return The ISO 4217 numeric code of the currency 354 * @draft ICU 49 355 */ 356 U_DRAFT int32_t U_EXPORT2 357 ucurr_getNumericCode(const UChar* currency); 358 #endif /* U_HIDE_DRAFT_API */ 359 360 #endif /* #if !UCONFIG_NO_FORMATTING */ 361 362 #endif 363
