icuSources/i18n/unicode/ucurr.h

   1 /*
   2 **********************************************************************
   3 * Copyright (c) 2002-2004, 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
  12 #if !UCONFIG_NO_FORMATTING
  13
  14 /**
  15  * The ucurr API encapsulates information about a currency, as defined by
  16  * ISO 4217.  A currency is represented by a 3-character string
  17  * containing its ISO 4217 code.  This API can return various data
  18  * necessary the proper display of a currency:
  19  *
  20  * <ul><li>A display symbol, for a specific locale
  21  * <li>The number of fraction digits to display
  22  * <li>A rounding increment
  23  * </ul>
  24  *
  25  * The <tt>DecimalFormat</tt> class uses these data to display
  26  * currencies.
  27  * @author Alan Liu
  28  * @since ICU 2.2
  29  */
  30
  31 /**
  32  * Finds a currency code for the given locale.
  33  * @param locale the locale for which to retrieve a currency code.
  34  *               Currency can be specified by the "currency" keyword
  35  *               in which case it overrides the default currency code
  36  * @param buff   fill in buffer. Can be NULL for preflighting.
  37  * @param buffCapacity capacity of the fill in buffer. Can be 0 for
  38  *               preflighting. If it is non-zero, the buff parameter
  39  *               must not be NULL.
  40  * @param ec error code
  41  * @return length of the currency string. It should always be 3. If 0,
  42  *                currency couldn't be found or the input values are
  43  *                invalid.
  44  * @draft ICU 2.8
  45  */
  46 U_DRAFT int32_t U_EXPORT2
  47 ucurr_forLocale(const char* locale,
  48                 UChar* buff,
  49                 int32_t buffCapacity,
  50                 UErrorCode* ec);
  51
  52 /**
  53  * Selector constants for ucurr_getName().
  54  *
  55  * @see ucurr_getName
  56  * @stable ICU 2.6
  57  */
  58 typedef enum UCurrNameStyle {
  59     /**
  60      * Selector for ucurr_getName indicating a symbolic name for a
  61      * currency, such as "$" for USD.
  62      * @stable ICU 2.6
  63      */
  64     UCURR_SYMBOL_NAME,
  65
  66     /**
  67      * Selector for ucurr_getName indicating the long name for a
  68      * currency, such as "US Dollar" for USD.
  69      * @stable ICU 2.6
  70      */
  71     UCURR_LONG_NAME
  72 } UCurrNameStyle;
  73
  74 #if !UCONFIG_NO_SERVICE
  75 /**
  76  * @internal
  77  */
  78 typedef const void* UCurrRegistryKey;
  79
  80 /**
  81  * Register an (existing) ISO 4217 currency code for the given locale.
  82  * Only the country code and the two variants EURO and PRE_EURO are
  83  * recognized.
  84  * @param isoCode the three-letter ISO 4217 currency code
  85  * @param locale  the locale for which to register this currency code
  86  * @param status the in/out status code
  87  * @return a registry key that can be used to unregister this currency code, or NULL
  88  * if there was an error.
  89  * @stable ICU 2.6
  90  */
  91 U_STABLE UCurrRegistryKey U_EXPORT2
  92 ucurr_register(const UChar* isoCode,
  93                    const char* locale,
  94                    UErrorCode* status);
  95 /**
  96  * Unregister the previously-registered currency definitions using the
  97  * URegistryKey returned from ucurr_register.  Key becomes invalid after
  98  * a successful call and should not be used again.  Any currency
  99  * that might have been hidden by the original ucurr_register call is
 100  * restored.
 101  * @param key the registry key returned by a previous call to ucurr_register
 102  * @param status the in/out status code, no special meanings are assigned
 103  * @return TRUE if the currency for this key was successfully unregistered
 104  * @stable ICU 2.6
 105  */
 106 U_STABLE UBool U_EXPORT2
 107 ucurr_unregister(UCurrRegistryKey key, UErrorCode* status);
 108 #endif /* UCONFIG_NO_SERVICE */
 109
 110 /**
 111  * Returns the display name for the given currency in the
 112  * given locale.  For example, the display name for the USD
 113  * currency object in the en_US locale is "$".
 114  * @param currency null-terminated 3-letter ISO 4217 code
 115  * @param locale locale in which to display currency
 116  * @param nameStyle selector for which kind of name to return
 117  * @param isChoiceFormat fill-in set to TRUE if the returned value
 118  * is a ChoiceFormat pattern; otherwise it is a static string
 119  * @param len fill-in parameter to receive length of result
 120  * @param ec error code
 121  * @return pointer to display string of 'len' UChars.  If the resource
 122  * data contains no entry for 'currency', then 'currency' itself is
 123  * returned.  If *isChoiceFormat is TRUE, then the result is a
 124  * ChoiceFormat pattern.  Otherwise it is a static string.
 125  * @stable ICU 2.6
 126  */
 127 U_STABLE const UChar* U_EXPORT2
 128 ucurr_getName(const UChar* currency,
 129               const char* locale,
 130               UCurrNameStyle nameStyle,
 131               UBool* isChoiceFormat,
 132               int32_t* len,
 133               UErrorCode* ec);
 134
 135 /**
 136  * Returns the number of the number of fraction digits that should
 137  * be displayed for the given currency.
 138  * @param currency null-terminated 3-letter ISO 4217 code
 139  * @param ec input-output error code
 140  * @return a non-negative number of fraction digits to be
 141  * displayed, or 0 if there is an error
 142  * @draft ICU 3.0
 143  */
 144 U_DRAFT int32_t U_EXPORT2
 145 ucurr_getDefaultFractionDigits(const UChar* currency,
 146                                UErrorCode* ec);
 147
 148 /**
 149  * Returns the rounding increment for the given currency, or 0.0 if no
 150  * rounding is done by the currency.
 151  * @param currency null-terminated 3-letter ISO 4217 code
 152  * @param ec input-output error code
 153  * @return the non-negative rounding increment, or 0.0 if none,
 154  * or 0.0 if there is an error
 155  * @draft ICU 3.0
 156  */
 157 U_DRAFT double U_EXPORT2
 158 ucurr_getRoundingIncrement(const UChar* currency,
 159                            UErrorCode* ec);
 160
 161 #ifdef XP_CPLUSPLUS
 162 #include "unicode/unistr.h"
 163 #include "unicode/parsepos.h"
 164 U_NAMESPACE_BEGIN
 165
 166 /**
 167  * Attempt to parse the given string as a currency, either as a
 168  * display name in the given locale, or as a 3-letter ISO 4217
 169  * code.  If multiple display names match, then the longest one is
 170  * selected.  If both a display name and a 3-letter ISO code
 171  * match, then the display name is preferred, unless it's length
 172  * is less than 3.
 173  *
 174  * @param locale the locale of the display names to match
 175  * @param text the text to parse
 176  * @param pos input-output position; on input, the position within
 177  * text to match; must have 0 <= pos.getIndex() < text.length();
 178  * on output, the position after the last matched character. If
 179  * the parse fails, the position in unchanged upon output.
 180  * @return the ISO 4217 code, as a string, of the best match, or
 181  * null if there is no match
 182  *
 183  * @internal
 184  */
 185 void
 186 uprv_parseCurrency(const char* locale,
 187                    const UnicodeString& text,
 188                    ParsePosition& pos,
 189                    UChar* result,
 190                    UErrorCode& ec);
 191
 192 U_NAMESPACE_END
 193 #endif
 194
 195 #endif /* #if !UCONFIG_NO_FORMATTING */
 196
 197 #endif