1/*
2**********************************************************************
3* Copyright (c) 2002-2014, 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 * @draft ICU 54
23 */
24enum UCurrencyUsage {
25#ifndef U_HIDE_DRAFT_API
26 /**
27 * a setting to specify currency usage which determines currency digit
28 * and rounding for standard usage, for example: "50.00 NT$"
29 * used as DEFAULT value
30 * @draft ICU 54
31 */
32 UCURR_USAGE_STANDARD=0,
33 /**
34 * a setting to specify currency usage which determines currency digit
35 * and rounding for cash usage, for example: "50 NT$"
36 * @draft ICU 54
37 */
38 UCURR_USAGE_CASH=1,
39#endif /* U_HIDE_DRAFT_API */
40 /**
41 * One higher than the last enum UCurrencyUsage constant.
42 * @draft ICU 54
43 */
44 UCURR_USAGE_COUNT=2
45};
46typedef enum UCurrencyUsage UCurrencyUsage;
47
48/**
49 * The ucurr API encapsulates information about a currency, as defined by
50 * ISO 4217. A currency is represented by a 3-character string
51 * containing its ISO 4217 code. This API can return various data
52 * necessary the proper display of a currency:
53 *
54 * <ul><li>A display symbol, for a specific locale
55 * <li>The number of fraction digits to display
56 * <li>A rounding increment
57 * </ul>
58 *
59 * The <tt>DecimalFormat</tt> class uses these data to display
60 * currencies.
61 * @author Alan Liu
62 * @since ICU 2.2
63 */
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#ifndef U_HIDE_DRAFT_API
208/**
209 * Returns the number of the number of fraction digits that should
210 * be displayed for the given currency with usage.
211 * @param currency null-terminated 3-letter ISO 4217 code
212 * @param usage enum usage for the currency
213 * @param ec input-output error code
214 * @return a non-negative number of fraction digits to be
215 * displayed, or 0 if there is an error
216 * @draft ICU 54
217 */
218U_DRAFT int32_t U_EXPORT2
219ucurr_getDefaultFractionDigitsForUsage(const UChar* currency,
220 const UCurrencyUsage usage,
221 UErrorCode* ec);
222#endif /* U_HIDE_DRAFT_API */
223
224/**
225 * Returns the rounding increment for the given currency, or 0.0 if no
226 * rounding is done by the currency.
227 * This is equivalent to ucurr_getRoundingIncrementForUsage(currency,UCURR_USAGE_STANDARD,ec);
228 * @param currency null-terminated 3-letter ISO 4217 code
229 * @param ec input-output error code
230 * @return the non-negative rounding increment, or 0.0 if none,
231 * or 0.0 if there is an error
232 * @stable ICU 3.0
233 */
234U_STABLE double U_EXPORT2
235ucurr_getRoundingIncrement(const UChar* currency,
236 UErrorCode* ec);
237
238#ifndef U_HIDE_DRAFT_API
239/**
240 * Returns the rounding increment for the given currency, or 0.0 if no
241 * rounding is done by the currency given usage.
242 * @param currency null-terminated 3-letter ISO 4217 code
243 * @param usage enum usage for the currency
244 * @param ec input-output error code
245 * @return the non-negative rounding increment, or 0.0 if none,
246 * or 0.0 if there is an error
247 * @draft ICU 54
248 */
249U_DRAFT double U_EXPORT2
250ucurr_getRoundingIncrementForUsage(const UChar* currency,
251 const UCurrencyUsage usage,
252 UErrorCode* ec);
253#endif /* U_HIDE_DRAFT_API */
254
255/**
256 * Selector constants for ucurr_openCurrencies().
257 *
258 * @see ucurr_openCurrencies
259 * @stable ICU 3.2
260 */
261typedef enum UCurrCurrencyType {
262 /**
263 * Select all ISO-4217 currency codes.
264 * @stable ICU 3.2
265 */
266 UCURR_ALL = INT32_MAX,
267 /**
268 * Select only ISO-4217 commonly used currency codes.
269 * These currencies can be found in common use, and they usually have
270 * bank notes or coins associated with the currency code.
271 * This does not include fund codes, precious metals and other
272 * various ISO-4217 codes limited to special financial products.
273 * @stable ICU 3.2
274 */
275 UCURR_COMMON = 1,
276 /**
277 * Select ISO-4217 uncommon currency codes.
278 * These codes respresent fund codes, precious metals and other
279 * various ISO-4217 codes limited to special financial products.
280 * A fund code is a monetary resource associated with a currency.
281 * @stable ICU 3.2
282 */
283 UCURR_UNCOMMON = 2,
284 /**
285 * Select only deprecated ISO-4217 codes.
286 * These codes are no longer in general public use.
287 * @stable ICU 3.2
288 */
289 UCURR_DEPRECATED = 4,
290 /**
291 * Select only non-deprecated ISO-4217 codes.
292 * These codes are in general public use.
293 * @stable ICU 3.2
294 */
295 UCURR_NON_DEPRECATED = 8
296} UCurrCurrencyType;
297
298/**
299 * Provides a UEnumeration object for listing ISO-4217 codes.
300 * @param currType You can use one of several UCurrCurrencyType values for this
301 * variable. You can also | (or) them together to get a specific list of
302 * currencies. Most people will want to use the (UCURR_CURRENCY|UCURR_NON_DEPRECATED) value to
303 * get a list of current currencies.
304 * @param pErrorCode Error code
305 * @stable ICU 3.2
306 */
307U_STABLE UEnumeration * U_EXPORT2
308ucurr_openISOCurrencies(uint32_t currType, UErrorCode *pErrorCode);
309
310/**
311 * Queries if the given ISO 4217 3-letter code is available on the specified date range.
312 *
313 * Note: For checking availability of a currency on a specific date, specify the date on both 'from' and 'to'
314 *
315 * When 'from' is U_DATE_MIN and 'to' is U_DATE_MAX, this method checks if the specified currency is available any time.
316 * If 'from' and 'to' are same UDate value, this method checks if the specified currency is available on that date.
317 *
318 * @param isoCode
319 * The ISO 4217 3-letter code.
320 *
321 * @param from
322 * The lower bound of the date range, inclusive. When 'from' is U_DATE_MIN, check the availability
323 * of the currency any date before 'to'
324 *
325 * @param to
326 * The upper bound of the date range, inclusive. When 'to' is U_DATE_MAX, check the availability of
327 * the currency any date after 'from'
328 *
329 * @param errorCode
330 * ICU error code
331 *
332 * @return TRUE if the given ISO 4217 3-letter code is supported on the specified date range.
333 *
334 * @stable ICU 4.8
335 */
336U_STABLE UBool U_EXPORT2
337ucurr_isAvailable(const UChar* isoCode,
338 UDate from,
339 UDate to,
340 UErrorCode* errorCode);
341
342/**
343 * Finds the number of valid currency codes for the
344 * given locale and date.
345 * @param locale the locale for which to retrieve the
346 * currency count.
347 * @param date the date for which to retrieve the
348 * currency count for the given locale.
349 * @param ec error code
350 * @return the number of currency codes for the
351 * given locale and date. If 0, currency
352 * codes couldn't be found for the input
353 * values are invalid.
354 * @stable ICU 4.0
355 */
356U_STABLE int32_t U_EXPORT2
357ucurr_countCurrencies(const char* locale,
358 UDate date,
359 UErrorCode* ec);
360
361/**
362 * Finds a currency code for the given locale and date
363 * @param locale the locale for which to retrieve a currency code.
364 * Currency can be specified by the "currency" keyword
365 * in which case it overrides the default currency code
366 * @param date the date for which to retrieve a currency code for
367 * the given locale.
368 * @param index the index within the available list of currency codes
369 * for the given locale on the given date.
370 * @param buff fill in buffer. Can be NULL for preflighting.
371 * @param buffCapacity capacity of the fill in buffer. Can be 0 for
372 * preflighting. If it is non-zero, the buff parameter
373 * must not be NULL.
374 * @param ec error code
375 * @return length of the currency string. It should always be 3.
376 * If 0, currency couldn't be found or the input values are
377 * invalid.
378 * @stable ICU 4.0
379 */
380U_STABLE int32_t U_EXPORT2
381ucurr_forLocaleAndDate(const char* locale,
382 UDate date,
383 int32_t index,
384 UChar* buff,
385 int32_t buffCapacity,
386 UErrorCode* ec);
387
388/**
389 * Given a key and a locale, returns an array of string values in a preferred
390 * order that would make a difference. These are all and only those values where
391 * the open (creation) of the service with the locale formed from the input locale
392 * plus input keyword and that value has different behavior than creation with the
393 * input locale alone.
394 * @param key one of the keys supported by this service. For now, only
395 * "currency" is supported.
396 * @param locale the locale
397 * @param commonlyUsed if set to true it will return only commonly used values
398 * with the given locale in preferred order. Otherwise,
399 * it will return all the available values for the locale.
400 * @param status error status
401 * @return a string enumeration over keyword values for the given key and the locale.
402 * @stable ICU 4.2
403 */
404U_STABLE UEnumeration* U_EXPORT2
405ucurr_getKeywordValuesForLocale(const char* key,
406 const char* locale,
407 UBool commonlyUsed,
408 UErrorCode* status);
409
410/**
411 * Returns the ISO 4217 numeric code for the currency.
412 * <p>Note: If the ISO 4217 numeric code is not assigned for the currency or
413 * the currency is unknown, this function returns 0.
414 *
415 * @param currency null-terminated 3-letter ISO 4217 code
416 * @return The ISO 4217 numeric code of the currency
417 * @stable ICU 49
418 */
419U_STABLE int32_t U_EXPORT2
420ucurr_getNumericCode(const UChar* currency);
421
422#endif /* #if !UCONFIG_NO_FORMATTING */
423
424#endif
425