icuSources/i18n/unicode/numfmt.h

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