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

source code of include/unicode/ucurr.h