1 /*
2 **********************************************************************
3 * Copyright (c) 2002-2015, 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  * Currency Usage used for Decimal Format
22  * @stable ICU 54
23  */
24 enum UCurrencyUsage {
25     /**
26      * a setting to specify currency usage which determines currency digit
27      * and rounding for standard usage, for example: "50.00 NT$"
28      * used as DEFAULT value
29      * @stable ICU 54
30      */
31     UCURR_USAGE_STANDARD=0,
32     /**
33      * a setting to specify currency usage which determines currency digit
34      * and rounding for cash usage, for example: "50 NT$"
35      * @stable ICU 54
36      */
37     UCURR_USAGE_CASH=1,
38     /**
39      * One higher than the last enum UCurrencyUsage constant.
40      * @stable ICU 54
41      */
42     UCURR_USAGE_COUNT=2
43 };
44 typedef enum UCurrencyUsage UCurrencyUsage;
45 
46 /**
47  * The ucurr API encapsulates information about a currency, as defined by
48  * ISO 4217.  A currency is represented by a 3-character string
49  * containing its ISO 4217 code.  This API can return various data
50  * necessary the proper display of a currency:
51  *
52  * <ul><li>A display symbol, for a specific locale
53  * <li>The number of fraction digits to display
54  * <li>A rounding increment
55  * </ul>
56  *
57  * The <tt>DecimalFormat</tt> class uses these data to display
58  * currencies.
59  * @author Alan Liu
60  * @since ICU 2.2
61  */
62 
63 /**
64  * Finds a currency code for the given locale.
65  * @param locale the locale for which to retrieve a currency code.
66  *               Currency can be specified by the "currency" keyword
67  *               in which case it overrides the default currency code
68  * @param buff   fill in buffer. Can be NULL for preflighting.
69  * @param buffCapacity capacity of the fill in buffer. Can be 0 for
70  *               preflighting. If it is non-zero, the buff parameter
71  *               must not be NULL.
72  * @param ec error code
73  * @return length of the currency string. It should always be 3. If 0,
74  *                currency couldn't be found or the input values are
75  *                invalid.
76  * @stable ICU 2.8
77  */
78 U_STABLE int32_t U_EXPORT2
79 ucurr_forLocale(const char* locale,
80                 UChar* buff,
81                 int32_t buffCapacity,
82                 UErrorCode* ec);
83 
84 /**
85  * Selector constants for ucurr_getName().
86  *
87  * @see ucurr_getName
88  * @stable ICU 2.6
89  */
90 typedef enum UCurrNameStyle {
91     /**
92      * Selector for ucurr_getName indicating a symbolic name for a
93      * currency, such as "$" for USD.
94      * @stable ICU 2.6
95      */
96     UCURR_SYMBOL_NAME,
97 
98     /**
99      * Selector for ucurr_getName indicating the long name for a
100      * currency, such as "US Dollar" for USD.
101      * @stable ICU 2.6
102      */
103     UCURR_LONG_NAME
104 } UCurrNameStyle;
105 
106 #if !UCONFIG_NO_SERVICE
107 /**
108  * @stable ICU 2.6
109  */
110 typedef const void* UCurrRegistryKey;
111 
112 /**
113  * Register an (existing) ISO 4217 currency code for the given locale.
114  * Only the country code and the two variants EURO and PRE_EURO are
115  * recognized.
116  * @param isoCode the three-letter ISO 4217 currency code
117  * @param locale  the locale for which to register this currency code
118  * @param status the in/out status code
119  * @return a registry key that can be used to unregister this currency code, or NULL
120  * if there was an error.
121  * @stable ICU 2.6
122  */
123 U_STABLE UCurrRegistryKey U_EXPORT2
124 ucurr_register(const UChar* isoCode,
125                    const char* locale,
126                    UErrorCode* status);
127 /**
128  * Unregister the previously-registered currency definitions using the
129  * URegistryKey returned from ucurr_register.  Key becomes invalid after
130  * a successful call and should not be used again.  Any currency
131  * that might have been hidden by the original ucurr_register call is
132  * restored.
133  * @param key the registry key returned by a previous call to ucurr_register
134  * @param status the in/out status code, no special meanings are assigned
135  * @return TRUE if the currency for this key was successfully unregistered
136  * @stable ICU 2.6
137  */
138 U_STABLE UBool U_EXPORT2
139 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status);
140 #endif /* UCONFIG_NO_SERVICE */
141 
142 /**
143  * Returns the display name for the given currency in the
144  * given locale.  For example, the display name for the USD
145  * currency object in the en_US locale is "$".
146  * @param currency null-terminated 3-letter ISO 4217 code
147  * @param locale locale in which to display currency
148  * @param nameStyle selector for which kind of name to return
149  * @param isChoiceFormat fill-in set to TRUE if the returned value
150  * is a ChoiceFormat pattern; otherwise it is a static string
151  * @param len fill-in parameter to receive length of result
152  * @param ec error code
153  * @return pointer to display string of 'len' UChars.  If the resource
154  * data contains no entry for 'currency', then 'currency' itself is
155  * returned.  If *isChoiceFormat is TRUE, then the result is a
156  * ChoiceFormat pattern.  Otherwise it is a static string.
157  * @stable ICU 2.6
158  */
159 U_STABLE const UChar* U_EXPORT2
160 ucurr_getName(const UChar* currency,
161               const char* locale,
162               UCurrNameStyle nameStyle,
163               UBool* isChoiceFormat,
164               int32_t* len,
165               UErrorCode* ec);
166 
167 /**
168  * Returns the plural name for the given currency in the
169  * given locale.  For example, the plural name for the USD
170  * currency object in the en_US locale is "US dollar" or "US dollars".
171  * @param currency null-terminated 3-letter ISO 4217 code
172  * @param locale locale in which to display currency
173  * @param isChoiceFormat fill-in set to TRUE if the returned value
174  * is a ChoiceFormat pattern; otherwise it is a static string
175  * @param pluralCount plural count
176  * @param len fill-in parameter to receive length of result
177  * @param ec error code
178  * @return pointer to display string of 'len' UChars.  If the resource
179  * data contains no entry for 'currency', then 'currency' itself is
180  * returned.
181  * @stable ICU 4.2
182  */
183 U_STABLE const UChar* U_EXPORT2
184 ucurr_getPluralName(const UChar* currency,
185                     const char* locale,
186                     UBool* isChoiceFormat,
187                     const char* pluralCount,
188                     int32_t* len,
189                     UErrorCode* ec);
190 
191 /**
192  * Returns the number of the number of fraction digits that should
193  * be displayed for the given currency.
194  * This is equivalent to ucurr_getDefaultFractionDigitsForUsage(currency,UCURR_USAGE_STANDARD,ec);
195  * @param currency null-terminated 3-letter ISO 4217 code
196  * @param ec input-output error code
197  * @return a non-negative number of fraction digits to be
198  * displayed, or 0 if there is an error
199  * @stable ICU 3.0
200  */
201 U_STABLE int32_t U_EXPORT2
202 ucurr_getDefaultFractionDigits(const UChar* currency,
203                                UErrorCode* ec);
204 
205 /**
206  * Returns the number of the number of fraction digits that should
207  * be displayed for the given currency with usage.
208  * @param currency null-terminated 3-letter ISO 4217 code
209  * @param usage enum usage for the currency
210  * @param ec input-output error code
211  * @return a non-negative number of fraction digits to be
212  * displayed, or 0 if there is an error
213  * @stable ICU 54
214  */
215 U_STABLE int32_t U_EXPORT2
216 ucurr_getDefaultFractionDigitsForUsage(const UChar* currency,
217                                        const UCurrencyUsage usage,
218                                        UErrorCode* ec);
219 
220 /**
221  * Returns the rounding increment for the given currency, or 0.0 if no
222  * rounding is done by the currency.
223  * This is equivalent to ucurr_getRoundingIncrementForUsage(currency,UCURR_USAGE_STANDARD,ec);
224  * @param currency null-terminated 3-letter ISO 4217 code
225  * @param ec input-output error code
226  * @return the non-negative rounding increment, or 0.0 if none,
227  * or 0.0 if there is an error
228  * @stable ICU 3.0
229  */
230 U_STABLE double U_EXPORT2
231 ucurr_getRoundingIncrement(const UChar* currency,
232                            UErrorCode* ec);
233 
234 /**
235  * Returns the rounding increment for the given currency, or 0.0 if no
236  * rounding is done by the currency given usage.
237  * @param currency null-terminated 3-letter ISO 4217 code
238  * @param usage enum usage for the currency
239  * @param ec input-output error code
240  * @return the non-negative rounding increment, or 0.0 if none,
241  * or 0.0 if there is an error
242  * @stable ICU 54
243  */
244 U_STABLE double U_EXPORT2
245 ucurr_getRoundingIncrementForUsage(const UChar* currency,
246                                    const UCurrencyUsage usage,
247                                    UErrorCode* ec);
248 
249 /**
250  * Selector constants for ucurr_openCurrencies().
251  *
252  * @see ucurr_openCurrencies
253  * @stable ICU 3.2
254  */
255 typedef enum UCurrCurrencyType {
256     /**
257      * Select all ISO-4217 currency codes.
258      * @stable ICU 3.2
259      */
260     UCURR_ALL = INT32_MAX,
261     /**
262      * Select only ISO-4217 commonly used currency codes.
263      * These currencies can be found in common use, and they usually have
264      * bank notes or coins associated with the currency code.
265      * This does not include fund codes, precious metals and other
266      * various ISO-4217 codes limited to special financial products.
267      * @stable ICU 3.2
268      */
269     UCURR_COMMON = 1,
270     /**
271      * Select ISO-4217 uncommon currency codes.
272      * These codes respresent fund codes, precious metals and other
273      * various ISO-4217 codes limited to special financial products.
274      * A fund code is a monetary resource associated with a currency.
275      * @stable ICU 3.2
276      */
277     UCURR_UNCOMMON = 2,
278     /**
279      * Select only deprecated ISO-4217 codes.
280      * These codes are no longer in general public use.
281      * @stable ICU 3.2
282      */
283     UCURR_DEPRECATED = 4,
284     /**
285      * Select only non-deprecated ISO-4217 codes.
286      * These codes are in general public use.
287      * @stable ICU 3.2
288      */
289     UCURR_NON_DEPRECATED = 8
290 } UCurrCurrencyType;
291 
292 /**
293  * Provides a UEnumeration object for listing ISO-4217 codes.
294  * @param currType You can use one of several UCurrCurrencyType values for this
295  *      variable. You can also | (or) them together to get a specific list of
296  *      currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to
297  *      get a list of current currencies.
298  * @param pErrorCode Error code
299  * @stable ICU 3.2
300  */
301 U_STABLE UEnumeration * U_EXPORT2
302 ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode);
303 
304 /**
305   * Queries if the given ISO 4217 3-letter code is available on the specified date range.
306   *
307   * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to'
308   *
309   * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time.
310   * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date.
311   *
312   * @param isoCode
313   *            The ISO 4217 3-letter code.
314   *
315   * @param from
316   *            The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability
317   *            of the currency any date before 'to'
318   *
319   * @param to
320   *            The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of
321   *            the currency any date after 'from'
322   *
323   * @param errorCode
324   *            ICU error code
325    *
326   * @return TRUE if the given ISO 4217 3-letter code is supported on the specified date range.
327   *
328   * @stable ICU 4.8
329   */
330 U_STABLE UBool U_EXPORT2
331 ucurr_isAvailable(const UChar* isoCode,
332              UDate from,
333              UDate to,
334              UErrorCode* errorCode);
335 
336 /**
337  * Finds the number of valid currency codes for the
338  * given locale and date.
339  * @param locale the locale for which to retrieve the
340  *               currency count.
341  * @param date   the date for which to retrieve the
342  *               currency count for the given locale.
343  * @param ec     error code
344  * @return       the number of currency codes for the
345  *               given locale and date.  If 0, currency
346  *               codes couldn't be found for the input
347  *               values are invalid.
348  * @stable ICU 4.0
349  */
350 U_STABLE int32_t U_EXPORT2
351 ucurr_countCurrencies(const char* locale,
352                  UDate date,
353                  UErrorCode* ec);
354 
355 /**
356  * Finds a currency code for the given locale and date
357  * @param locale the locale for which to retrieve a currency code.
358  *               Currency can be specified by the "currency" keyword
359  *               in which case it overrides the default currency code
360  * @param date   the date for which to retrieve a currency code for
361  *               the given locale.
362  * @param index  the index within the available list of currency codes
363  *               for the given locale on the given date.
364  * @param buff   fill in buffer. Can be NULL for preflighting.
365  * @param buffCapacity capacity of the fill in buffer. Can be 0 for
366  *               preflighting. If it is non-zero, the buff parameter
367  *               must not be NULL.
368  * @param ec     error code
369  * @return       length of the currency string. It should always be 3.
370  *               If 0, currency couldn't be found or the input values are
371  *               invalid.
372  * @stable ICU 4.0
373  */
374 U_STABLE int32_t U_EXPORT2
375 ucurr_forLocaleAndDate(const char* locale,
376                 UDate date,
377                 int32_t index,
378                 UChar* buff,
379                 int32_t buffCapacity,
380                 UErrorCode* ec);
381 
382 /**
383  * Given a key and a locale, returns an array of string values in a preferred
384  * order that would make a difference. These are all and only those values where
385  * the open (creation) of the service with the locale formed from the input locale
386  * plus input keyword and that value has different behavior than creation with the
387  * input locale alone.
388  * @param key           one of the keys supported by this service.  For now, only
389  *                      "currency" is supported.
390  * @param locale        the locale
391  * @param commonlyUsed  if set to true it will return only commonly used values
392  *                      with the given locale in preferred order.  Otherwise,
393  *                      it will return all the available values for the locale.
394  * @param status error status
395  * @return a string enumeration over keyword values for the given key and the locale.
396  * @stable ICU 4.2
397  */
398 U_STABLE UEnumeration* U_EXPORT2
399 ucurr_getKeywordValuesForLocale(const char* key,
400                                 const char* locale,
401                                 UBool commonlyUsed,
402                                 UErrorCode* status);
403 
404 /**
405  * Returns the ISO 4217 numeric code for the currency.
406  * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
407  * the currency is unknown, this function returns 0.
408  *
409  * @param currency null-terminated 3-letter ISO 4217 code
410  * @return The ISO 4217 numeric code of the currency
411  * @stable ICU 49
412  */
413 U_STABLE int32_t U_EXPORT2
414 ucurr_getNumericCode(const UChar* currency);
415 
416 #endif /* #if !UCONFIG_NO_FORMATTING */
417 
418 #endif
419