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 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 * 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 */ 169 class U_I18N_API NumberFormat : public Format { 170 public: 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; 525 public: 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 570 public: 571 572 /** 573 * Return a long if possible (e.g. within range LONG_MAX, 574 * LONG_MAX], and with no decimals), otherwise a double. If 575 * IntegerOnly is set, will stop at a decimal point (or equivalent; 576 * e.g. for rational numbers "1 2/3", will stop after the 1). 577 * <P> 578 * If no object can be parsed, index is unchanged, and NULL is 579 * returned. 580 * <P> 581 * This is a pure virtual which concrete subclasses must implement. 582 * 583 * @param text The text to be parsed. 584 * @param result Formattable to be set to the parse result. 585 * If parse fails, return contents are undefined. 586 * @param parsePosition The position to start parsing at on input. 587 * On output, moved to after the last successfully 588 * parse character. On parse failure, does not change. 589 * @stable ICU 2.0 590 */ 591 virtual void parse(const UnicodeString& text, 592 Formattable& result, 593 ParsePosition& parsePosition) const = 0; 594 595 /** 596 * Parse a string as a numeric value, and return a Formattable 597 * numeric object. This method parses integers only if IntegerOnly 598 * is set. 599 * 600 * @param text The text to be parsed. 601 * @param result Formattable to be set to the parse result. 602 * If parse fails, return contents are undefined. 603 * @param status Output parameter set to a failure error code 604 * when a failure occurs. 605 * @see NumberFormat::isParseIntegerOnly 606 * @stable ICU 2.0 607 */ 608 virtual void parse(const UnicodeString& text, 609 Formattable& result, 610 UErrorCode& status) const; 611 612 /** 613 * Parses text from the given string as a currency amount. Unlike 614 * the parse() method, this method will attempt to parse a generic 615 * currency name, searching for a match of this object's locale's 616 * currency display names, or for a 3-letter ISO currency code. 617 * This method will fail if this format is not a currency format, 618 * that is, if it does not contain the currency pattern symbol 619 * (U+00A4) in its prefix or suffix. 620 * 621 * @param text the string to parse 622 * @param pos input-output position; on input, the position within text 623 * to match; must have 0 <= pos.getIndex() < text.length(); 624 * on output, the position after the last matched character. 625 * If the parse fails, the position in unchanged upon output. 626 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount 627 * object (owned by the caller) containing information about 628 * the parsed currency; if parse fails, this is NULL. 629 * @stable ICU 49 630 */ 631 virtual CurrencyAmount* parseCurrency(const UnicodeString& text, 632 ParsePosition& pos) const; 633 634 /** 635 * Return true if this format will parse numbers as integers 636 * only. For example in the English locale, with ParseIntegerOnly 637 * true, the string "1234." would be parsed as the integer value 638 * 1234 and parsing would stop at the "." character. Of course, 639 * the exact format accepted by the parse operation is locale 640 * dependant and determined by sub-classes of NumberFormat. 641 * @return true if this format will parse numbers as integers 642 * only. 643 * @stable ICU 2.0 644 */ 645 UBool isParseIntegerOnly(void) const; 646 647 /** 648 * Sets whether or not numbers should be parsed as integers only. 649 * @param value set True, this format will parse numbers as integers 650 * only. 651 * @see isParseIntegerOnly 652 * @stable ICU 2.0 653 */ 654 virtual void setParseIntegerOnly(UBool value); 655 656 /** 657 * Sets whether lenient parsing should be enabled (it is off by default). 658 * 659 * @param enable <code>TRUE</code> if lenient parsing should be used, 660 * <code>FALSE</code> otherwise. 661 * @stable ICU 4.8 662 */ 663 virtual void setLenient(UBool enable); 664 665 /** 666 * Returns whether lenient parsing is enabled (it is off by default). 667 * 668 * @return <code>TRUE</code> if lenient parsing is enabled, 669 * <code>FALSE</code> otherwise. 670 * @see #setLenient 671 * @stable ICU 4.8 672 */ 673 virtual UBool isLenient(void) const; 674 675 /** 676 * Returns the default number format for the current default 677 * locale. The default format is one of the styles provided by 678 * the other factory methods: getNumberInstance, 679 * getCurrencyInstance or getPercentInstance. Exactly which one 680 * is locale dependant. 681 * @stable ICU 2.0 682 */ 683 static NumberFormat* U_EXPORT2 createInstance(UErrorCode&); 684 685 /** 686 * Returns the default number format for the specified locale. 687 * The default format is one of the styles provided by the other 688 * factory methods: getNumberInstance, getCurrencyInstance or 689 * getPercentInstance. Exactly which one is locale dependant. 690 * @param inLocale the given locale. 691 * @stable ICU 2.0 692 */ 693 static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale, 694 UErrorCode&); 695 696 /** 697 * Creates the specified decimal format style of the desired locale. 698 * @param desiredLocale the given locale. 699 * @param style the given style. 700 * @param errorCode Output param filled with success/failure status. 701 * @return A new NumberFormat instance. 702 * @stable ICU 4.8 703 */ 704 static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale, 705 UNumberFormatStyle style, 706 UErrorCode& errorCode); 707 708 /** 709 * Returns a currency format for the current default locale. 710 * @stable ICU 2.0 711 */ 712 static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&); 713 714 /** 715 * Returns a currency format for the specified locale. 716 * @param inLocale the given locale. 717 * @stable ICU 2.0 718 */ 719 static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale, 720 UErrorCode&); 721 722 /** 723 * Returns a percentage format for the current default locale. 724 * @stable ICU 2.0 725 */ 726 static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&); 727 728 /** 729 * Returns a percentage format for the specified locale. 730 * @param inLocale the given locale. 731 * @stable ICU 2.0 732 */ 733 static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale, 734 UErrorCode&); 735 736 /** 737 * Returns a scientific format for the current default locale. 738 * @stable ICU 2.0 739 */ 740 static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&); 741 742 /** 743 * Returns a scientific format for the specified locale. 744 * @param inLocale the given locale. 745 * @stable ICU 2.0 746 */ 747 static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale, 748 UErrorCode&); 749 750 /** 751 * Get the set of Locales for which NumberFormats are installed. 752 * @param count Output param to receive the size of the locales 753 * @stable ICU 2.0 754 */ 755 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); 756 757 #if !UCONFIG_NO_SERVICE 758 /** 759 * Register a new NumberFormatFactory. The factory will be adopted. 760 * @param toAdopt the NumberFormatFactory instance to be adopted 761 * @param status the in/out status code, no special meanings are assigned 762 * @return a registry key that can be used to unregister this factory 763 * @stable ICU 2.6 764 */ 765 static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status); 766 767 /** 768 * Unregister a previously-registered NumberFormatFactory using the key returned from the 769 * register call. Key becomes invalid after a successful call and should not be used again. 770 * The NumberFormatFactory corresponding to the key will be deleted. 771 * @param key the registry key returned by a previous call to registerFactory 772 * @param status the in/out status code, no special meanings are assigned 773 * @return TRUE if the factory for the key was successfully unregistered 774 * @stable ICU 2.6 775 */ 776 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status); 777 778 /** 779 * Return a StringEnumeration over the locales available at the time of the call, 780 * including registered locales. 781 * @return a StringEnumeration over the locales available at the time of the call 782 * @stable ICU 2.6 783 */ 784 static StringEnumeration* U_EXPORT2 getAvailableLocales(void); 785 #endif /* UCONFIG_NO_SERVICE */ 786 787 /** 788 * Returns true if grouping is used in this format. For example, 789 * in the English locale, with grouping on, the number 1234567 790 * might be formatted as "1,234,567". The grouping separator as 791 * well as the size of each group is locale dependant and is 792 * determined by sub-classes of NumberFormat. 793 * @see setGroupingUsed 794 * @stable ICU 2.0 795 */ 796 UBool isGroupingUsed(void) const; 797 798 /** 799 * Set whether or not grouping will be used in this format. 800 * @param newValue True, grouping will be used in this format. 801 * @see getGroupingUsed 802 * @stable ICU 2.0 803 */ 804 virtual void setGroupingUsed(UBool newValue); 805 806 /** 807 * Returns the maximum number of digits allowed in the integer portion of a 808 * number. 809 * @return the maximum number of digits allowed in the integer portion of a 810 * number. 811 * @see setMaximumIntegerDigits 812 * @stable ICU 2.0 813 */ 814 int32_t getMaximumIntegerDigits(void) const; 815 816 /** 817 * Sets the maximum number of digits allowed in the integer portion of a 818 * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the 819 * new value for maximumIntegerDigits is less than the current value 820 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to 821 * the new value. 822 * 823 * @param newValue the new value for the maximum number of digits 824 * allowed in the integer portion of a number. 825 * @see getMaximumIntegerDigits 826 * @stable ICU 2.0 827 */ 828 virtual void setMaximumIntegerDigits(int32_t newValue); 829 830 /** 831 * Returns the minimum number of digits allowed in the integer portion of a 832 * number. 833 * @return the minimum number of digits allowed in the integer portion of a 834 * number. 835 * @see setMinimumIntegerDigits 836 * @stable ICU 2.0 837 */ 838 int32_t getMinimumIntegerDigits(void) const; 839 840 /** 841 * Sets the minimum number of digits allowed in the integer portion of a 842 * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the 843 * new value for minimumIntegerDigits exceeds the current value 844 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to 845 * the new value. 846 * @param newValue the new value to be set. 847 * @see getMinimumIntegerDigits 848 * @stable ICU 2.0 849 */ 850 virtual void setMinimumIntegerDigits(int32_t newValue); 851 852 /** 853 * Returns the maximum number of digits allowed in the fraction portion of a 854 * number. 855 * @return the maximum number of digits allowed in the fraction portion of a 856 * number. 857 * @see setMaximumFractionDigits 858 * @stable ICU 2.0 859 */ 860 int32_t getMaximumFractionDigits(void) const; 861 862 /** 863 * Sets the maximum number of digits allowed in the fraction portion of a 864 * number. maximumFractionDigits must be >= minimumFractionDigits. If the 865 * new value for maximumFractionDigits is less than the current value 866 * of minimumFractionDigits, then minimumFractionDigits will also be set to 867 * the new value. 868 * @param newValue the new value to be set. 869 * @see getMaximumFractionDigits 870 * @stable ICU 2.0 871 */ 872 virtual void setMaximumFractionDigits(int32_t newValue); 873 874 /** 875 * Returns the minimum number of digits allowed in the fraction portion of a 876 * number. 877 * @return the minimum number of digits allowed in the fraction portion of a 878 * number. 879 * @see setMinimumFractionDigits 880 * @stable ICU 2.0 881 */ 882 int32_t getMinimumFractionDigits(void) const; 883 884 /** 885 * Sets the minimum number of digits allowed in the fraction portion of a 886 * number. minimumFractionDigits must be <= maximumFractionDigits. If the 887 * new value for minimumFractionDigits exceeds the current value 888 * of maximumFractionDigits, then maximumIntegerDigits will also be set to 889 * the new value 890 * @param newValue the new value to be set. 891 * @see getMinimumFractionDigits 892 * @stable ICU 2.0 893 */ 894 virtual void setMinimumFractionDigits(int32_t newValue); 895 896 /** 897 * Sets the currency used to display currency 898 * amounts. This takes effect immediately, if this format is a 899 * currency format. If this format is not a currency format, then 900 * the currency is used if and when this object becomes a 901 * currency format. 902 * @param theCurrency a 3-letter ISO code indicating new currency 903 * to use. It need not be null-terminated. May be the empty 904 * string or NULL to indicate no currency. 905 * @param ec input-output error code 906 * @stable ICU 3.0 907 */ 908 virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec); 909 910 /** 911 * Gets the currency used to display currency 912 * amounts. This may be an empty string for some subclasses. 913 * @return a 3-letter null-terminated ISO code indicating 914 * the currency in use, or a pointer to the empty string. 915 * @stable ICU 2.6 916 */ 917 const UChar* getCurrency() const; 918 919 public: 920 921 /** 922 * Return the class ID for this class. This is useful for 923 * comparing to a return value from getDynamicClassID(). Note that, 924 * because NumberFormat is an abstract base class, no fully constructed object 925 * will have the class ID returned by NumberFormat::getStaticClassID(). 926 * @return The class ID for all objects of this class. 927 * @stable ICU 2.0 928 */ 929 static UClassID U_EXPORT2 getStaticClassID(void); 930 931 /** 932 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 933 * This method is to implement a simple version of RTTI, since not all 934 * C++ compilers support genuine RTTI. Polymorphic operator==() and 935 * clone() methods call this method. 936 * <P> 937 * @return The class ID for this object. All objects of a 938 * given class have the same class ID. Objects of 939 * other classes have different class IDs. 940 * @stable ICU 2.0 941 */ 942 virtual UClassID getDynamicClassID(void) const = 0; 943 944 protected: 945 946 /** 947 * Default constructor for subclass use only. 948 * @stable ICU 2.0 949 */ 950 NumberFormat(); 951 952 /** 953 * Copy constructor. 954 * @stable ICU 2.0 955 */ 956 NumberFormat(const NumberFormat&); 957 958 /** 959 * Assignment operator. 960 * @stable ICU 2.0 961 */ 962 NumberFormat& operator=(const NumberFormat&); 963 964 /** 965 * Returns the currency in effect for this formatter. Subclasses 966 * should override this method as needed. Unlike getCurrency(), 967 * this method should never return "". 968 * @result output parameter for null-terminated result, which must 969 * have a capacity of at least 4 970 * @internal 971 */ 972 virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const; 973 974 #ifndef U_HIDE_INTERNAL_API 975 /** 976 * Creates the specified number format style of the desired locale. 977 * If mustBeDecimalFormat is TRUE, then the returned pointer is 978 * either a DecimalFormat or it is NULL. 979 * @internal 980 */ 981 static NumberFormat* makeInstance(const Locale& desiredLocale, 982 UNumberFormatStyle style, 983 UBool mustBeDecimalFormat, 984 UErrorCode& errorCode); 985 #endif /* U_HIDE_INTERNAL_API */ 986 987 private: 988 989 static UBool isStyleSupported(UNumberFormatStyle style); 990 991 /** 992 * Creates the specified decimal format style of the desired locale. 993 * @param desiredLocale the given locale. 994 * @param style the given style. 995 * @param errorCode Output param filled with success/failure status. 996 * @return A new NumberFormat instance. 997 */ 998 static NumberFormat* makeInstance(const Locale& desiredLocale, 999 UNumberFormatStyle style, 1000 UErrorCode& errorCode); 1001 1002 UBool fGroupingUsed; 1003 int32_t fMaxIntegerDigits; 1004 int32_t fMinIntegerDigits; 1005 int32_t fMaxFractionDigits; 1006 int32_t fMinFractionDigits; 1007 1008 protected: 1009 static const int32_t gDefaultMaxIntegerDigits; 1010 static const int32_t gDefaultMinIntegerDigits; 1011 1012 private: 1013 UBool fParseIntegerOnly; 1014 UBool fLenient; // TRUE => lenient parse is enabled 1015 1016 // ISO currency code 1017 UChar fCurrency[4]; 1018 1019 friend class ICUNumberFormatFactory; // access to makeInstance 1020 friend class ICUNumberFormatService; 1021 friend class ::NumberFormatTest; // access to isStyleSupported() 1022 }; 1023 1024 #if !UCONFIG_NO_SERVICE 1025 /** 1026 * A NumberFormatFactory is used to register new number formats. The factory 1027 * should be able to create any of the predefined formats for each locale it 1028 * supports. When registered, the locales it supports extend or override the 1029 * locale already supported by ICU. 1030 * 1031 * @stable ICU 2.6 1032 */ 1033 class U_I18N_API NumberFormatFactory : public UObject { 1034 public: 1035 1036 /** 1037 * Destructor 1038 * @stable ICU 3.0 1039 */ 1040 virtual ~NumberFormatFactory(); 1041 1042 /** 1043 * Return true if this factory will be visible. Default is true. 1044 * If not visible, the locales supported by this factory will not 1045 * be listed by getAvailableLocales. 1046 * @stable ICU 2.6 1047 */ 1048 virtual UBool visible(void) const = 0; 1049 1050 /** 1051 * Return the locale names directly supported by this factory. The number of names 1052 * is returned in count; 1053 * @stable ICU 2.6 1054 */ 1055 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0; 1056 1057 /** 1058 * Return a number format of the appropriate type. If the locale 1059 * is not supported, return null. If the locale is supported, but 1060 * the type is not provided by this service, return null. Otherwise 1061 * return an appropriate instance of NumberFormat. 1062 * @stable ICU 2.6 1063 */ 1064 virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0; 1065 }; 1066 1067 /** 1068 * A NumberFormatFactory that supports a single locale. It can be visible or invisible. 1069 * @stable ICU 2.6 1070 */ 1071 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory { 1072 protected: 1073 /** 1074 * True if the locale supported by this factory is visible. 1075 * @stable ICU 2.6 1076 */ 1077 const UBool _visible; 1078 1079 /** 1080 * The locale supported by this factory, as a UnicodeString. 1081 * @stable ICU 2.6 1082 */ 1083 UnicodeString _id; 1084 1085 public: 1086 /** 1087 * @stable ICU 2.6 1088 */ 1089 SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE); 1090 1091 /** 1092 * @stable ICU 3.0 1093 */ 1094 virtual ~SimpleNumberFormatFactory(); 1095 1096 /** 1097 * @stable ICU 2.6 1098 */ 1099 virtual UBool visible(void) const; 1100 1101 /** 1102 * @stable ICU 2.6 1103 */ 1104 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const; 1105 }; 1106 #endif /* #if !UCONFIG_NO_SERVICE */ 1107 1108 // ------------------------------------- 1109 1110 inline UBool 1111 NumberFormat::isParseIntegerOnly() const 1112 { 1113 return fParseIntegerOnly; 1114 } 1115 1116 inline UBool 1117 NumberFormat::isLenient() const 1118 { 1119 return fLenient; 1120 } 1121 1122 U_NAMESPACE_END 1123 1124 #endif /* #if !UCONFIG_NO_FORMATTING */ 1125 1126 #endif // _NUMFMT 1127 //eof 1128