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 */
41enum 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};
63typedef 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 */
80U_STABLE int32_t U_EXPORT2
81ucurr_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 */
92typedef 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 */
112typedef 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 */
125U_STABLE UCurrRegistryKey U_EXPORT2
126ucurr_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 */
140U_STABLE UBool U_EXPORT2
141ucurr_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 */
161U_STABLE const UChar* U_EXPORT2
162ucurr_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 */
185U_STABLE const UChar* U_EXPORT2
186ucurr_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 */
203U_STABLE int32_t U_EXPORT2
204ucurr_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 */
217U_STABLE int32_t U_EXPORT2
218ucurr_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 */
232U_STABLE double U_EXPORT2
233ucurr_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 */
246U_STABLE double U_EXPORT2
247ucurr_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 */
257typedef 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 */
303U_STABLE UEnumeration * U_EXPORT2
304ucurr_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  */
332U_STABLE UBool U_EXPORT2
333ucurr_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 */
352U_STABLE int32_t U_EXPORT2
353ucurr_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 */
376U_STABLE int32_t U_EXPORT2
377ucurr_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 */
400U_STABLE UEnumeration* U_EXPORT2
401ucurr_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 */
415U_STABLE int32_t U_EXPORT2
416ucurr_getNumericCode(const UChar* currency);
417
418#endif /* #if !UCONFIG_NO_FORMATTING */
419
420#endif
421