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