icuSources/i18n/unicode/numfmt.h

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