1/*
2**********************************************************************
3* Copyright (c) 2002-2013, 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 */
52U_STABLE int32_t U_EXPORT2
53ucurr_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 */
64typedef 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 */
84typedef 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 */
97U_STABLE UCurrRegistryKey U_EXPORT2
98ucurr_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 */
112U_STABLE UBool U_EXPORT2
113ucurr_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 */
133U_STABLE const UChar* U_EXPORT2
134ucurr_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 */
157U_STABLE const UChar* U_EXPORT2
158ucurr_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 */
174U_STABLE int32_t U_EXPORT2
175ucurr_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 */
187U_STABLE double U_EXPORT2
188ucurr_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 */
197typedef 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 */
243U_STABLE UEnumeration * U_EXPORT2
244ucurr_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  */
272U_STABLE UBool U_EXPORT2
273ucurr_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 */
292U_STABLE int32_t U_EXPORT2
293ucurr_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 */
316U_STABLE int32_t U_EXPORT2
317ucurr_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 */
340U_STABLE UEnumeration* U_EXPORT2
341ucurr_getKeywordValuesForLocale(const char* key,
342                                const char* locale,
343                                UBool commonlyUsed,
344                                UErrorCode* status);
345
346/**
347 * Returns the ISO 4217 numeric code for the currency.
348 * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
349 * the currency is unknown, this function returns 0.
350 *
351 * @param currency null-terminated 3-letter ISO 4217 code
352 * @return The ISO 4217 numeric code of the currency
353 * @stable ICU 49
354 */
355U_STABLE int32_t U_EXPORT2
356ucurr_getNumericCode(const UChar* currency);
357
358#endif /* #if !UCONFIG_NO_FORMATTING */
359
360#endif
361