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