Home | History | Annotate | Download | only in unicode
      1 /*
      2 ********************************************************************************
      3 * Copyright (C) 1997-2010, International Business Machines Corporation and others.
      4 * All Rights Reserved.
      5 ********************************************************************************
      6 *
      7 * File NUMFMT.H
      8 *
      9 * Modification History:
     10 *
     11 *   Date        Name        Description
     12 *   02/19/97    aliu        Converted from java.
     13 *   03/18/97    clhuang     Updated per C++ implementation.
     14 *   04/17/97    aliu        Changed DigitCount to int per code review.
     15 *    07/20/98    stephen        JDK 1.2 sync up. Added scientific support.
     16 *                            Changed naming conventions to match C++ guidelines
     17 *                            Derecated Java style constants (eg, INTEGER_FIELD)
     18 ********************************************************************************
     19 */
     20 
     21 #ifndef NUMFMT_H
     22 #define NUMFMT_H
     23 
     24 
     25 #include "unicode/utypes.h"
     26 
     27 /**
     28  * \file
     29  * \brief C++ API: Abstract base class for all number formats.
     30  */
     31 
     32 #if !UCONFIG_NO_FORMATTING
     33 
     34 #include "unicode/unistr.h"
     35 #include "unicode/format.h"
     36 #include "unicode/unum.h" // UNumberFormatStyle
     37 #include "unicode/locid.h"
     38 #include "unicode/stringpiece.h"
     39 
     40 U_NAMESPACE_BEGIN
     41 
     42 #if !UCONFIG_NO_SERVICE
     43 class NumberFormatFactory;
     44 class StringEnumeration;
     45 #endif
     46 
     47 /**
     48  *
     49  * Abstract base class for all number formats.  Provides interface for
     50  * formatting and parsing a number.  Also provides methods for
     51  * determining which locales have number formats, and what their names
     52  * are.
     53  * <P>
     54  * NumberFormat helps you to format and parse numbers for any locale.
     55  * Your code can be completely independent of the locale conventions
     56  * for decimal points, thousands-separators, or even the particular
     57  * decimal digits used, or whether the number format is even decimal.
     58  * <P>
     59  * To format a number for the current Locale, use one of the static
     60  * factory methods:
     61  * <pre>
     62  * \code
     63  *    double myNumber = 7.0;
     64  *    UnicodeString myString;
     65  *    UErrorCode success = U_ZERO_ERROR;
     66  *    NumberFormat* nf = NumberFormat::createInstance(success)
     67  *    nf->format(myNumber, myString);
     68  *    cout << " Example 1: " << myString << endl;
     69  * \endcode
     70  * </pre>
     71  * If you are formatting multiple numbers, it is more efficient to get
     72  * the format and use it multiple times so that the system doesn't
     73  * have to fetch the information about the local language and country
     74  * conventions multiple times.
     75  * <pre>
     76  * \code
     77  *     UnicodeString myString;
     78  *     UErrorCode success = U_ZERO_ERROR;
     79  *     nf = NumberFormat::createInstance( success );
     80  *     int32_t a[] = { 123, 3333, -1234567 };
     81  *     const int32_t a_len = sizeof(a) / sizeof(a[0]);
     82  *     myString.remove();
     83  *     for (int32_t i = 0; i < a_len; i++) {
     84  *         nf->format(a[i], myString);
     85  *         myString += " ; ";
     86  *     }
     87  *     cout << " Example 2: " << myString << endl;
     88  * \endcode
     89  * </pre>
     90  * To format a number for a different Locale, specify it in the
     91  * call to createInstance().
     92  * <pre>
     93  * \code
     94  *     nf = NumberFormat::createInstance( Locale::FRENCH, success );
     95  * \endcode
     96  * </pre>
     97  * You can use a NumberFormat to parse also.
     98  * <pre>
     99  * \code
    100  *    UErrorCode success;
    101  *    Formattable result(-999);  // initialized with error code
    102  *    nf->parse(myString, result, success);
    103  * \endcode
    104  * </pre>
    105  * Use createInstance to get the normal number format for that country.
    106  * There are other static factory methods available.  Use getCurrency
    107  * to get the currency number format for that country.  Use getPercent
    108  * to get a format for displaying percentages. With this format, a
    109  * fraction from 0.53 is displayed as 53%.
    110  * <P>
    111  * Starting from ICU 4.2, you can use createInstance() by passing in a 'style'
    112  * as parameter to get the correct instance.
    113  * For example,
    114  * use createInstance(...kNumberStyle...) to get the normal number format,
    115  * createInstance(...kPercentStyle...) to get a format for displaying
    116  * percentage,
    117  * createInstance(...kScientificStyle...) to get a format for displaying
    118  * scientific number,
    119  * createInstance(...kCurrencyStyle...) to get the currency number format,
    120  * in which the currency is represented by its symbol, for example, "$3.00".
    121  * createInstance(...kIsoCurrencyStyle...)  to get the currency number format,
    122  * in which the currency is represented by its ISO code, for example "USD3.00".
    123  * createInstance(...kPluralCurrencyStyle...) to get the currency number format,
    124  * in which the currency is represented by its full name in plural format,
    125  * for example, "3.00 US dollars" or "1.00 US dollar".
    126  * <P>
    127  * You can also control the display of numbers with such methods as
    128  * getMinimumFractionDigits.  If you want even more control over the
    129  * format or parsing, or want to give your users more control, you can
    130  * try casting the NumberFormat you get from the factory methods to a
    131  * DecimalNumberFormat. This will work for the vast majority of
    132  * countries; just remember to put it in a try block in case you
    133  * encounter an unusual one.
    134  * <P>
    135  * You can also use forms of the parse and format methods with
    136  * ParsePosition and FieldPosition to allow you to:
    137  * <ul type=round>
    138  *   <li>(a) progressively parse through pieces of a string.
    139  *   <li>(b) align the decimal point and other areas.
    140  * </ul>
    141  * For example, you can align numbers in two ways.
    142  * <P>
    143  * If you are using a monospaced font with spacing for alignment, you
    144  * can pass the FieldPosition in your format call, with field =
    145  * INTEGER_FIELD. On output, getEndIndex will be set to the offset
    146  * between the last character of the integer and the decimal. Add
    147  * (desiredSpaceCount - getEndIndex) spaces at the front of the
    148  * string.
    149  * <P>
    150  * If you are using proportional fonts, instead of padding with
    151  * spaces, measure the width of the string in pixels from the start to
    152  * getEndIndex.  Then move the pen by (desiredPixelWidth -
    153  * widthToAlignmentPoint) before drawing the text.  It also works
    154  * where there is no decimal, but possibly additional characters at
    155  * the end, e.g. with parentheses in negative numbers: "(12)" for -12.
    156  * <p>
    157  * <em>User subclasses are not supported.</em> While clients may write
    158  * subclasses, such code will not necessarily work and will not be
    159  * guaranteed to work stably from release to release.
    160  *
    161  * @stable ICU 2.0
    162  */
    163 class U_I18N_API NumberFormat : public Format {
    164 public:
    165 
    166     /**
    167      * Constants for various number format styles.
    168      * kNumberStyle specifies a normal number style of format.
    169      * kCurrencyStyle specifies a currency format using currency symbol name,
    170      * such as in "$1.00".
    171      * kPercentStyle specifies a style of format to display percent.
    172      * kScientificStyle specifies a style of format to display scientific number.
    173      * kISOCurrencyStyle specifies a currency format using ISO currency code,
    174      * such as in "USD1.00".
    175      * kPluralCurrencyStyle specifies a currency format using currency plural
    176      * names, such as in "1.00 US dollar" and "3.00 US dollars".
    177      * @draft ICU 4.2
    178      */
    179     enum EStyles {
    180         kNumberStyle,
    181         kCurrencyStyle,
    182         kPercentStyle,
    183         kScientificStyle,
    184         kIsoCurrencyStyle,
    185         kPluralCurrencyStyle,
    186         kStyleCount // ALWAYS LAST ENUM: number of styles
    187     };
    188 
    189     /**
    190      * Alignment Field constants used to construct a FieldPosition object.
    191      * Signifies that the position of the integer part or fraction part of
    192      * a formatted number should be returned.
    193      *
    194      * Note: as of ICU 4.4, the values in this enum have been extended to
    195      * support identification of all number format fields, not just those
    196      * pertaining to alignment.
    197      *
    198      * @see FieldPosition
    199      * @stable ICU 2.0
    200      */
    201     enum EAlignmentFields {
    202         kIntegerField,
    203         kFractionField,
    204         kDecimalSeparatorField,
    205         kExponentSymbolField,
    206         kExponentSignField,
    207         kExponentField,
    208         kGroupingSeparatorField,
    209         kCurrencyField,
    210         kPercentField,
    211         kPermillField,
    212         kSignField,
    213 
    214     /**
    215      * These constants are provided for backwards compatibility only.
    216      * Please use the C++ style constants defined above.
    217      * @stable ICU 2.0
    218      */
    219         INTEGER_FIELD        = kIntegerField,
    220         FRACTION_FIELD        = kFractionField
    221     };
    222 
    223     /**
    224      * Destructor.
    225      * @stable ICU 2.0
    226      */
    227     virtual ~NumberFormat();
    228 
    229     /**
    230      * Return true if the given Format objects are semantically equal.
    231      * Objects of different subclasses are considered unequal.
    232      * @return    true if the given Format objects are semantically equal.
    233      * @stable ICU 2.0
    234      */
    235     virtual UBool operator==(const Format& other) const;
    236 
    237 
    238     using Format::format;
    239 
    240     /**
    241      * Format an object to produce a string.  This method handles
    242      * Formattable objects with numeric types. If the Formattable
    243      * object type is not a numeric type, then it returns a failing
    244      * UErrorCode.
    245      *
    246      * @param obj       The object to format.
    247      * @param appendTo  Output parameter to receive result.
    248      *                  Result is appended to existing contents.
    249      * @param pos       On input: an alignment field, if desired.
    250      *                  On output: the offsets of the alignment field.
    251      * @param status    Output param filled with success/failure status.
    252      * @return          Reference to 'appendTo' parameter.
    253      * @stable ICU 2.0
    254      */
    255     virtual UnicodeString& format(const Formattable& obj,
    256                                   UnicodeString& appendTo,
    257                                   FieldPosition& pos,
    258                                   UErrorCode& status) const;
    259 
    260     /**
    261      * Format an object to produce a string.  This method handles
    262      * Formattable objects with numeric types. If the Formattable
    263      * object type is not a numeric type, then it returns a failing
    264      * UErrorCode.
    265      *
    266      * @param obj       The object to format.
    267      * @param appendTo  Output parameter to receive result.
    268      *                  Result is appended to existing contents.
    269      * @param posIter   On return, can be used to iterate over positions
    270      *                  of fields generated by this format call.  Can be
    271      *                  NULL.
    272      * @param status    Output param filled with success/failure status.
    273      * @return          Reference to 'appendTo' parameter.
    274      * @stable 4.4
    275      */
    276     virtual UnicodeString& format(const Formattable& obj,
    277                                   UnicodeString& appendTo,
    278                                   FieldPositionIterator* posIter,
    279                                   UErrorCode& status) const;
    280 
    281     /**
    282      * Parse a string to produce an object.  This methods handles
    283      * parsing of numeric strings into Formattable objects with numeric
    284      * types.
    285      * <P>
    286      * Before calling, set parse_pos.index to the offset you want to
    287      * start parsing at in the source. After calling, parse_pos.index
    288      * indicates the position after the successfully parsed text.  If
    289      * an error occurs, parse_pos.index is unchanged.
    290      * <P>
    291      * When parsing, leading whitespace is discarded (with successful
    292      * parse), while trailing whitespace is left as is.
    293      * <P>
    294      * See Format::parseObject() for more.
    295      *
    296      * @param source    The string to be parsed into an object.
    297      * @param result    Formattable to be set to the parse result.
    298      *                  If parse fails, return contents are undefined.
    299      * @param parse_pos The position to start parsing at. Upon return
    300      *                  this param is set to the position after the
    301      *                  last character successfully parsed. If the
    302      *                  source is not parsed successfully, this param
    303      *                  will remain unchanged.
    304      * @return          A newly created Formattable* object, or NULL
    305      *                  on failure.  The caller owns this and should
    306      *                  delete it when done.
    307      * @stable ICU 2.0
    308      */
    309     virtual void parseObject(const UnicodeString& source,
    310                              Formattable& result,
    311                              ParsePosition& parse_pos) const;
    312 
    313     /**
    314      * Format a double number. These methods call the NumberFormat
    315      * pure virtual format() methods with the default FieldPosition.
    316      *
    317      * @param number    The value to be formatted.
    318      * @param appendTo  Output parameter to receive result.
    319      *                  Result is appended to existing contents.
    320      * @return          Reference to 'appendTo' parameter.
    321      * @stable ICU 2.0
    322      */
    323     UnicodeString& format(  double number,
    324                             UnicodeString& appendTo) const;
    325 
    326     /**
    327      * Format a long number. These methods call the NumberFormat
    328      * pure virtual format() methods with the default FieldPosition.
    329      *
    330      * @param number    The value to be formatted.
    331      * @param appendTo  Output parameter to receive result.
    332      *                  Result is appended to existing contents.
    333      * @return          Reference to 'appendTo' parameter.
    334      * @stable ICU 2.0
    335      */
    336     UnicodeString& format(  int32_t number,
    337                             UnicodeString& appendTo) const;
    338 
    339     /**
    340      * Format an int64 number. These methods call the NumberFormat
    341      * pure virtual format() methods with the default FieldPosition.
    342      *
    343      * @param number    The value to be formatted.
    344      * @param appendTo  Output parameter to receive result.
    345      *                  Result is appended to existing contents.
    346      * @return          Reference to 'appendTo' parameter.
    347      * @stable ICU 2.8
    348      */
    349     UnicodeString& format(  int64_t number,
    350                             UnicodeString& appendTo) const;
    351 
    352     /**
    353      * Format a double number. Concrete subclasses must implement
    354      * these pure virtual methods.
    355      *
    356      * @param number    The value to be formatted.
    357      * @param appendTo  Output parameter to receive result.
    358      *                  Result is appended to existing contents.
    359      * @param pos       On input: an alignment field, if desired.
    360      *                  On output: the offsets of the alignment field.
    361      * @return          Reference to 'appendTo' parameter.
    362      * @stable ICU 2.0
    363      */
    364     virtual UnicodeString& format(double number,
    365                                   UnicodeString& appendTo,
    366                                   FieldPosition& pos) const = 0;
    367     /**
    368      * Format a double number. Subclasses must implement
    369      * this method.
    370      *
    371      * @param number    The value to be formatted.
    372      * @param appendTo  Output parameter to receive result.
    373      *                  Result is appended to existing contents.
    374      * @param posIter   On return, can be used to iterate over positions
    375      *                  of fields generated by this format call.
    376      *                  Can be NULL.
    377      * @param status    Output param filled with success/failure status.
    378      * @return          Reference to 'appendTo' parameter.
    379      * @stable 4.4
    380      */
    381     virtual UnicodeString& format(double number,
    382                                   UnicodeString& appendTo,
    383                                   FieldPositionIterator* posIter,
    384                                   UErrorCode& status) const;
    385     /**
    386      * Format a long number. Concrete subclasses must implement
    387      * these pure virtual methods.
    388      *
    389      * @param number    The value to be formatted.
    390      * @param appendTo  Output parameter to receive result.
    391      *                  Result is appended to existing contents.
    392      * @param pos       On input: an alignment field, if desired.
    393      *                  On output: the offsets of the alignment field.
    394      * @return          Reference to 'appendTo' parameter.
    395      * @stable ICU 2.0
    396     */
    397     virtual UnicodeString& format(int32_t number,
    398                                   UnicodeString& appendTo,
    399                                   FieldPosition& pos) const = 0;
    400 
    401     /**
    402      * Format an int32 number. Subclasses must implement
    403      * this method.
    404      *
    405      * @param number    The value to be formatted.
    406      * @param appendTo  Output parameter to receive result.
    407      *                  Result is appended to existing contents.
    408      * @param posIter   On return, can be used to iterate over positions
    409      *                  of fields generated by this format call.
    410      *                  Can be NULL.
    411      * @param status    Output param filled with success/failure status.
    412      * @return          Reference to 'appendTo' parameter.
    413      * @stable 4.4
    414      */
    415     virtual UnicodeString& format(int32_t number,
    416                                   UnicodeString& appendTo,
    417                                   FieldPositionIterator* posIter,
    418                                   UErrorCode& status) const;
    419     /**
    420      * Format an int64 number. (Not abstract to retain compatibility
    421      * with earlier releases, however subclasses should override this
    422      * method as it just delegates to format(int32_t number...);
    423      *
    424      * @param number    The value to be formatted.
    425      * @param appendTo  Output parameter to receive result.
    426      *                  Result is appended to existing contents.
    427      * @param pos       On input: an alignment field, if desired.
    428      *                  On output: the offsets of the alignment field.
    429      * @return          Reference to 'appendTo' parameter.
    430      * @stable ICU 2.8
    431     */
    432     virtual UnicodeString& format(int64_t number,
    433                                   UnicodeString& appendTo,
    434                                   FieldPosition& pos) const;
    435     /**
    436      * Format an int64 number. Subclasses must implement
    437      * this method.
    438      *
    439      * @param number    The value to be formatted.
    440      * @param appendTo  Output parameter to receive result.
    441      *                  Result is appended to existing contents.
    442      * @param posIter   On return, can be used to iterate over positions
    443      *                  of fields generated by this format call.
    444      *                  Can be NULL.
    445      * @param status    Output param filled with success/failure status.
    446      * @return          Reference to 'appendTo' parameter.
    447      * @stable 4.4
    448      */
    449     virtual UnicodeString& format(int64_t number,
    450                                   UnicodeString& appendTo,
    451                                   FieldPositionIterator* posIter,
    452                                   UErrorCode& status) const;
    453 
    454     /**
    455      * Format a decimal number. Subclasses must implement
    456      * this method.  The syntax of the unformatted number is a "numeric string"
    457      * as defined in the Decimal Arithmetic Specification, available at
    458      * http://speleotrove.com/decimal
    459      *
    460      * @param number    The unformatted number, as a string, to be formatted.
    461      * @param appendTo  Output parameter to receive result.
    462      *                  Result is appended to existing contents.
    463      * @param posIter   On return, can be used to iterate over positions
    464      *                  of fields generated by this format call.
    465      *                  Can be NULL.
    466      * @param status    Output param filled with success/failure status.
    467      * @return          Reference to 'appendTo' parameter.
    468      * @stable 4.4
    469      */
    470     virtual UnicodeString& format(const StringPiece &number,
    471                                   UnicodeString& appendTo,
    472                                   FieldPositionIterator* posIter,
    473                                   UErrorCode& status) const;
    474 public:
    475     /**
    476      * Format a decimal number.
    477      * The number is a DigitList wrapper onto a floating point decimal number.
    478      * The default implementation in NumberFormat converts the decimal number
    479      * to a double and formats that.  Subclasses of NumberFormat that want
    480      * to specifically handle big decimal numbers must override this method.
    481      * class DecimalFormat does so.
    482      *
    483      * @param number    The number, a DigitList format Decimal Floating Point.
    484      * @param appendTo  Output parameter to receive result.
    485      *                  Result is appended to existing contents.
    486      * @param posIter   On return, can be used to iterate over positions
    487      *                  of fields generated by this format call.
    488      * @param status    Output param filled with success/failure status.
    489      * @return          Reference to 'appendTo' parameter.
    490      * @internal
    491      */
    492     virtual UnicodeString& format(const DigitList &number,
    493                                   UnicodeString& appendTo,
    494                                   FieldPositionIterator* posIter,
    495                                   UErrorCode& status) const;
    496 
    497     /**
    498      * Format a decimal number.
    499      * The number is a DigitList wrapper onto a floating point decimal number.
    500      * The default implementation in NumberFormat converts the decimal number
    501      * to a double and formats that.  Subclasses of NumberFormat that want
    502      * to specifically handle big decimal numbers must override this method.
    503      * class DecimalFormat does so.
    504      *
    505      * @param number    The number, a DigitList format Decimal Floating Point.
    506      * @param appendTo  Output parameter to receive result.
    507      *                  Result is appended to existing contents.
    508      * @param pos       On input: an alignment field, if desired.
    509      *                  On output: the offsets of the alignment field.
    510      * @param status    Output param filled with success/failure status.
    511      * @return          Reference to 'appendTo' parameter.
    512      * @internal
    513      */
    514     virtual UnicodeString& format(const DigitList &number,
    515                                   UnicodeString& appendTo,
    516                                   FieldPosition& pos,
    517                                   UErrorCode& status) const;
    518 
    519 public:
    520 
    521     /**
    522      * Redeclared Format method.
    523      * @param obj       The object to be formatted.
    524      * @param appendTo  Output parameter to receive result.
    525      *                  Result is appended to existing contents.
    526      * @param status    Output parameter set to a failure error code
    527      *                  when a failure occurs.
    528      * @return          Reference to 'appendTo' parameter.
    529      * @stable ICU 2.0
    530      */
    531     UnicodeString& format(const Formattable& obj,
    532                           UnicodeString& appendTo,
    533                           UErrorCode& status) const;
    534 
    535    /**
    536     * Return a long if possible (e.g. within range LONG_MAX,
    537     * LONG_MAX], and with no decimals), otherwise a double.  If
    538     * IntegerOnly is set, will stop at a decimal point (or equivalent;
    539     * e.g. for rational numbers "1 2/3", will stop after the 1).
    540     * <P>
    541     * If no object can be parsed, index is unchanged, and NULL is
    542     * returned.
    543     * <P>
    544     * This is a pure virtual which concrete subclasses must implement.
    545     *
    546     * @param text           The text to be parsed.
    547     * @param result         Formattable to be set to the parse result.
    548     *                       If parse fails, return contents are undefined.
    549     * @param parsePosition  The position to start parsing at on input.
    550     *                       On output, moved to after the last successfully
    551     *                       parse character. On parse failure, does not change.
    552     * @return               A Formattable object of numeric type.  The caller
    553     *                       owns this an must delete it.  NULL on failure.
    554     * @stable ICU 2.0
    555     */
    556     virtual void parse(const UnicodeString& text,
    557                        Formattable& result,
    558                        ParsePosition& parsePosition) const = 0;
    559 
    560     /**
    561      * Parse a string as a numeric value, and return a Formattable
    562      * numeric object. This method parses integers only if IntegerOnly
    563      * is set.
    564      *
    565      * @param text          The text to be parsed.
    566      * @param result        Formattable to be set to the parse result.
    567      *                      If parse fails, return contents are undefined.
    568      * @param status        Output parameter set to a failure error code
    569      *                      when a failure occurs.
    570      * @return              A Formattable object of numeric type.  The caller
    571      *                      owns this an must delete it.  NULL on failure.
    572      * @see                 NumberFormat::isParseIntegerOnly
    573      * @stable ICU 2.0
    574      */
    575     virtual void parse( const UnicodeString& text,
    576                         Formattable& result,
    577                         UErrorCode& status) const;
    578 
    579     /**
    580      * Parses text from the given string as a currency amount.  Unlike
    581      * the parse() method, this method will attempt to parse a generic
    582      * currency name, searching for a match of this object's locale's
    583      * currency display names, or for a 3-letter ISO currency code.
    584      * This method will fail if this format is not a currency format,
    585      * that is, if it does not contain the currency pattern symbol
    586      * (U+00A4) in its prefix or suffix.
    587      *
    588      * @param text the string to parse
    589      * @param result output parameter to receive result. This will have
    590      * its currency set to the parsed ISO currency code.
    591      * @param pos input-output position; on input, the position within
    592      * text to match; must have 0 <= pos.getIndex() < text.length();
    593      * on output, the position after the last matched character. If
    594      * the parse fails, the position in unchanged upon output.
    595      * @return a reference to result
    596      * @internal
    597      */
    598     virtual Formattable& parseCurrency(const UnicodeString& text,
    599                                        Formattable& result,
    600                                        ParsePosition& pos) const;
    601 
    602     /**
    603      * Return true if this format will parse numbers as integers
    604      * only.  For example in the English locale, with ParseIntegerOnly
    605      * true, the string "1234." would be parsed as the integer value
    606      * 1234 and parsing would stop at the "." character.  Of course,
    607      * the exact format accepted by the parse operation is locale
    608      * dependant and determined by sub-classes of NumberFormat.
    609      * @return    true if this format will parse numbers as integers
    610      *            only.
    611      * @stable ICU 2.0
    612      */
    613     UBool isParseIntegerOnly(void) const;
    614 
    615     /**
    616      * Sets whether or not numbers should be parsed as integers only.
    617      * @param value    set True, this format will parse numbers as integers
    618      *                 only.
    619      * @see isParseIntegerOnly
    620      * @stable ICU 2.0
    621      */
    622     virtual void setParseIntegerOnly(UBool value);
    623 
    624     /**
    625      * Returns the default number format for the current default
    626      * locale.  The default format is one of the styles provided by
    627      * the other factory methods: getNumberInstance,
    628      * getCurrencyInstance or getPercentInstance.  Exactly which one
    629      * is locale dependant.
    630      * @stable ICU 2.0
    631      */
    632     static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
    633 
    634     /**
    635      * Returns the default number format for the specified locale.
    636      * The default format is one of the styles provided by the other
    637      * factory methods: getNumberInstance, getCurrencyInstance or
    638      * getPercentInstance.  Exactly which one is locale dependant.
    639      * @param inLocale    the given locale.
    640      * @stable ICU 2.0
    641      */
    642     static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
    643                                         UErrorCode&);
    644 
    645     /**
    646      * Creates the specified decimal format style of the desired locale.
    647      * @param desiredLocale    the given locale.
    648      * @param choice           the given style.
    649      * @param success          Output param filled with success/failure status.
    650      * @return                 A new NumberFormat instance.
    651      * @draft ICU 4.2
    652      */
    653     static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success);
    654 
    655 
    656     /**
    657      * Returns a currency format for the current default locale.
    658      * @stable ICU 2.0
    659      */
    660     static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
    661 
    662     /**
    663      * Returns a currency format for the specified locale.
    664      * @param inLocale    the given locale.
    665      * @stable ICU 2.0
    666      */
    667     static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
    668                                                 UErrorCode&);
    669 
    670     /**
    671      * Returns a percentage format for the current default locale.
    672      * @stable ICU 2.0
    673      */
    674     static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
    675 
    676     /**
    677      * Returns a percentage format for the specified locale.
    678      * @param inLocale    the given locale.
    679      * @stable ICU 2.0
    680      */
    681     static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
    682                                                UErrorCode&);
    683 
    684     /**
    685      * Returns a scientific format for the current default locale.
    686      * @stable ICU 2.0
    687      */
    688     static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
    689 
    690     /**
    691      * Returns a scientific format for the specified locale.
    692      * @param inLocale    the given locale.
    693      * @stable ICU 2.0
    694      */
    695     static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
    696                                                 UErrorCode&);
    697 
    698     /**
    699      * Get the set of Locales for which NumberFormats are installed.
    700      * @param count    Output param to receive the size of the locales
    701      * @stable ICU 2.0
    702      */
    703     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
    704 
    705 #if !UCONFIG_NO_SERVICE
    706     /**
    707      * Register a new NumberFormatFactory.  The factory will be adopted.
    708      * @param toAdopt the NumberFormatFactory instance to be adopted
    709      * @param status the in/out status code, no special meanings are assigned
    710      * @return a registry key that can be used to unregister this factory
    711      * @stable ICU 2.6
    712      */
    713     static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
    714 
    715     /**
    716      * Unregister a previously-registered NumberFormatFactory using the key returned from the
    717      * register call.  Key becomes invalid after a successful call and should not be used again.
    718      * The NumberFormatFactory corresponding to the key will be deleted.
    719      * @param key the registry key returned by a previous call to registerFactory
    720      * @param status the in/out status code, no special meanings are assigned
    721      * @return TRUE if the factory for the key was successfully unregistered
    722      * @stable ICU 2.6
    723      */
    724     static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
    725 
    726     /**
    727      * Return a StringEnumeration over the locales available at the time of the call,
    728      * including registered locales.
    729      * @return a StringEnumeration over the locales available at the time of the call
    730      * @stable ICU 2.6
    731      */
    732     static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
    733 #endif /* UCONFIG_NO_SERVICE */
    734 
    735     /**
    736      * Returns true if grouping is used in this format. For example,
    737      * in the English locale, with grouping on, the number 1234567
    738      * might be formatted as "1,234,567". The grouping separator as
    739      * well as the size of each group is locale dependant and is
    740      * determined by sub-classes of NumberFormat.
    741      * @see setGroupingUsed
    742      * @stable ICU 2.0
    743      */
    744     UBool isGroupingUsed(void) const;
    745 
    746     /**
    747      * Set whether or not grouping will be used in this format.
    748      * @param newValue    True, grouping will be used in this format.
    749      * @see getGroupingUsed
    750      * @stable ICU 2.0
    751      */
    752     virtual void setGroupingUsed(UBool newValue);
    753 
    754     /**
    755      * Returns the maximum number of digits allowed in the integer portion of a
    756      * number.
    757      * @return     the maximum number of digits allowed in the integer portion of a
    758      *             number.
    759      * @see setMaximumIntegerDigits
    760      * @stable ICU 2.0
    761      */
    762     int32_t getMaximumIntegerDigits(void) const;
    763 
    764     /**
    765      * Sets the maximum number of digits allowed in the integer portion of a
    766      * number. maximumIntegerDigits must be >= minimumIntegerDigits.  If the
    767      * new value for maximumIntegerDigits is less than the current value
    768      * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
    769      * the new value.
    770      *
    771      * @param newValue    the new value for the maximum number of digits
    772      *                    allowed in the integer portion of a number.
    773      * @see getMaximumIntegerDigits
    774      * @stable ICU 2.0
    775      */
    776     virtual void setMaximumIntegerDigits(int32_t newValue);
    777 
    778     /**
    779      * Returns the minimum number of digits allowed in the integer portion of a
    780      * number.
    781      * @return    the minimum number of digits allowed in the integer portion of a
    782      *            number.
    783      * @see setMinimumIntegerDigits
    784      * @stable ICU 2.0
    785      */
    786     int32_t getMinimumIntegerDigits(void) const;
    787 
    788     /**
    789      * Sets the minimum number of digits allowed in the integer portion of a
    790      * number. minimumIntegerDigits must be &lt;= maximumIntegerDigits.  If the
    791      * new value for minimumIntegerDigits exceeds the current value
    792      * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
    793      * the new value.
    794      * @param newValue    the new value to be set.
    795      * @see getMinimumIntegerDigits
    796      * @stable ICU 2.0
    797      */
    798     virtual void setMinimumIntegerDigits(int32_t newValue);
    799 
    800     /**
    801      * Returns the maximum number of digits allowed in the fraction portion of a
    802      * number.
    803      * @return    the maximum number of digits allowed in the fraction portion of a
    804      *            number.
    805      * @see setMaximumFractionDigits
    806      * @stable ICU 2.0
    807      */
    808     int32_t getMaximumFractionDigits(void) const;
    809 
    810     /**
    811      * Sets the maximum number of digits allowed in the fraction portion of a
    812      * number. maximumFractionDigits must be >= minimumFractionDigits.  If the
    813      * new value for maximumFractionDigits is less than the current value
    814      * of minimumFractionDigits, then minimumFractionDigits will also be set to
    815      * the new value.
    816      * @param newValue    the new value to be set.
    817      * @see getMaximumFractionDigits
    818      * @stable ICU 2.0
    819      */
    820     virtual void setMaximumFractionDigits(int32_t newValue);
    821 
    822     /**
    823      * Returns the minimum number of digits allowed in the fraction portion of a
    824      * number.
    825      * @return    the minimum number of digits allowed in the fraction portion of a
    826      *            number.
    827      * @see setMinimumFractionDigits
    828      * @stable ICU 2.0
    829      */
    830     int32_t getMinimumFractionDigits(void) const;
    831 
    832     /**
    833      * Sets the minimum number of digits allowed in the fraction portion of a
    834      * number. minimumFractionDigits must be &lt;= maximumFractionDigits.   If the
    835      * new value for minimumFractionDigits exceeds the current value
    836      * of maximumFractionDigits, then maximumIntegerDigits will also be set to
    837      * the new value
    838      * @param newValue    the new value to be set.
    839      * @see getMinimumFractionDigits
    840      * @stable ICU 2.0
    841      */
    842     virtual void setMinimumFractionDigits(int32_t newValue);
    843 
    844     /**
    845      * Sets the currency used to display currency
    846      * amounts.  This takes effect immediately, if this format is a
    847      * currency format.  If this format is not a currency format, then
    848      * the currency is used if and when this object becomes a
    849      * currency format.
    850      * @param theCurrency a 3-letter ISO code indicating new currency
    851      * to use.  It need not be null-terminated.  May be the empty
    852      * string or NULL to indicate no currency.
    853      * @param ec input-output error code
    854      * @stable ICU 3.0
    855      */
    856     virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
    857 
    858     /**
    859      * Gets the currency used to display currency
    860      * amounts.  This may be an empty string for some subclasses.
    861      * @return a 3-letter null-terminated ISO code indicating
    862      * the currency in use, or a pointer to the empty string.
    863      * @stable ICU 2.6
    864      */
    865     const UChar* getCurrency() const;
    866 
    867 public:
    868 
    869     /**
    870      * Return the class ID for this class.  This is useful for
    871      * comparing to a return value from getDynamicClassID(). Note that,
    872      * because NumberFormat is an abstract base class, no fully constructed object
    873      * will have the class ID returned by NumberFormat::getStaticClassID().
    874      * @return The class ID for all objects of this class.
    875      * @stable ICU 2.0
    876      */
    877     static UClassID U_EXPORT2 getStaticClassID(void);
    878 
    879     /**
    880      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
    881      * This method is to implement a simple version of RTTI, since not all
    882      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
    883      * clone() methods call this method.
    884      * <P>
    885      * @return The class ID for this object. All objects of a
    886      * given class have the same class ID.  Objects of
    887      * other classes have different class IDs.
    888      * @stable ICU 2.0
    889      */
    890     virtual UClassID getDynamicClassID(void) const = 0;
    891 
    892 protected:
    893 
    894     /**
    895      * Default constructor for subclass use only.
    896      * @stable ICU 2.0
    897      */
    898     NumberFormat();
    899 
    900     /**
    901      * Copy constructor.
    902      * @stable ICU 2.0
    903      */
    904     NumberFormat(const NumberFormat&);
    905 
    906     /**
    907      * Assignment operator.
    908      * @stable ICU 2.0
    909      */
    910     NumberFormat& operator=(const NumberFormat&);
    911 
    912     /**
    913      * Returns the currency in effect for this formatter.  Subclasses
    914      * should override this method as needed.  Unlike getCurrency(),
    915      * this method should never return "".
    916      * @result output parameter for null-terminated result, which must
    917      * have a capacity of at least 4
    918      * @internal
    919      */
    920     virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const;
    921 
    922 private:
    923 
    924     /**
    925      * Creates the specified decimal format style of the desired locale.
    926      * @param desiredLocale    the given locale.
    927      * @param choice           the given style.
    928      * @param success          Output param filled with success/failure status.
    929      * @return                 A new NumberFormat instance.
    930      */
    931     static NumberFormat* makeInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success);
    932 
    933     UBool      fGroupingUsed;
    934     int32_t     fMaxIntegerDigits;
    935     int32_t     fMinIntegerDigits;
    936     int32_t     fMaxFractionDigits;
    937     int32_t     fMinFractionDigits;
    938     UBool      fParseIntegerOnly;
    939 
    940     // ISO currency code
    941     UChar      fCurrency[4];
    942 
    943     friend class ICUNumberFormatFactory; // access to makeInstance, EStyles
    944     friend class ICUNumberFormatService;
    945 };
    946 
    947 #if !UCONFIG_NO_SERVICE
    948 /**
    949  * A NumberFormatFactory is used to register new number formats.  The factory
    950  * should be able to create any of the predefined formats for each locale it
    951  * supports.  When registered, the locales it supports extend or override the
    952  * locale already supported by ICU.
    953  *
    954  * @stable ICU 2.6
    955  */
    956 class U_I18N_API NumberFormatFactory : public UObject {
    957 public:
    958 
    959     /**
    960      * Destructor
    961      * @stable ICU 3.0
    962      */
    963     virtual ~NumberFormatFactory();
    964 
    965     /**
    966      * Return true if this factory will be visible.  Default is true.
    967      * If not visible, the locales supported by this factory will not
    968      * be listed by getAvailableLocales.
    969      * @stable ICU 2.6
    970      */
    971     virtual UBool visible(void) const = 0;
    972 
    973     /**
    974      * Return the locale names directly supported by this factory.  The number of names
    975      * is returned in count;
    976      * @stable ICU 2.6
    977      */
    978     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
    979 
    980     /**
    981      * Return a number format of the appropriate type.  If the locale
    982      * is not supported, return null.  If the locale is supported, but
    983      * the type is not provided by this service, return null.  Otherwise
    984      * return an appropriate instance of NumberFormat.
    985      * @stable ICU 2.6
    986      */
    987     virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
    988 };
    989 
    990 /**
    991  * A NumberFormatFactory that supports a single locale.  It can be visible or invisible.
    992  * @stable ICU 2.6
    993  */
    994 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
    995 protected:
    996     /**
    997      * True if the locale supported by this factory is visible.
    998      * @stable ICU 2.6
    999      */
   1000     const UBool _visible;
   1001 
   1002     /**
   1003      * The locale supported by this factory, as a UnicodeString.
   1004      * @stable ICU 2.6
   1005      */
   1006     UnicodeString _id;
   1007 
   1008 public:
   1009     /**
   1010      * @stable ICU 2.6
   1011      */
   1012     SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
   1013 
   1014     /**
   1015      * @stable ICU 3.0
   1016      */
   1017     virtual ~SimpleNumberFormatFactory();
   1018 
   1019     /**
   1020      * @stable ICU 2.6
   1021      */
   1022     virtual UBool visible(void) const;
   1023 
   1024     /**
   1025      * @stable ICU 2.6
   1026      */
   1027     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
   1028 };
   1029 #endif /* #if !UCONFIG_NO_SERVICE */
   1030 
   1031 // -------------------------------------
   1032 
   1033 inline UBool
   1034 NumberFormat::isParseIntegerOnly() const
   1035 {
   1036     return fParseIntegerOnly;
   1037 }
   1038 
   1039 inline UnicodeString&
   1040 NumberFormat::format(const Formattable& obj,
   1041                      UnicodeString& appendTo,
   1042                      UErrorCode& status) const {
   1043     return Format::format(obj, appendTo, status);
   1044 }
   1045 
   1046 U_NAMESPACE_END
   1047 
   1048 #endif /* #if !UCONFIG_NO_FORMATTING */
   1049 
   1050 #endif // _NUMFMT
   1051 //eof
   1052