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