Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ucurr.h @ 69:33d812a61356

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