1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/ucurr.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,360 @@
1.4 +/*
1.5 +**********************************************************************
1.6 +* Copyright (c) 2002-2013, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +**********************************************************************
1.9 +*/
1.10 +#ifndef _UCURR_H_
1.11 +#define _UCURR_H_
1.12 +
1.13 +#include "unicode/utypes.h"
1.14 +#include "unicode/uenum.h"
1.15 +
1.16 +/**
1.17 + * \file
1.18 + * \brief C API: Encapsulates information about a currency.
1.19 + */
1.20 +
1.21 +#if !UCONFIG_NO_FORMATTING
1.22 +
1.23 +/**
1.24 + * The ucurr API encapsulates information about a currency, as defined by
1.25 + * ISO 4217. A currency is represented by a 3-character string
1.26 + * containing its ISO 4217 code. This API can return various data
1.27 + * necessary the proper display of a currency:
1.28 + *
1.29 + * <ul><li>A display symbol, for a specific locale
1.30 + * <li>The number of fraction digits to display
1.31 + * <li>A rounding increment
1.32 + * </ul>
1.33 + *
1.34 + * The <tt>DecimalFormat</tt> class uses these data to display
1.35 + * currencies.
1.36 + * @author Alan Liu
1.37 + * @since ICU 2.2
1.38 + */
1.39 +
1.40 +/**
1.41 + * Finds a currency code for the given locale.
1.42 + * @param locale the locale for which to retrieve a currency code.
1.43 + * Currency can be specified by the "currency" keyword
1.44 + * in which case it overrides the default currency code
1.45 + * @param buff fill in buffer. Can be NULL for preflighting.
1.46 + * @param buffCapacity capacity of the fill in buffer. Can be 0 for
1.47 + * preflighting. If it is non-zero, the buff parameter
1.48 + * must not be NULL.
1.49 + * @param ec error code
1.50 + * @return length of the currency string. It should always be 3. If 0,
1.51 + * currency couldn't be found or the input values are
1.52 + * invalid.
1.53 + * @stable ICU 2.8
1.54 + */
1.55 +U_STABLE int32_t U_EXPORT2
1.56 +ucurr_forLocale(const char* locale,
1.57 + UChar* buff,
1.58 + int32_t buffCapacity,
1.59 + UErrorCode* ec);
1.60 +
1.61 +/**
1.62 + * Selector constants for ucurr_getName().
1.63 + *
1.64 + * @see ucurr_getName
1.65 + * @stable ICU 2.6
1.66 + */
1.67 +typedef enum UCurrNameStyle {
1.68 + /**
1.69 + * Selector for ucurr_getName indicating a symbolic name for a
1.70 + * currency, such as "$" for USD.
1.71 + * @stable ICU 2.6
1.72 + */
1.73 + UCURR_SYMBOL_NAME,
1.74 +
1.75 + /**
1.76 + * Selector for ucurr_getName indicating the long name for a
1.77 + * currency, such as "US Dollar" for USD.
1.78 + * @stable ICU 2.6
1.79 + */
1.80 + UCURR_LONG_NAME
1.81 +} UCurrNameStyle;
1.82 +
1.83 +#if !UCONFIG_NO_SERVICE
1.84 +/**
1.85 + * @stable ICU 2.6
1.86 + */
1.87 +typedef const void* UCurrRegistryKey;
1.88 +
1.89 +/**
1.90 + * Register an (existing) ISO 4217 currency code for the given locale.
1.91 + * Only the country code and the two variants EURO and PRE_EURO are
1.92 + * recognized.
1.93 + * @param isoCode the three-letter ISO 4217 currency code
1.94 + * @param locale the locale for which to register this currency code
1.95 + * @param status the in/out status code
1.96 + * @return a registry key that can be used to unregister this currency code, or NULL
1.97 + * if there was an error.
1.98 + * @stable ICU 2.6
1.99 + */
1.100 +U_STABLE UCurrRegistryKey U_EXPORT2
1.101 +ucurr_register(const UChar* isoCode,
1.102 + const char* locale,
1.103 + UErrorCode* status);
1.104 +/**
1.105 + * Unregister the previously-registered currency definitions using the
1.106 + * URegistryKey returned from ucurr_register. Key becomes invalid after
1.107 + * a successful call and should not be used again. Any currency
1.108 + * that might have been hidden by the original ucurr_register call is
1.109 + * restored.
1.110 + * @param key the registry key returned by a previous call to ucurr_register
1.111 + * @param status the in/out status code, no special meanings are assigned
1.112 + * @return TRUE if the currency for this key was successfully unregistered
1.113 + * @stable ICU 2.6
1.114 + */
1.115 +U_STABLE UBool U_EXPORT2
1.116 +ucurr_unregister(UCurrRegistryKey key, UErrorCode* status);
1.117 +#endif /* UCONFIG_NO_SERVICE */
1.118 +
1.119 +/**
1.120 + * Returns the display name for the given currency in the
1.121 + * given locale. For example, the display name for the USD
1.122 + * currency object in the en_US locale is "$".
1.123 + * @param currency null-terminated 3-letter ISO 4217 code
1.124 + * @param locale locale in which to display currency
1.125 + * @param nameStyle selector for which kind of name to return
1.126 + * @param isChoiceFormat fill-in set to TRUE if the returned value
1.127 + * is a ChoiceFormat pattern; otherwise it is a static string
1.128 + * @param len fill-in parameter to receive length of result
1.129 + * @param ec error code
1.130 + * @return pointer to display string of 'len' UChars. If the resource
1.131 + * data contains no entry for 'currency', then 'currency' itself is
1.132 + * returned. If *isChoiceFormat is TRUE, then the result is a
1.133 + * ChoiceFormat pattern. Otherwise it is a static string.
1.134 + * @stable ICU 2.6
1.135 + */
1.136 +U_STABLE const UChar* U_EXPORT2
1.137 +ucurr_getName(const UChar* currency,
1.138 + const char* locale,
1.139 + UCurrNameStyle nameStyle,
1.140 + UBool* isChoiceFormat,
1.141 + int32_t* len,
1.142 + UErrorCode* ec);
1.143 +
1.144 +/**
1.145 + * Returns the plural name for the given currency in the
1.146 + * given locale. For example, the plural name for the USD
1.147 + * currency object in the en_US locale is "US dollar" or "US dollars".
1.148 + * @param currency null-terminated 3-letter ISO 4217 code
1.149 + * @param locale locale in which to display currency
1.150 + * @param isChoiceFormat fill-in set to TRUE if the returned value
1.151 + * is a ChoiceFormat pattern; otherwise it is a static string
1.152 + * @param pluralCount plural count
1.153 + * @param len fill-in parameter to receive length of result
1.154 + * @param ec error code
1.155 + * @return pointer to display string of 'len' UChars. If the resource
1.156 + * data contains no entry for 'currency', then 'currency' itself is
1.157 + * returned.
1.158 + * @stable ICU 4.2
1.159 + */
1.160 +U_STABLE const UChar* U_EXPORT2
1.161 +ucurr_getPluralName(const UChar* currency,
1.162 + const char* locale,
1.163 + UBool* isChoiceFormat,
1.164 + const char* pluralCount,
1.165 + int32_t* len,
1.166 + UErrorCode* ec);
1.167 +
1.168 +/**
1.169 + * Returns the number of the number of fraction digits that should
1.170 + * be displayed for the given currency.
1.171 + * @param currency null-terminated 3-letter ISO 4217 code
1.172 + * @param ec input-output error code
1.173 + * @return a non-negative number of fraction digits to be
1.174 + * displayed, or 0 if there is an error
1.175 + * @stable ICU 3.0
1.176 + */
1.177 +U_STABLE int32_t U_EXPORT2
1.178 +ucurr_getDefaultFractionDigits(const UChar* currency,
1.179 + UErrorCode* ec);
1.180 +
1.181 +/**
1.182 + * Returns the rounding increment for the given currency, or 0.0 if no
1.183 + * rounding is done by the currency.
1.184 + * @param currency null-terminated 3-letter ISO 4217 code
1.185 + * @param ec input-output error code
1.186 + * @return the non-negative rounding increment, or 0.0 if none,
1.187 + * or 0.0 if there is an error
1.188 + * @stable ICU 3.0
1.189 + */
1.190 +U_STABLE double U_EXPORT2
1.191 +ucurr_getRoundingIncrement(const UChar* currency,
1.192 + UErrorCode* ec);
1.193 +
1.194 +/**
1.195 + * Selector constants for ucurr_openCurrencies().
1.196 + *
1.197 + * @see ucurr_openCurrencies
1.198 + * @stable ICU 3.2
1.199 + */
1.200 +typedef enum UCurrCurrencyType {
1.201 + /**
1.202 + * Select all ISO-4217 currency codes.
1.203 + * @stable ICU 3.2
1.204 + */
1.205 + UCURR_ALL = INT32_MAX,
1.206 + /**
1.207 + * Select only ISO-4217 commonly used currency codes.
1.208 + * These currencies can be found in common use, and they usually have
1.209 + * bank notes or coins associated with the currency code.
1.210 + * This does not include fund codes, precious metals and other
1.211 + * various ISO-4217 codes limited to special financial products.
1.212 + * @stable ICU 3.2
1.213 + */
1.214 + UCURR_COMMON = 1,
1.215 + /**
1.216 + * Select ISO-4217 uncommon currency codes.
1.217 + * These codes respresent fund codes, precious metals and other
1.218 + * various ISO-4217 codes limited to special financial products.
1.219 + * A fund code is a monetary resource associated with a currency.
1.220 + * @stable ICU 3.2
1.221 + */
1.222 + UCURR_UNCOMMON = 2,
1.223 + /**
1.224 + * Select only deprecated ISO-4217 codes.
1.225 + * These codes are no longer in general public use.
1.226 + * @stable ICU 3.2
1.227 + */
1.228 + UCURR_DEPRECATED = 4,
1.229 + /**
1.230 + * Select only non-deprecated ISO-4217 codes.
1.231 + * These codes are in general public use.
1.232 + * @stable ICU 3.2
1.233 + */
1.234 + UCURR_NON_DEPRECATED = 8
1.235 +} UCurrCurrencyType;
1.236 +
1.237 +/**
1.238 + * Provides a UEnumeration object for listing ISO-4217 codes.
1.239 + * @param currType You can use one of several UCurrCurrencyType values for this
1.240 + * variable. You can also | (or) them together to get a specific list of
1.241 + * currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to
1.242 + * get a list of current currencies.
1.243 + * @param pErrorCode Error code
1.244 + * @stable ICU 3.2
1.245 + */
1.246 +U_STABLE UEnumeration * U_EXPORT2
1.247 +ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode);
1.248 +
1.249 +/**
1.250 + * Queries if the given ISO 4217 3-letter code is available on the specified date range.
1.251 + *
1.252 + * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to'
1.253 + *
1.254 + * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time.
1.255 + * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date.
1.256 + *
1.257 + * @param isoCode
1.258 + * The ISO 4217 3-letter code.
1.259 + *
1.260 + * @param from
1.261 + * The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability
1.262 + * of the currency any date before 'to'
1.263 + *
1.264 + * @param to
1.265 + * The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of
1.266 + * the currency any date after 'from'
1.267 + *
1.268 + * @param errorCode
1.269 + * ICU error code
1.270 + *
1.271 + * @return TRUE if the given ISO 4217 3-letter code is supported on the specified date range.
1.272 + *
1.273 + * @stable ICU 4.8
1.274 + */
1.275 +U_STABLE UBool U_EXPORT2
1.276 +ucurr_isAvailable(const UChar* isoCode,
1.277 + UDate from,
1.278 + UDate to,
1.279 + UErrorCode* errorCode);
1.280 +
1.281 +/**
1.282 + * Finds the number of valid currency codes for the
1.283 + * given locale and date.
1.284 + * @param locale the locale for which to retrieve the
1.285 + * currency count.
1.286 + * @param date the date for which to retrieve the
1.287 + * currency count for the given locale.
1.288 + * @param ec error code
1.289 + * @return the number of currency codes for the
1.290 + * given locale and date. If 0, currency
1.291 + * codes couldn't be found for the input
1.292 + * values are invalid.
1.293 + * @stable ICU 4.0
1.294 + */
1.295 +U_STABLE int32_t U_EXPORT2
1.296 +ucurr_countCurrencies(const char* locale,
1.297 + UDate date,
1.298 + UErrorCode* ec);
1.299 +
1.300 +/**
1.301 + * Finds a currency code for the given locale and date
1.302 + * @param locale the locale for which to retrieve a currency code.
1.303 + * Currency can be specified by the "currency" keyword
1.304 + * in which case it overrides the default currency code
1.305 + * @param date the date for which to retrieve a currency code for
1.306 + * the given locale.
1.307 + * @param index the index within the available list of currency codes
1.308 + * for the given locale on the given date.
1.309 + * @param buff fill in buffer. Can be NULL for preflighting.
1.310 + * @param buffCapacity capacity of the fill in buffer. Can be 0 for
1.311 + * preflighting. If it is non-zero, the buff parameter
1.312 + * must not be NULL.
1.313 + * @param ec error code
1.314 + * @return length of the currency string. It should always be 3.
1.315 + * If 0, currency couldn't be found or the input values are
1.316 + * invalid.
1.317 + * @stable ICU 4.0
1.318 + */
1.319 +U_STABLE int32_t U_EXPORT2
1.320 +ucurr_forLocaleAndDate(const char* locale,
1.321 + UDate date,
1.322 + int32_t index,
1.323 + UChar* buff,
1.324 + int32_t buffCapacity,
1.325 + UErrorCode* ec);
1.326 +
1.327 +/**
1.328 + * Given a key and a locale, returns an array of string values in a preferred
1.329 + * order that would make a difference. These are all and only those values where
1.330 + * the open (creation) of the service with the locale formed from the input locale
1.331 + * plus input keyword and that value has different behavior than creation with the
1.332 + * input locale alone.
1.333 + * @param key one of the keys supported by this service. For now, only
1.334 + * "currency" is supported.
1.335 + * @param locale the locale
1.336 + * @param commonlyUsed if set to true it will return only commonly used values
1.337 + * with the given locale in preferred order. Otherwise,
1.338 + * it will return all the available values for the locale.
1.339 + * @param status error status
1.340 + * @return a string enumeration over keyword values for the given key and the locale.
1.341 + * @stable ICU 4.2
1.342 + */
1.343 +U_STABLE UEnumeration* U_EXPORT2
1.344 +ucurr_getKeywordValuesForLocale(const char* key,
1.345 + const char* locale,
1.346 + UBool commonlyUsed,
1.347 + UErrorCode* status);
1.348 +
1.349 +/**
1.350 + * Returns the ISO 4217 numeric code for the currency.
1.351 + * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
1.352 + * the currency is unknown, this function returns 0.
1.353 + *
1.354 + * @param currency null-terminated 3-letter ISO 4217 code
1.355 + * @return The ISO 4217 numeric code of the currency
1.356 + * @stable ICU 49
1.357 + */
1.358 +U_STABLE int32_t U_EXPORT2
1.359 +ucurr_getNumericCode(const UChar* currency);
1.360 +
1.361 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.362 +
1.363 +#endif
