icuSources/i18n/unicode/numfmt.h

   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      * Return whether or not strict parsing is in effect.
 626      *
 627      * @return <code>TRUE</code> if strict parsing is in effect,
 628      *         <code>FALSE</code> otherwise.
 629      *  @internal
 630      */
 631     UBool isParseStrict(void) const;
 632
 633     /**
 634      * Set whether or not strict parsing should be used.
 635      *
 636      * @param value <code>TRUE</code> if strict parsing should be used,
 637      *              <code>FALSE</code> otherwise.
 638      *  @internal
 639      */
 640     virtual void setParseStrict(UBool value);
 641
 642     /**
 643      * Returns the default number format for the current default
 644      * locale.  The default format is one of the styles provided by
 645      * the other factory methods: getNumberInstance,
 646      * getCurrencyInstance or getPercentInstance.  Exactly which one
 647      * is locale dependant.
 648      * @stable ICU 2.0
 649      */
 650     static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
 651
 652     /**
 653      * Returns the default number format for the specified locale.
 654      * The default format is one of the styles provided by the other
 655      * factory methods: getNumberInstance, getCurrencyInstance or
 656      * getPercentInstance.  Exactly which one is locale dependant.
 657      * @param inLocale    the given locale.
 658      * @stable ICU 2.0
 659      */
 660     static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
 661                                         UErrorCode&);
 662
 663     /**
 664      * Creates the specified decimal format style of the desired locale.
 665      * @param desiredLocale    the given locale.
 666      * @param choice           the given style.
 667      * @param success          Output param filled with success/failure status.
 668      * @return                 A new NumberFormat instance.
 669      * @draft ICU 4.2
 670      */
 671     static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success);
 672
 673
 674     /**
 675      * Returns a currency format for the current default locale.
 676      * @stable ICU 2.0
 677      */
 678     static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
 679
 680     /**
 681      * Returns a currency format for the specified locale.
 682      * @param inLocale    the given locale.
 683      * @stable ICU 2.0
 684      */
 685     static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
 686                                                 UErrorCode&);
 687
 688     /**
 689      * Returns a percentage format for the current default locale.
 690      * @stable ICU 2.0
 691      */
 692     static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
 693
 694     /**
 695      * Returns a percentage format for the specified locale.
 696      * @param inLocale    the given locale.
 697      * @stable ICU 2.0
 698      */
 699     static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
 700                                                UErrorCode&);
 701
 702     /**
 703      * Returns a scientific format for the current default locale.
 704      * @stable ICU 2.0
 705      */
 706     static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
 707
 708     /**
 709      * Returns a scientific format for the specified locale.
 710      * @param inLocale    the given locale.
 711      * @stable ICU 2.0
 712      */
 713     static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
 714                                                 UErrorCode&);
 715
 716     /**
 717      * Get the set of Locales for which NumberFormats are installed.
 718      * @param count    Output param to receive the size of the locales
 719      * @stable ICU 2.0
 720      */
 721     static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
 722
 723 #if !UCONFIG_NO_SERVICE
 724     /**
 725      * Register a new NumberFormatFactory.  The factory will be adopted.
 726      * @param toAdopt the NumberFormatFactory instance to be adopted
 727      * @param status the in/out status code, no special meanings are assigned
 728      * @return a registry key that can be used to unregister this factory
 729      * @stable ICU 2.6
 730      */
 731     static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
 732
 733     /**
 734      * Unregister a previously-registered NumberFormatFactory using the key returned from the
 735      * register call.  Key becomes invalid after a successful call and should not be used again.
 736      * The NumberFormatFactory corresponding to the key will be deleted.
 737      * @param key the registry key returned by a previous call to registerFactory
 738      * @param status the in/out status code, no special meanings are assigned
 739      * @return TRUE if the factory for the key was successfully unregistered
 740      * @stable ICU 2.6
 741      */
 742     static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
 743
 744     /**
 745      * Return a StringEnumeration over the locales available at the time of the call,
 746      * including registered locales.
 747      * @return a StringEnumeration over the locales available at the time of the call
 748      * @stable ICU 2.6
 749      */
 750     static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
 751 #endif /* UCONFIG_NO_SERVICE */
 752
 753     /**
 754      * Returns true if grouping is used in this format. For example,
 755      * in the English locale, with grouping on, the number 1234567
 756      * might be formatted as "1,234,567". The grouping separator as
 757      * well as the size of each group is locale dependant and is
 758      * determined by sub-classes of NumberFormat.
 759      * @see setGroupingUsed
 760      * @stable ICU 2.0
 761      */
 762     UBool isGroupingUsed(void) const;
 763
 764     /**
 765      * Set whether or not grouping will be used in this format.
 766      * @param newValue    True, grouping will be used in this format.
 767      * @see getGroupingUsed
 768      * @stable ICU 2.0
 769      */
 770     virtual void setGroupingUsed(UBool newValue);
 771
 772     /**
 773      * Returns the maximum number of digits allowed in the integer portion of a
 774      * number.
 775      * @return     the maximum number of digits allowed in the integer portion of a
 776      *             number.
 777      * @see setMaximumIntegerDigits
 778      * @stable ICU 2.0
 779      */
 780     int32_t getMaximumIntegerDigits(void) const;
 781
 782     /**
 783      * Sets the maximum number of digits allowed in the integer portion of a
 784      * number. maximumIntegerDigits must be >= minimumIntegerDigits.  If the
 785      * new value for maximumIntegerDigits is less than the current value
 786      * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
 787      * the new value.
 788      *
 789      * @param newValue    the new value for the maximum number of digits
 790      *                    allowed in the integer portion of a number.
 791      * @see getMaximumIntegerDigits
 792      * @stable ICU 2.0
 793      */
 794     virtual void setMaximumIntegerDigits(int32_t newValue);
 795
 796     /**
 797      * Returns the minimum number of digits allowed in the integer portion of a
 798      * number.
 799      * @return    the minimum number of digits allowed in the integer portion of a
 800      *            number.
 801      * @see setMinimumIntegerDigits
 802      * @stable ICU 2.0
 803      */
 804     int32_t getMinimumIntegerDigits(void) const;
 805
 806     /**
 807      * Sets the minimum number of digits allowed in the integer portion of a
 808      * number. minimumIntegerDigits must be &lt;= maximumIntegerDigits.  If the
 809      * new value for minimumIntegerDigits exceeds the current value
 810      * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
 811      * the new value.
 812      * @param newValue    the new value to be set.
 813      * @see getMinimumIntegerDigits
 814      * @stable ICU 2.0
 815      */
 816     virtual void setMinimumIntegerDigits(int32_t newValue);
 817
 818     /**
 819      * Returns the maximum number of digits allowed in the fraction portion of a
 820      * number.
 821      * @return    the maximum number of digits allowed in the fraction portion of a
 822      *            number.
 823      * @see setMaximumFractionDigits
 824      * @stable ICU 2.0
 825      */
 826     int32_t getMaximumFractionDigits(void) const;
 827
 828     /**
 829      * Sets the maximum number of digits allowed in the fraction portion of a
 830      * number. maximumFractionDigits must be >= minimumFractionDigits.  If the
 831      * new value for maximumFractionDigits is less than the current value
 832      * of minimumFractionDigits, then minimumFractionDigits will also be set to
 833      * the new value.
 834      * @param newValue    the new value to be set.
 835      * @see getMaximumFractionDigits
 836      * @stable ICU 2.0
 837      */
 838     virtual void setMaximumFractionDigits(int32_t newValue);
 839
 840     /**
 841      * Returns the minimum number of digits allowed in the fraction portion of a
 842      * number.
 843      * @return    the minimum number of digits allowed in the fraction portion of a
 844      *            number.
 845      * @see setMinimumFractionDigits
 846      * @stable ICU 2.0
 847      */
 848     int32_t getMinimumFractionDigits(void) const;
 849
 850     /**
 851      * Sets the minimum number of digits allowed in the fraction portion of a
 852      * number. minimumFractionDigits must be &lt;= maximumFractionDigits.   If the
 853      * new value for minimumFractionDigits exceeds the current value
 854      * of maximumFractionDigits, then maximumIntegerDigits will also be set to
 855      * the new value
 856      * @param newValue    the new value to be set.
 857      * @see getMinimumFractionDigits
 858      * @stable ICU 2.0
 859      */
 860     virtual void setMinimumFractionDigits(int32_t newValue);
 861
 862     /**
 863      * Sets the currency used to display currency
 864      * amounts.  This takes effect immediately, if this format is a
 865      * currency format.  If this format is not a currency format, then
 866      * the currency is used if and when this object becomes a
 867      * currency format.
 868      * @param theCurrency a 3-letter ISO code indicating new currency
 869      * to use.  It need not be null-terminated.  May be the empty
 870      * string or NULL to indicate no currency.
 871      * @param ec input-output error code
 872      * @stable ICU 3.0
 873      */
 874     virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
 875
 876     /**
 877      * Gets the currency used to display currency
 878      * amounts.  This may be an empty string for some subclasses.
 879      * @return a 3-letter null-terminated ISO code indicating
 880      * the currency in use, or a pointer to the empty string.
 881      * @stable ICU 2.6
 882      */
 883     const UChar* getCurrency() const;
 884
 885 public:
 886
 887     /**
 888      * Return the class ID for this class.  This is useful for
 889      * comparing to a return value from getDynamicClassID(). Note that,
 890      * because NumberFormat is an abstract base class, no fully constructed object
 891      * will have the class ID returned by NumberFormat::getStaticClassID().
 892      * @return The class ID for all objects of this class.
 893      * @stable ICU 2.0
 894      */
 895     static UClassID U_EXPORT2 getStaticClassID(void);
 896
 897     /**
 898      * Returns a unique class ID POLYMORPHICALLY.  Pure virtual override.
 899      * This method is to implement a simple version of RTTI, since not all
 900      * C++ compilers support genuine RTTI.  Polymorphic operator==() and
 901      * clone() methods call this method.
 902      * <P>
 903      * @return The class ID for this object. All objects of a
 904      * given class have the same class ID.  Objects of
 905      * other classes have different class IDs.
 906      * @stable ICU 2.0
 907      */
 908     virtual UClassID getDynamicClassID(void) const = 0;
 909
 910 protected:
 911
 912     /**
 913      * Default constructor for subclass use only.
 914      * @stable ICU 2.0
 915      */
 916     NumberFormat();
 917
 918     /**
 919      * Copy constructor.
 920      * @stable ICU 2.0
 921      */
 922     NumberFormat(const NumberFormat&);
 923
 924     /**
 925      * Assignment operator.
 926      * @stable ICU 2.0
 927      */
 928     NumberFormat& operator=(const NumberFormat&);
 929
 930     /**
 931      * Returns the currency in effect for this formatter.  Subclasses
 932      * should override this method as needed.  Unlike getCurrency(),
 933      * this method should never return "".
 934      * @result output parameter for null-terminated result, which must
 935      * have a capacity of at least 4
 936      * @internal
 937      */
 938     virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const;
 939
 940 private:
 941
 942     /**
 943      * Creates the specified decimal format style of the desired locale.
 944      * @param desiredLocale    the given locale.
 945      * @param choice           the given style.
 946      * @param success          Output param filled with success/failure status.
 947      * @return                 A new NumberFormat instance.
 948      */
 949     static NumberFormat* makeInstance(const Locale& desiredLocale, EStyles choice, UErrorCode& success);
 950
 951     UBool      fGroupingUsed;
 952     int32_t     fMaxIntegerDigits;
 953     int32_t     fMinIntegerDigits;
 954     int32_t     fMaxFractionDigits;
 955     int32_t     fMinFractionDigits;
 956     UBool      fParseIntegerOnly;
 957     UBool      fParseStrict;
 958
 959     // ISO currency code
 960     UChar      fCurrency[4];
 961
 962     friend class ICUNumberFormatFactory; // access to makeInstance, EStyles
 963     friend class ICUNumberFormatService;
 964 };
 965
 966 #if !UCONFIG_NO_SERVICE
 967 /**
 968  * A NumberFormatFactory is used to register new number formats.  The factory
 969  * should be able to create any of the predefined formats for each locale it
 970  * supports.  When registered, the locales it supports extend or override the
 971  * locale already supported by ICU.
 972  *
 973  * @stable ICU 2.6
 974  */
 975 class U_I18N_API NumberFormatFactory : public UObject {
 976 public:
 977
 978     /**
 979      * Destructor
 980      * @stable ICU 3.0
 981      */
 982     virtual ~NumberFormatFactory();
 983
 984     /**
 985      * Return true if this factory will be visible.  Default is true.
 986      * If not visible, the locales supported by this factory will not
 987      * be listed by getAvailableLocales.
 988      * @stable ICU 2.6
 989      */
 990     virtual UBool visible(void) const = 0;
 991
 992     /**
 993      * Return the locale names directly supported by this factory.  The number of names
 994      * is returned in count;
 995      * @stable ICU 2.6
 996      */
 997     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
 998
 999     /**
1000      * Return a number format of the appropriate type.  If the locale
1001      * is not supported, return null.  If the locale is supported, but
1002      * the type is not provided by this service, return null.  Otherwise
1003      * return an appropriate instance of NumberFormat.
1004      * @stable ICU 2.6
1005      */
1006     virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
1007 };
1008
1009 /**
1010  * A NumberFormatFactory that supports a single locale.  It can be visible or invisible.
1011  * @stable ICU 2.6
1012  */
1013 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
1014 protected:
1015     /**
1016      * True if the locale supported by this factory is visible.
1017      * @stable ICU 2.6
1018      */
1019     const UBool _visible;
1020
1021     /**
1022      * The locale supported by this factory, as a UnicodeString.
1023      * @stable ICU 2.6
1024      */
1025     UnicodeString _id;
1026
1027 public:
1028     /**
1029      * @stable ICU 2.6
1030      */
1031     SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
1032
1033     /**
1034      * @stable ICU 3.0
1035      */
1036     virtual ~SimpleNumberFormatFactory();
1037
1038     /**
1039      * @stable ICU 2.6
1040      */
1041     virtual UBool visible(void) const;
1042
1043     /**
1044      * @stable ICU 2.6
1045      */
1046     virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
1047 };
1048 #endif /* #if !UCONFIG_NO_SERVICE */
1049
1050 // -------------------------------------
1051
1052 inline UBool
1053 NumberFormat::isParseIntegerOnly() const
1054 {
1055     return fParseIntegerOnly;
1056 }
1057
1058 inline UBool
1059 NumberFormat::isParseStrict() const
1060 {
1061         return fParseStrict;
1062 }
1063
1064 inline UnicodeString&
1065 NumberFormat::format(const Formattable& obj,
1066                      UnicodeString& appendTo,
1067                      UErrorCode& status) const {
1068     return Format::format(obj, appendTo, status);
1069 }
1070
1071 U_NAMESPACE_END
1072
1073 #endif /* #if !UCONFIG_NO_FORMATTING */
1074
1075 #endif // _NUMFMT
1076 //eof