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