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