icuSources/i18n/unicode/numfmt.h

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