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