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