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