icuSources/i18n/unicode/numfmt.h

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