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 6 * Corporation and others. All Rights Reserved. 7 ******************************************************************************** 8 * 9 * File DECIMFMT.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 02/19/97 aliu Converted from java. 15 * 03/20/97 clhuang Updated per C++ implementation. 16 * 04/03/97 aliu Rewrote parsing and formatting completely, and 17 * cleaned up and debugged. Actually works now. 18 * 04/17/97 aliu Changed DigitCount to int per code review. 19 * 07/10/97 helena Made ParsePosition a class and get rid of the function 20 * hiding problems. 21 * 09/09/97 aliu Ported over support for exponential formats. 22 * 07/20/98 stephen Changed documentation 23 * 01/30/13 emmons Added Scaling methods 24 ******************************************************************************** 25 */ 26 27 #ifndef DECIMFMT_H 28 #define DECIMFMT_H 29 30 #include "unicode/utypes.h" 31 /** 32 * \file 33 * \brief C++ API: Compatibility APIs for decimal formatting. 34 */ 35 36 #if !UCONFIG_NO_FORMATTING 37 38 #include "unicode/dcfmtsym.h" 39 #include "unicode/numfmt.h" 40 #include "unicode/locid.h" 41 #include "unicode/fpositer.h" 42 #include "unicode/stringpiece.h" 43 #include "unicode/curramt.h" 44 #include "unicode/enumset.h" 45 46 U_NAMESPACE_BEGIN 47 48 class CurrencyPluralInfo; 49 class CompactDecimalFormat; 50 51 namespace number { 52 class LocalizedNumberFormatter; 53 class FormattedNumber; 54 namespace impl { 55 class DecimalQuantity; 56 struct DecimalFormatFields; 57 } 58 } 59 60 namespace numparse { 61 namespace impl { 62 class NumberParserImpl; 63 } 64 } 65 66 /** 67 * \cond 68 * explicit template instantiation. see digitlst.h 69 * (When building DLLs for Windows this is required.) 70 */ 71 #if U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN && !defined(U_IN_DOXYGEN) 72 template class U_I18N_API EnumSet<UNumberFormatAttribute, 73 UNUM_MAX_NONBOOLEAN_ATTRIBUTE+1, 74 UNUM_LIMIT_BOOLEAN_ATTRIBUTE>; 75 #endif 76 /** \endcond */ 77 78 /** 79 * **IMPORTANT:** New users are strongly encouraged to see if 80 * numberformatter.h fits their use case. Although not deprecated, this header 81 * is provided for backwards compatibility only. 82 * 83 * DecimalFormat is a concrete subclass of NumberFormat that formats decimal 84 * numbers. It has a variety of features designed to make it possible to parse 85 * and format numbers in any locale, including support for Western, Arabic, or 86 * Indic digits. It also supports different flavors of numbers, including 87 * integers ("123"), fixed-point numbers ("123.4"), scientific notation 88 * ("1.23E4"), percentages ("12%"), and currency amounts ("$123", "USD123", 89 * "123 US dollars"). All of these flavors can be easily localized. 90 * 91 * To obtain a NumberFormat for a specific locale (including the default 92 * locale) call one of NumberFormat's factory methods such as 93 * createInstance(). Do not call the DecimalFormat constructors directly, unless 94 * you know what you are doing, since the NumberFormat factory methods may 95 * return subclasses other than DecimalFormat. 96 * 97 * **Example Usage** 98 * 99 * \code 100 * // Normally we would have a GUI with a menu for this 101 * int32_t locCount; 102 * const Locale* locales = NumberFormat::getAvailableLocales(locCount); 103 * 104 * double myNumber = -1234.56; 105 * UErrorCode success = U_ZERO_ERROR; 106 * NumberFormat* form; 107 * 108 * // Print out a number with the localized number, currency and percent 109 * // format for each locale. 110 * UnicodeString countryName; 111 * UnicodeString displayName; 112 * UnicodeString str; 113 * UnicodeString pattern; 114 * Formattable fmtable; 115 * for (int32_t j = 0; j < 3; ++j) { 116 * cout << endl << "FORMAT " << j << endl; 117 * for (int32_t i = 0; i < locCount; ++i) { 118 * if (locales[i].getCountry(countryName).size() == 0) { 119 * // skip language-only 120 * continue; 121 * } 122 * switch (j) { 123 * case 0: 124 * form = NumberFormat::createInstance(locales[i], success ); break; 125 * case 1: 126 * form = NumberFormat::createCurrencyInstance(locales[i], success ); break; 127 * default: 128 * form = NumberFormat::createPercentInstance(locales[i], success ); break; 129 * } 130 * if (form) { 131 * str.remove(); 132 * pattern = ((DecimalFormat*)form)->toPattern(pattern); 133 * cout << locales[i].getDisplayName(displayName) << ": " << pattern; 134 * cout << " -> " << form->format(myNumber,str) << endl; 135 * form->parse(form->format(myNumber,str), fmtable, success); 136 * delete form; 137 * } 138 * } 139 * } 140 * \endcode 141 * 142 * **Another example use createInstance(style)** 143 * 144 * \code 145 * // Print out a number using the localized number, currency, 146 * // percent, scientific, integer, iso currency, and plural currency 147 * // format for each locale</strong> 148 * Locale* locale = new Locale("en", "US"); 149 * double myNumber = 1234.56; 150 * UErrorCode success = U_ZERO_ERROR; 151 * UnicodeString str; 152 * Formattable fmtable; 153 * for (int j=NumberFormat::kNumberStyle; 154 * j<=NumberFormat::kPluralCurrencyStyle; 155 * ++j) { 156 * NumberFormat* form = NumberFormat::createInstance(locale, j, success); 157 * str.remove(); 158 * cout << "format result " << form->format(myNumber, str) << endl; 159 * format->parse(form->format(myNumber, str), fmtable, success); 160 * delete form; 161 * } 162 * \endcode 163 * 164 * 165 * <p><strong>Patterns</strong> 166 * 167 * <p>A DecimalFormat consists of a <em>pattern</em> and a set of 168 * <em>symbols</em>. The pattern may be set directly using 169 * applyPattern(), or indirectly using other API methods which 170 * manipulate aspects of the pattern, such as the minimum number of integer 171 * digits. The symbols are stored in a DecimalFormatSymbols 172 * object. When using the NumberFormat factory methods, the 173 * pattern and symbols are read from ICU's locale data. 174 * 175 * <p><strong>Special Pattern Characters</strong> 176 * 177 * <p>Many characters in a pattern are taken literally; they are matched during 178 * parsing and output unchanged during formatting. Special characters, on the 179 * other hand, stand for other characters, strings, or classes of characters. 180 * For example, the '#' character is replaced by a localized digit. Often the 181 * replacement character is the same as the pattern character; in the U.S. locale, 182 * the ',' grouping character is replaced by ','. However, the replacement is 183 * still happening, and if the symbols are modified, the grouping character 184 * changes. Some special characters affect the behavior of the formatter by 185 * their presence; for example, if the percent character is seen, then the 186 * value is multiplied by 100 before being displayed. 187 * 188 * <p>To insert a special character in a pattern as a literal, that is, without 189 * any special meaning, the character must be quoted. There are some exceptions to 190 * this which are noted below. 191 * 192 * <p>The characters listed here are used in non-localized patterns. Localized 193 * patterns use the corresponding characters taken from this formatter's 194 * DecimalFormatSymbols object instead, and these characters lose 195 * their special status. Two exceptions are the currency sign and quote, which 196 * are not localized. 197 * 198 * <table border=0 cellspacing=3 cellpadding=0> 199 * <tr bgcolor="#ccccff"> 200 * <td align=left><strong>Symbol</strong> 201 * <td align=left><strong>Location</strong> 202 * <td align=left><strong>Localized?</strong> 203 * <td align=left><strong>Meaning</strong> 204 * <tr valign=top> 205 * <td><code>0</code> 206 * <td>Number 207 * <td>Yes 208 * <td>Digit 209 * <tr valign=top bgcolor="#eeeeff"> 210 * <td><code>1-9</code> 211 * <td>Number 212 * <td>Yes 213 * <td>'1' through '9' indicate rounding. 214 * <tr valign=top> 215 * <td><code>\htmlonly@\endhtmlonly</code> <!--doxygen doesn't like @--> 216 * <td>Number 217 * <td>No 218 * <td>Significant digit 219 * <tr valign=top bgcolor="#eeeeff"> 220 * <td><code>#</code> 221 * <td>Number 222 * <td>Yes 223 * <td>Digit, zero shows as absent 224 * <tr valign=top> 225 * <td><code>.</code> 226 * <td>Number 227 * <td>Yes 228 * <td>Decimal separator or monetary decimal separator 229 * <tr valign=top bgcolor="#eeeeff"> 230 * <td><code>-</code> 231 * <td>Number 232 * <td>Yes 233 * <td>Minus sign 234 * <tr valign=top> 235 * <td><code>,</code> 236 * <td>Number 237 * <td>Yes 238 * <td>Grouping separator 239 * <tr valign=top bgcolor="#eeeeff"> 240 * <td><code>E</code> 241 * <td>Number 242 * <td>Yes 243 * <td>Separates mantissa and exponent in scientific notation. 244 * <em>Need not be quoted in prefix or suffix.</em> 245 * <tr valign=top> 246 * <td><code>+</code> 247 * <td>Exponent 248 * <td>Yes 249 * <td>Prefix positive exponents with localized plus sign. 250 * <em>Need not be quoted in prefix or suffix.</em> 251 * <tr valign=top bgcolor="#eeeeff"> 252 * <td><code>;</code> 253 * <td>Subpattern boundary 254 * <td>Yes 255 * <td>Separates positive and negative subpatterns 256 * <tr valign=top> 257 * <td><code>\%</code> 258 * <td>Prefix or suffix 259 * <td>Yes 260 * <td>Multiply by 100 and show as percentage 261 * <tr valign=top bgcolor="#eeeeff"> 262 * <td><code>\\u2030</code> 263 * <td>Prefix or suffix 264 * <td>Yes 265 * <td>Multiply by 1000 and show as per mille 266 * <tr valign=top> 267 * <td><code>\htmlonly¤\endhtmlonly</code> (<code>\\u00A4</code>) 268 * <td>Prefix or suffix 269 * <td>No 270 * <td>Currency sign, replaced by currency symbol. If 271 * doubled, replaced by international currency symbol. 272 * If tripled, replaced by currency plural names, for example, 273 * "US dollar" or "US dollars" for America. 274 * If present in a pattern, the monetary decimal separator 275 * is used instead of the decimal separator. 276 * <tr valign=top bgcolor="#eeeeff"> 277 * <td><code>'</code> 278 * <td>Prefix or suffix 279 * <td>No 280 * <td>Used to quote special characters in a prefix or suffix, 281 * for example, <code>"'#'#"</code> formats 123 to 282 * <code>"#123"</code>. To create a single quote 283 * itself, use two in a row: <code>"# o''clock"</code>. 284 * <tr valign=top> 285 * <td><code>*</code> 286 * <td>Prefix or suffix boundary 287 * <td>Yes 288 * <td>Pad escape, precedes pad character 289 * </table> 290 * 291 * <p>A DecimalFormat pattern contains a postive and negative 292 * subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a 293 * prefix, a numeric part, and a suffix. If there is no explicit negative 294 * subpattern, the negative subpattern is the localized minus sign prefixed to the 295 * positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there 296 * is an explicit negative subpattern, it serves only to specify the negative 297 * prefix and suffix; the number of digits, minimal digits, and other 298 * characteristics are ignored in the negative subpattern. That means that 299 * "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)". 300 * 301 * <p>The prefixes, suffixes, and various symbols used for infinity, digits, 302 * thousands separators, decimal separators, etc. may be set to arbitrary 303 * values, and they will appear properly during formatting. However, care must 304 * be taken that the symbols and strings do not conflict, or parsing will be 305 * unreliable. For example, either the positive and negative prefixes or the 306 * suffixes must be distinct for parse() to be able 307 * to distinguish positive from negative values. Another example is that the 308 * decimal separator and thousands separator should be distinct characters, or 309 * parsing will be impossible. 310 * 311 * <p>The <em>grouping separator</em> is a character that separates clusters of 312 * integer digits to make large numbers more legible. It commonly used for 313 * thousands, but in some locales it separates ten-thousands. The <em>grouping 314 * size</em> is the number of digits between the grouping separators, such as 3 315 * for "100,000,000" or 4 for "1 0000 0000". There are actually two different 316 * grouping sizes: One used for the least significant integer digits, the 317 * <em>primary grouping size</em>, and one used for all others, the 318 * <em>secondary grouping size</em>. In most locales these are the same, but 319 * sometimes they are different. For example, if the primary grouping interval 320 * is 3, and the secondary is 2, then this corresponds to the pattern 321 * "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a 322 * pattern contains multiple grouping separators, the interval between the last 323 * one and the end of the integer defines the primary grouping size, and the 324 * interval between the last two defines the secondary grouping size. All others 325 * are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####". 326 * 327 * <p>Illegal patterns, such as "#.#.#" or "#.###,###", will cause 328 * DecimalFormat to set a failing UErrorCode. 329 * 330 * <p><strong>Pattern BNF</strong> 331 * 332 * <pre> 333 * pattern := subpattern (';' subpattern)? 334 * subpattern := prefix? number exponent? suffix? 335 * number := (integer ('.' fraction)?) | sigDigits 336 * prefix := '\\u0000'..'\\uFFFD' - specialCharacters 337 * suffix := '\\u0000'..'\\uFFFD' - specialCharacters 338 * integer := '#'* '0'* '0' 339 * fraction := '0'* '#'* 340 * sigDigits := '#'* '@' '@'* '#'* 341 * exponent := 'E' '+'? '0'* '0' 342 * padSpec := '*' padChar 343 * padChar := '\\u0000'..'\\uFFFD' - quote 344 * 345 * Notation: 346 * X* 0 or more instances of X 347 * X? 0 or 1 instances of X 348 * X|Y either X or Y 349 * C..D any character from C up to D, inclusive 350 * S-T characters in S, except those in T 351 * </pre> 352 * The first subpattern is for positive numbers. The second (optional) 353 * subpattern is for negative numbers. 354 * 355 * <p>Not indicated in the BNF syntax above: 356 * 357 * <ul><li>The grouping separator ',' can occur inside the integer and 358 * sigDigits elements, between any two pattern characters of that 359 * element, as long as the integer or sigDigits element is not 360 * followed by the exponent element. 361 * 362 * <li>Two grouping intervals are recognized: That between the 363 * decimal point and the first grouping symbol, and that 364 * between the first and second grouping symbols. These 365 * intervals are identical in most locales, but in some 366 * locales they differ. For example, the pattern 367 * "#,##,###" formats the number 123456789 as 368 * "12,34,56,789".</li> 369 * 370 * <li>The pad specifier <code>padSpec</code> may appear before the prefix, 371 * after the prefix, before the suffix, after the suffix, or not at all. 372 * 373 * <li>In place of '0', the digits '1' through '9' may be used to 374 * indicate a rounding increment. 375 * </ul> 376 * 377 * <p><strong>Parsing</strong> 378 * 379 * <p>DecimalFormat parses all Unicode characters that represent 380 * decimal digits, as defined by u_charDigitValue(). In addition, 381 * DecimalFormat also recognizes as digits the ten consecutive 382 * characters starting with the localized zero digit defined in the 383 * DecimalFormatSymbols object. During formatting, the 384 * DecimalFormatSymbols-based digits are output. 385 * 386 * <p>During parsing, grouping separators are ignored if in lenient mode; 387 * otherwise, if present, they must be in appropriate positions. 388 * 389 * <p>For currency parsing, the formatter is able to parse every currency 390 * style formats no matter which style the formatter is constructed with. 391 * For example, a formatter instance gotten from 392 * NumberFormat.getInstance(ULocale, NumberFormat.CURRENCYSTYLE) can parse 393 * formats such as "USD1.00" and "3.00 US dollars". 394 * 395 * <p>If parse(UnicodeString&,Formattable&,ParsePosition&) 396 * fails to parse a string, it leaves the parse position unchanged. 397 * The convenience method parse(UnicodeString&,Formattable&,UErrorCode&) 398 * indicates parse failure by setting a failing 399 * UErrorCode. 400 * 401 * <p><strong>Formatting</strong> 402 * 403 * <p>Formatting is guided by several parameters, all of which can be 404 * specified either using a pattern or using the API. The following 405 * description applies to formats that do not use <a href="#sci">scientific 406 * notation</a> or <a href="#sigdig">significant digits</a>. 407 * 408 * <ul><li>If the number of actual integer digits exceeds the 409 * <em>maximum integer digits</em>, then only the least significant 410 * digits are shown. For example, 1997 is formatted as "97" if the 411 * maximum integer digits is set to 2. 412 * 413 * <li>If the number of actual integer digits is less than the 414 * <em>minimum integer digits</em>, then leading zeros are added. For 415 * example, 1997 is formatted as "01997" if the minimum integer digits 416 * is set to 5. 417 * 418 * <li>If the number of actual fraction digits exceeds the <em>maximum 419 * fraction digits</em>, then rounding is performed to the 420 * maximum fraction digits. For example, 0.125 is formatted as "0.12" 421 * if the maximum fraction digits is 2. This behavior can be changed 422 * by specifying a rounding increment and/or a rounding mode. 423 * 424 * <li>If the number of actual fraction digits is less than the 425 * <em>minimum fraction digits</em>, then trailing zeros are added. 426 * For example, 0.125 is formatted as "0.1250" if the mimimum fraction 427 * digits is set to 4. 428 * 429 * <li>Trailing fractional zeros are not displayed if they occur 430 * <em>j</em> positions after the decimal, where <em>j</em> is less 431 * than the maximum fraction digits. For example, 0.10004 is 432 * formatted as "0.1" if the maximum fraction digits is four or less. 433 * </ul> 434 * 435 * <p><strong>Special Values</strong> 436 * 437 * <p><code>NaN</code> is represented as a single character, typically 438 * <code>\\uFFFD</code>. This character is determined by the 439 * DecimalFormatSymbols object. This is the only value for which 440 * the prefixes and suffixes are not used. 441 * 442 * <p>Infinity is represented as a single character, typically 443 * <code>\\u221E</code>, with the positive or negative prefixes and suffixes 444 * applied. The infinity character is determined by the 445 * DecimalFormatSymbols object. 446 * 447 * <a name="sci"><strong>Scientific Notation</strong></a> 448 * 449 * <p>Numbers in scientific notation are expressed as the product of a mantissa 450 * and a power of ten, for example, 1234 can be expressed as 1.234 x 10<sup>3</sup>. The 451 * mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), 452 * but it need not be. DecimalFormat supports arbitrary mantissas. 453 * DecimalFormat can be instructed to use scientific 454 * notation through the API or through the pattern. In a pattern, the exponent 455 * character immediately followed by one or more digit characters indicates 456 * scientific notation. Example: "0.###E0" formats the number 1234 as 457 * "1.234E3". 458 * 459 * <ul> 460 * <li>The number of digit characters after the exponent character gives the 461 * minimum exponent digit count. There is no maximum. Negative exponents are 462 * formatted using the localized minus sign, <em>not</em> the prefix and suffix 463 * from the pattern. This allows patterns such as "0.###E0 m/s". To prefix 464 * positive exponents with a localized plus sign, specify '+' between the 465 * exponent and the digits: "0.###E+0" will produce formats "1E+1", "1E+0", 466 * "1E-1", etc. (In localized patterns, use the localized plus sign rather than 467 * '+'.) 468 * 469 * <li>The minimum number of integer digits is achieved by adjusting the 470 * exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This 471 * only happens if there is no maximum number of integer digits. If there is a 472 * maximum, then the minimum number of integer digits is fixed at one. 473 * 474 * <li>The maximum number of integer digits, if present, specifies the exponent 475 * grouping. The most common use of this is to generate <em>engineering 476 * notation</em>, in which the exponent is a multiple of three, e.g., 477 * "##0.###E0". The number 12345 is formatted using "##0.####E0" as "12.345E3". 478 * 479 * <li>When using scientific notation, the formatter controls the 480 * digit counts using significant digits logic. The maximum number of 481 * significant digits limits the total number of integer and fraction 482 * digits that will be shown in the mantissa; it does not affect 483 * parsing. For example, 12345 formatted with "##0.##E0" is "12.3E3". 484 * See the section on significant digits for more details. 485 * 486 * <li>The number of significant digits shown is determined as 487 * follows: If areSignificantDigitsUsed() returns false, then the 488 * minimum number of significant digits shown is one, and the maximum 489 * number of significant digits shown is the sum of the <em>minimum 490 * integer</em> and <em>maximum fraction</em> digits, and is 491 * unaffected by the maximum integer digits. If this sum is zero, 492 * then all significant digits are shown. If 493 * areSignificantDigitsUsed() returns true, then the significant digit 494 * counts are specified by getMinimumSignificantDigits() and 495 * getMaximumSignificantDigits(). In this case, the number of 496 * integer digits is fixed at one, and there is no exponent grouping. 497 * 498 * <li>Exponential patterns may not contain grouping separators. 499 * </ul> 500 * 501 * <a name="sigdig"><strong>Significant Digits</strong></a> 502 * 503 * <code>DecimalFormat</code> has two ways of controlling how many 504 * digits are shows: (a) significant digits counts, or (b) integer and 505 * fraction digit counts. Integer and fraction digit counts are 506 * described above. When a formatter is using significant digits 507 * counts, the number of integer and fraction digits is not specified 508 * directly, and the formatter settings for these counts are ignored. 509 * Instead, the formatter uses however many integer and fraction 510 * digits are required to display the specified number of significant 511 * digits. Examples: 512 * 513 * <table border=0 cellspacing=3 cellpadding=0> 514 * <tr bgcolor="#ccccff"> 515 * <td align=left>Pattern 516 * <td align=left>Minimum significant digits 517 * <td align=left>Maximum significant digits 518 * <td align=left>Number 519 * <td align=left>Output of format() 520 * <tr valign=top> 521 * <td><code>\@\@\@</code> 522 * <td>3 523 * <td>3 524 * <td>12345 525 * <td><code>12300</code> 526 * <tr valign=top bgcolor="#eeeeff"> 527 * <td><code>\@\@\@</code> 528 * <td>3 529 * <td>3 530 * <td>0.12345 531 * <td><code>0.123</code> 532 * <tr valign=top> 533 * <td><code>\@\@##</code> 534 * <td>2 535 * <td>4 536 * <td>3.14159 537 * <td><code>3.142</code> 538 * <tr valign=top bgcolor="#eeeeff"> 539 * <td><code>\@\@##</code> 540 * <td>2 541 * <td>4 542 * <td>1.23004 543 * <td><code>1.23</code> 544 * </table> 545 * 546 * <ul> 547 * <li>Significant digit counts may be expressed using patterns that 548 * specify a minimum and maximum number of significant digits. These 549 * are indicated by the <code>'@'</code> and <code>'#'</code> 550 * characters. The minimum number of significant digits is the number 551 * of <code>'@'</code> characters. The maximum number of significant 552 * digits is the number of <code>'@'</code> characters plus the number 553 * of <code>'#'</code> characters following on the right. For 554 * example, the pattern <code>"@@@"</code> indicates exactly 3 555 * significant digits. The pattern <code>"@##"</code> indicates from 556 * 1 to 3 significant digits. Trailing zero digits to the right of 557 * the decimal separator are suppressed after the minimum number of 558 * significant digits have been shown. For example, the pattern 559 * <code>"@##"</code> formats the number 0.1203 as 560 * <code>"0.12"</code>. 561 * 562 * <li>If a pattern uses significant digits, it may not contain a 563 * decimal separator, nor the <code>'0'</code> pattern character. 564 * Patterns such as <code>"@00"</code> or <code>"@.###"</code> are 565 * disallowed. 566 * 567 * <li>Any number of <code>'#'</code> characters may be prepended to 568 * the left of the leftmost <code>'@'</code> character. These have no 569 * effect on the minimum and maximum significant digits counts, but 570 * may be used to position grouping separators. For example, 571 * <code>"#,#@#"</code> indicates a minimum of one significant digits, 572 * a maximum of two significant digits, and a grouping size of three. 573 * 574 * <li>In order to enable significant digits formatting, use a pattern 575 * containing the <code>'@'</code> pattern character. Alternatively, 576 * call setSignificantDigitsUsed(TRUE). 577 * 578 * <li>In order to disable significant digits formatting, use a 579 * pattern that does not contain the <code>'@'</code> pattern 580 * character. Alternatively, call setSignificantDigitsUsed(FALSE). 581 * 582 * <li>The number of significant digits has no effect on parsing. 583 * 584 * <li>Significant digits may be used together with exponential notation. Such 585 * patterns are equivalent to a normal exponential pattern with a minimum and 586 * maximum integer digit count of one, a minimum fraction digit count of 587 * <code>getMinimumSignificantDigits() - 1</code>, and a maximum fraction digit 588 * count of <code>getMaximumSignificantDigits() - 1</code>. For example, the 589 * pattern <code>"@@###E0"</code> is equivalent to <code>"0.0###E0"</code>. 590 * 591 * <li>If signficant digits are in use, then the integer and fraction 592 * digit counts, as set via the API, are ignored. If significant 593 * digits are not in use, then the signficant digit counts, as set via 594 * the API, are ignored. 595 * 596 * </ul> 597 * 598 * <p><strong>Padding</strong> 599 * 600 * <p>DecimalFormat supports padding the result of 601 * format() to a specific width. Padding may be specified either 602 * through the API or through the pattern syntax. In a pattern the pad escape 603 * character, followed by a single pad character, causes padding to be parsed 604 * and formatted. The pad escape character is '*' in unlocalized patterns, and 605 * can be localized using DecimalFormatSymbols::setSymbol() with a 606 * DecimalFormatSymbols::kPadEscapeSymbol 607 * selector. For example, <code>"$*x#,##0.00"</code> formats 123 to 608 * <code>"$xx123.00"</code>, and 1234 to <code>"$1,234.00"</code>. 609 * 610 * <ul> 611 * <li>When padding is in effect, the width of the positive subpattern, 612 * including prefix and suffix, determines the format width. For example, in 613 * the pattern <code>"* #0 o''clock"</code>, the format width is 10. 614 * 615 * <li>The width is counted in 16-bit code units (char16_ts). 616 * 617 * <li>Some parameters which usually do not matter have meaning when padding is 618 * used, because the pattern width is significant with padding. In the pattern 619 * "* ##,##,#,##0.##", the format width is 14. The initial characters "##,##," 620 * do not affect the grouping size or maximum integer digits, but they do affect 621 * the format width. 622 * 623 * <li>Padding may be inserted at one of four locations: before the prefix, 624 * after the prefix, before the suffix, or after the suffix. If padding is 625 * specified in any other location, applyPattern() 626 * sets a failing UErrorCode. If there is no prefix, 627 * before the prefix and after the prefix are equivalent, likewise for the 628 * suffix. 629 * 630 * <li>When specified in a pattern, the 32-bit code point immediately 631 * following the pad escape is the pad character. This may be any character, 632 * including a special pattern character. That is, the pad escape 633 * <em>escapes</em> the following character. If there is no character after 634 * the pad escape, then the pattern is illegal. 635 * 636 * </ul> 637 * 638 * <p><strong>Rounding</strong> 639 * 640 * <p>DecimalFormat supports rounding to a specific increment. For 641 * example, 1230 rounded to the nearest 50 is 1250. 1.234 rounded to the 642 * nearest 0.65 is 1.3. The rounding increment may be specified through the API 643 * or in a pattern. To specify a rounding increment in a pattern, include the 644 * increment in the pattern itself. "#,#50" specifies a rounding increment of 645 * 50. "#,##0.05" specifies a rounding increment of 0.05. 646 * 647 * <p>In the absense of an explicit rounding increment numbers are 648 * rounded to their formatted width. 649 * 650 * <ul> 651 * <li>Rounding only affects the string produced by formatting. It does 652 * not affect parsing or change any numerical values. 653 * 654 * <li>A <em>rounding mode</em> determines how values are rounded; see 655 * DecimalFormat::ERoundingMode. The default rounding mode is 656 * DecimalFormat::kRoundHalfEven. The rounding mode can only be set 657 * through the API; it can not be set with a pattern. 658 * 659 * <li>Some locales use rounding in their currency formats to reflect the 660 * smallest currency denomination. 661 * 662 * <li>In a pattern, digits '1' through '9' specify rounding, but otherwise 663 * behave identically to digit '0'. 664 * </ul> 665 * 666 * <p><strong>Synchronization</strong> 667 * 668 * <p>DecimalFormat objects are not synchronized. Multiple 669 * threads should not access one formatter concurrently. 670 * 671 * <p><strong>Subclassing</strong> 672 * 673 * <p><em>User subclasses are not supported.</em> While clients may write 674 * subclasses, such code will not necessarily work and will not be 675 * guaranteed to work stably from release to release. 676 */ 677 class U_I18N_API DecimalFormat : public NumberFormat { 678 public: 679 /** 680 * Pad position. 681 * @stable ICU 2.4 682 */ 683 enum EPadPosition { 684 kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, kPadAfterSuffix 685 }; 686 687 /** 688 * Create a DecimalFormat using the default pattern and symbols 689 * for the default locale. This is a convenient way to obtain a 690 * DecimalFormat when internationalization is not the main concern. 691 * <P> 692 * To obtain standard formats for a given locale, use the factory methods 693 * on NumberFormat such as createInstance. These factories will 694 * return the most appropriate sub-class of NumberFormat for a given 695 * locale. 696 * <p> 697 * <strong>NOTE:</strong> New users are strongly encouraged to use 698 * #icu::number::NumberFormatter instead of DecimalFormat. 699 * @param status Output param set to success/failure code. If the 700 * pattern is invalid this will be set to a failure code. 701 * @stable ICU 2.0 702 */ 703 DecimalFormat(UErrorCode& status); 704 705 /** 706 * Create a DecimalFormat from the given pattern and the symbols 707 * for the default locale. This is a convenient way to obtain a 708 * DecimalFormat when internationalization is not the main concern. 709 * <P> 710 * To obtain standard formats for a given locale, use the factory methods 711 * on NumberFormat such as createInstance. These factories will 712 * return the most appropriate sub-class of NumberFormat for a given 713 * locale. 714 * <p> 715 * <strong>NOTE:</strong> New users are strongly encouraged to use 716 * #icu::number::NumberFormatter instead of DecimalFormat. 717 * @param pattern A non-localized pattern string. 718 * @param status Output param set to success/failure code. If the 719 * pattern is invalid this will be set to a failure code. 720 * @stable ICU 2.0 721 */ 722 DecimalFormat(const UnicodeString& pattern, UErrorCode& status); 723 724 /** 725 * Create a DecimalFormat from the given pattern and symbols. 726 * Use this constructor when you need to completely customize the 727 * behavior of the format. 728 * <P> 729 * To obtain standard formats for a given 730 * locale, use the factory methods on NumberFormat such as 731 * createInstance or createCurrencyInstance. If you need only minor adjustments 732 * to a standard format, you can modify the format returned by 733 * a NumberFormat factory method. 734 * <p> 735 * <strong>NOTE:</strong> New users are strongly encouraged to use 736 * #icu::number::NumberFormatter instead of DecimalFormat. 737 * 738 * @param pattern a non-localized pattern string 739 * @param symbolsToAdopt the set of symbols to be used. The caller should not 740 * delete this object after making this call. 741 * @param status Output param set to success/failure code. If the 742 * pattern is invalid this will be set to a failure code. 743 * @stable ICU 2.0 744 */ 745 DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, UErrorCode& status); 746 747 #ifndef U_HIDE_INTERNAL_API 748 749 /** 750 * This API is for ICU use only. 751 * Create a DecimalFormat from the given pattern, symbols, and style. 752 * 753 * @param pattern a non-localized pattern string 754 * @param symbolsToAdopt the set of symbols to be used. The caller should not 755 * delete this object after making this call. 756 * @param style style of decimal format 757 * @param status Output param set to success/failure code. If the 758 * pattern is invalid this will be set to a failure code. 759 * @internal 760 */ 761 DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, 762 UNumberFormatStyle style, UErrorCode& status); 763 764 #if UCONFIG_HAVE_PARSEALLINPUT 765 766 /** 767 * @internal 768 */ 769 void setParseAllInput(UNumberFormatAttributeValue value); 770 771 #endif 772 773 #endif /* U_HIDE_INTERNAL_API */ 774 775 private: 776 777 /** 778 * Internal constructor for DecimalFormat; sets up internal fields. All public constructors should 779 * call this constructor. 780 */ 781 DecimalFormat(const DecimalFormatSymbols* symbolsToAdopt, UErrorCode& status); 782 783 public: 784 785 /** 786 * Set an integer attribute on this DecimalFormat. 787 * May return U_UNSUPPORTED_ERROR if this instance does not support 788 * the specified attribute. 789 * @param attr the attribute to set 790 * @param newValue new value 791 * @param status the error type 792 * @return *this - for chaining (example: format.setAttribute(...).setAttribute(...) ) 793 * @stable ICU 51 794 */ 795 virtual DecimalFormat& setAttribute(UNumberFormatAttribute attr, int32_t newValue, UErrorCode& status); 796 797 /** 798 * Get an integer 799 * May return U_UNSUPPORTED_ERROR if this instance does not support 800 * the specified attribute. 801 * @param attr the attribute to set 802 * @param status the error type 803 * @return the attribute value. Undefined if there is an error. 804 * @stable ICU 51 805 */ 806 virtual int32_t getAttribute(UNumberFormatAttribute attr, UErrorCode& status) const; 807 808 809 /** 810 * Set whether or not grouping will be used in this format. 811 * @param newValue True, grouping will be used in this format. 812 * @see getGroupingUsed 813 * @stable ICU 53 814 */ 815 void setGroupingUsed(UBool newValue) U_OVERRIDE; 816 817 /** 818 * Sets whether or not numbers should be parsed as integers only. 819 * @param value set True, this format will parse numbers as integers 820 * only. 821 * @see isParseIntegerOnly 822 * @stable ICU 53 823 */ 824 void setParseIntegerOnly(UBool value) U_OVERRIDE; 825 826 /** 827 * Sets whether lenient parsing should be enabled (it is off by default). 828 * 829 * @param enable \c TRUE if lenient parsing should be used, 830 * \c FALSE otherwise. 831 * @stable ICU 4.8 832 */ 833 void setLenient(UBool enable) U_OVERRIDE; 834 835 /** 836 * Create a DecimalFormat from the given pattern and symbols. 837 * Use this constructor when you need to completely customize the 838 * behavior of the format. 839 * <P> 840 * To obtain standard formats for a given 841 * locale, use the factory methods on NumberFormat such as 842 * createInstance or createCurrencyInstance. If you need only minor adjustments 843 * to a standard format, you can modify the format returned by 844 * a NumberFormat factory method. 845 * <p> 846 * <strong>NOTE:</strong> New users are strongly encouraged to use 847 * #icu::number::NumberFormatter instead of DecimalFormat. 848 * 849 * @param pattern a non-localized pattern string 850 * @param symbolsToAdopt the set of symbols to be used. The caller should not 851 * delete this object after making this call. 852 * @param parseError Output param to receive errors occured during parsing 853 * @param status Output param set to success/failure code. If the 854 * pattern is invalid this will be set to a failure code. 855 * @stable ICU 2.0 856 */ 857 DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, 858 UParseError& parseError, UErrorCode& status); 859 860 /** 861 * Create a DecimalFormat from the given pattern and symbols. 862 * Use this constructor when you need to completely customize the 863 * behavior of the format. 864 * <P> 865 * To obtain standard formats for a given 866 * locale, use the factory methods on NumberFormat such as 867 * createInstance or createCurrencyInstance. If you need only minor adjustments 868 * to a standard format, you can modify the format returned by 869 * a NumberFormat factory method. 870 * <p> 871 * <strong>NOTE:</strong> New users are strongly encouraged to use 872 * #icu::number::NumberFormatter instead of DecimalFormat. 873 * 874 * @param pattern a non-localized pattern string 875 * @param symbols the set of symbols to be used 876 * @param status Output param set to success/failure code. If the 877 * pattern is invalid this will be set to a failure code. 878 * @stable ICU 2.0 879 */ 880 DecimalFormat(const UnicodeString& pattern, const DecimalFormatSymbols& symbols, UErrorCode& status); 881 882 /** 883 * Copy constructor. 884 * 885 * @param source the DecimalFormat object to be copied from. 886 * @stable ICU 2.0 887 */ 888 DecimalFormat(const DecimalFormat& source); 889 890 /** 891 * Assignment operator. 892 * 893 * @param rhs the DecimalFormat object to be copied. 894 * @stable ICU 2.0 895 */ 896 DecimalFormat& operator=(const DecimalFormat& rhs); 897 898 /** 899 * Destructor. 900 * @stable ICU 2.0 901 */ 902 ~DecimalFormat() U_OVERRIDE; 903 904 /** 905 * Clone this Format object polymorphically. The caller owns the 906 * result and should delete it when done. 907 * 908 * @return a polymorphic copy of this DecimalFormat. 909 * @stable ICU 2.0 910 */ 911 Format* clone(void) const U_OVERRIDE; 912 913 /** 914 * Return true if the given Format objects are semantically equal. 915 * Objects of different subclasses are considered unequal. 916 * 917 * @param other the object to be compared with. 918 * @return true if the given Format objects are semantically equal. 919 * @stable ICU 2.0 920 */ 921 UBool operator==(const Format& other) const U_OVERRIDE; 922 923 924 using NumberFormat::format; 925 926 /** 927 * Format a double or long number using base-10 representation. 928 * 929 * @param number The value to be formatted. 930 * @param appendTo Output parameter to receive result. 931 * Result is appended to existing contents. 932 * @param pos On input: an alignment field, if desired. 933 * On output: the offsets of the alignment field. 934 * @return Reference to 'appendTo' parameter. 935 * @stable ICU 2.0 936 */ 937 UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos) const U_OVERRIDE; 938 939 #ifndef U_HIDE_INTERNAL_API 940 /** 941 * Format a double or long number using base-10 representation. 942 * 943 * @param number The value to be formatted. 944 * @param appendTo Output parameter to receive result. 945 * Result is appended to existing contents. 946 * @param pos On input: an alignment field, if desired. 947 * On output: the offsets of the alignment field. 948 * @param status 949 * @return Reference to 'appendTo' parameter. 950 * @internal 951 */ 952 UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos, 953 UErrorCode& status) const U_OVERRIDE; 954 #endif /* U_HIDE_INTERNAL_API */ 955 956 /** 957 * Format a double or long number using base-10 representation. 958 * 959 * @param number The value to be formatted. 960 * @param appendTo Output parameter to receive result. 961 * Result is appended to existing contents. 962 * @param posIter On return, can be used to iterate over positions 963 * of fields generated by this format call. 964 * Can be NULL. 965 * @param status Output param filled with success/failure status. 966 * @return Reference to 'appendTo' parameter. 967 * @stable ICU 4.4 968 */ 969 UnicodeString& format(double number, UnicodeString& appendTo, FieldPositionIterator* posIter, 970 UErrorCode& status) const U_OVERRIDE; 971 972 /** 973 * Format a long number using base-10 representation. 974 * 975 * @param number The value to be formatted. 976 * @param appendTo Output parameter to receive result. 977 * Result is appended to existing contents. 978 * @param pos On input: an alignment field, if desired. 979 * On output: the offsets of the alignment field. 980 * @return Reference to 'appendTo' parameter. 981 * @stable ICU 2.0 982 */ 983 UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPosition& pos) const U_OVERRIDE; 984 985 #ifndef U_HIDE_INTERNAL_API 986 /** 987 * Format a long number using base-10 representation. 988 * 989 * @param number The value to be formatted. 990 * @param appendTo Output parameter to receive result. 991 * Result is appended to existing contents. 992 * @param pos On input: an alignment field, if desired. 993 * On output: the offsets of the alignment field. 994 * @param status Output param filled with success/failure status. 995 * @return Reference to 'appendTo' parameter. 996 * @internal 997 */ 998 UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPosition& pos, 999 UErrorCode& status) const U_OVERRIDE; 1000 #endif /* U_HIDE_INTERNAL_API */ 1001 1002 /** 1003 * Format a long number using base-10 representation. 1004 * 1005 * @param number The value to be formatted. 1006 * @param appendTo Output parameter to receive result. 1007 * Result is appended to existing contents. 1008 * @param posIter On return, can be used to iterate over positions 1009 * of fields generated by this format call. 1010 * Can be NULL. 1011 * @param status Output param filled with success/failure status. 1012 * @return Reference to 'appendTo' parameter. 1013 * @stable ICU 4.4 1014 */ 1015 UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPositionIterator* posIter, 1016 UErrorCode& status) const U_OVERRIDE; 1017 1018 /** 1019 * Format an int64 number using base-10 representation. 1020 * 1021 * @param number The value to be formatted. 1022 * @param appendTo Output parameter to receive result. 1023 * Result is appended to existing contents. 1024 * @param pos On input: an alignment field, if desired. 1025 * On output: the offsets of the alignment field. 1026 * @return Reference to 'appendTo' parameter. 1027 * @stable ICU 2.8 1028 */ 1029 UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos) const U_OVERRIDE; 1030 1031 #ifndef U_HIDE_INTERNAL_API 1032 /** 1033 * Format an int64 number using base-10 representation. 1034 * 1035 * @param number The value to be formatted. 1036 * @param appendTo Output parameter to receive result. 1037 * Result is appended to existing contents. 1038 * @param pos On input: an alignment field, if desired. 1039 * On output: the offsets of the alignment field. 1040 * @param status Output param filled with success/failure status. 1041 * @return Reference to 'appendTo' parameter. 1042 * @internal 1043 */ 1044 UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos, 1045 UErrorCode& status) const U_OVERRIDE; 1046 #endif /* U_HIDE_INTERNAL_API */ 1047 1048 /** 1049 * Format an int64 number using base-10 representation. 1050 * 1051 * @param number The value to be formatted. 1052 * @param appendTo Output parameter to receive result. 1053 * Result is appended to existing contents. 1054 * @param posIter On return, can be used to iterate over positions 1055 * of fields generated by this format call. 1056 * Can be NULL. 1057 * @param status Output param filled with success/failure status. 1058 * @return Reference to 'appendTo' parameter. 1059 * @stable ICU 4.4 1060 */ 1061 UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPositionIterator* posIter, 1062 UErrorCode& status) const U_OVERRIDE; 1063 1064 /** 1065 * Format a decimal number. 1066 * The syntax of the unformatted number is a "numeric string" 1067 * as defined in the Decimal Arithmetic Specification, available at 1068 * http://speleotrove.com/decimal 1069 * 1070 * @param number The unformatted number, as a string. 1071 * @param appendTo Output parameter to receive result. 1072 * Result is appended to existing contents. 1073 * @param posIter On return, can be used to iterate over positions 1074 * of fields generated by this format call. 1075 * Can be NULL. 1076 * @param status Output param filled with success/failure status. 1077 * @return Reference to 'appendTo' parameter. 1078 * @stable ICU 4.4 1079 */ 1080 UnicodeString& format(StringPiece number, UnicodeString& appendTo, FieldPositionIterator* posIter, 1081 UErrorCode& status) const U_OVERRIDE; 1082 1083 #ifndef U_HIDE_INTERNAL_API 1084 1085 /** 1086 * Format a decimal number. 1087 * The number is a DecimalQuantity wrapper onto a floating point decimal number. 1088 * The default implementation in NumberFormat converts the decimal number 1089 * to a double and formats that. 1090 * 1091 * @param number The number, a DecimalQuantity format Decimal Floating Point. 1092 * @param appendTo Output parameter to receive result. 1093 * Result is appended to existing contents. 1094 * @param posIter On return, can be used to iterate over positions 1095 * of fields generated by this format call. 1096 * @param status Output param filled with success/failure status. 1097 * @return Reference to 'appendTo' parameter. 1098 * @internal 1099 */ 1100 UnicodeString& format(const number::impl::DecimalQuantity& number, UnicodeString& appendTo, 1101 FieldPositionIterator* posIter, UErrorCode& status) const U_OVERRIDE; 1102 1103 /** 1104 * Format a decimal number. 1105 * The number is a DecimalQuantity wrapper onto a floating point decimal number. 1106 * The default implementation in NumberFormat converts the decimal number 1107 * to a double and formats that. 1108 * 1109 * @param number The number, a DecimalQuantity format Decimal Floating Point. 1110 * @param appendTo Output parameter to receive result. 1111 * Result is appended to existing contents. 1112 * @param pos On input: an alignment field, if desired. 1113 * On output: the offsets of the alignment field. 1114 * @param status Output param filled with success/failure status. 1115 * @return Reference to 'appendTo' parameter. 1116 * @internal 1117 */ 1118 UnicodeString& format(const number::impl::DecimalQuantity& number, UnicodeString& appendTo, 1119 FieldPosition& pos, UErrorCode& status) const U_OVERRIDE; 1120 1121 #endif // U_HIDE_INTERNAL_API 1122 1123 using NumberFormat::parse; 1124 1125 /** 1126 * Parse the given string using this object's choices. The method 1127 * does string comparisons to try to find an optimal match. 1128 * If no object can be parsed, index is unchanged, and NULL is 1129 * returned. The result is returned as the most parsimonious 1130 * type of Formattable that will accomodate all of the 1131 * necessary precision. For example, if the result is exactly 12, 1132 * it will be returned as a long. However, if it is 1.5, it will 1133 * be returned as a double. 1134 * 1135 * @param text The text to be parsed. 1136 * @param result Formattable to be set to the parse result. 1137 * If parse fails, return contents are undefined. 1138 * @param parsePosition The position to start parsing at on input. 1139 * On output, moved to after the last successfully 1140 * parse character. On parse failure, does not change. 1141 * @see Formattable 1142 * @stable ICU 2.0 1143 */ 1144 void parse(const UnicodeString& text, Formattable& result, 1145 ParsePosition& parsePosition) const U_OVERRIDE; 1146 1147 /** 1148 * Parses text from the given string as a currency amount. Unlike 1149 * the parse() method, this method will attempt to parse a generic 1150 * currency name, searching for a match of this object's locale's 1151 * currency display names, or for a 3-letter ISO currency code. 1152 * This method will fail if this format is not a currency format, 1153 * that is, if it does not contain the currency pattern symbol 1154 * (U+00A4) in its prefix or suffix. 1155 * 1156 * @param text the string to parse 1157 * @param pos input-output position; on input, the position within text 1158 * to match; must have 0 <= pos.getIndex() < text.length(); 1159 * on output, the position after the last matched character. 1160 * If the parse fails, the position in unchanged upon output. 1161 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount 1162 * object (owned by the caller) containing information about 1163 * the parsed currency; if parse fails, this is NULL. 1164 * @stable ICU 49 1165 */ 1166 CurrencyAmount* parseCurrency(const UnicodeString& text, ParsePosition& pos) const U_OVERRIDE; 1167 1168 /** 1169 * Returns the decimal format symbols, which is generally not changed 1170 * by the programmer or user. 1171 * @return desired DecimalFormatSymbols 1172 * @see DecimalFormatSymbols 1173 * @stable ICU 2.0 1174 */ 1175 virtual const DecimalFormatSymbols* getDecimalFormatSymbols(void) const; 1176 1177 /** 1178 * Sets the decimal format symbols, which is generally not changed 1179 * by the programmer or user. 1180 * @param symbolsToAdopt DecimalFormatSymbols to be adopted. 1181 * @stable ICU 2.0 1182 */ 1183 virtual void adoptDecimalFormatSymbols(DecimalFormatSymbols* symbolsToAdopt); 1184 1185 /** 1186 * Sets the decimal format symbols, which is generally not changed 1187 * by the programmer or user. 1188 * @param symbols DecimalFormatSymbols. 1189 * @stable ICU 2.0 1190 */ 1191 virtual void setDecimalFormatSymbols(const DecimalFormatSymbols& symbols); 1192 1193 1194 /** 1195 * Returns the currency plural format information, 1196 * which is generally not changed by the programmer or user. 1197 * @return desired CurrencyPluralInfo 1198 * @stable ICU 4.2 1199 */ 1200 virtual const CurrencyPluralInfo* getCurrencyPluralInfo(void) const; 1201 1202 /** 1203 * Sets the currency plural format information, 1204 * which is generally not changed by the programmer or user. 1205 * @param toAdopt CurrencyPluralInfo to be adopted. 1206 * @stable ICU 4.2 1207 */ 1208 virtual void adoptCurrencyPluralInfo(CurrencyPluralInfo* toAdopt); 1209 1210 /** 1211 * Sets the currency plural format information, 1212 * which is generally not changed by the programmer or user. 1213 * @param info Currency Plural Info. 1214 * @stable ICU 4.2 1215 */ 1216 virtual void setCurrencyPluralInfo(const CurrencyPluralInfo& info); 1217 1218 1219 /** 1220 * Get the positive prefix. 1221 * 1222 * @param result Output param which will receive the positive prefix. 1223 * @return A reference to 'result'. 1224 * Examples: +123, $123, sFr123 1225 * @stable ICU 2.0 1226 */ 1227 UnicodeString& getPositivePrefix(UnicodeString& result) const; 1228 1229 /** 1230 * Set the positive prefix. 1231 * 1232 * @param newValue the new value of the the positive prefix to be set. 1233 * Examples: +123, $123, sFr123 1234 * @stable ICU 2.0 1235 */ 1236 virtual void setPositivePrefix(const UnicodeString& newValue); 1237 1238 /** 1239 * Get the negative prefix. 1240 * 1241 * @param result Output param which will receive the negative prefix. 1242 * @return A reference to 'result'. 1243 * Examples: -123, ($123) (with negative suffix), sFr-123 1244 * @stable ICU 2.0 1245 */ 1246 UnicodeString& getNegativePrefix(UnicodeString& result) const; 1247 1248 /** 1249 * Set the negative prefix. 1250 * 1251 * @param newValue the new value of the the negative prefix to be set. 1252 * Examples: -123, ($123) (with negative suffix), sFr-123 1253 * @stable ICU 2.0 1254 */ 1255 virtual void setNegativePrefix(const UnicodeString& newValue); 1256 1257 /** 1258 * Get the positive suffix. 1259 * 1260 * @param result Output param which will receive the positive suffix. 1261 * @return A reference to 'result'. 1262 * Example: 123% 1263 * @stable ICU 2.0 1264 */ 1265 UnicodeString& getPositiveSuffix(UnicodeString& result) const; 1266 1267 /** 1268 * Set the positive suffix. 1269 * 1270 * @param newValue the new value of the positive suffix to be set. 1271 * Example: 123% 1272 * @stable ICU 2.0 1273 */ 1274 virtual void setPositiveSuffix(const UnicodeString& newValue); 1275 1276 /** 1277 * Get the negative suffix. 1278 * 1279 * @param result Output param which will receive the negative suffix. 1280 * @return A reference to 'result'. 1281 * Examples: -123%, ($123) (with positive suffixes) 1282 * @stable ICU 2.0 1283 */ 1284 UnicodeString& getNegativeSuffix(UnicodeString& result) const; 1285 1286 /** 1287 * Set the negative suffix. 1288 * 1289 * @param newValue the new value of the negative suffix to be set. 1290 * Examples: 123% 1291 * @stable ICU 2.0 1292 */ 1293 virtual void setNegativeSuffix(const UnicodeString& newValue); 1294 1295 #ifndef U_HIDE_INTERNAL_API 1296 /** 1297 * Whether to show the plus sign on positive (non-negative) numbers; for example, "+12" 1298 * @internal Technical Preview 1299 */ 1300 UBool isSignAlwaysShown() const; 1301 #endif /* U_HIDE_INTERNAL_API */ 1302 1303 /** 1304 * Set whether to show the plus sign on positive (non-negative) numbers; for example, "+12" 1305 * @param value The new setting for whether to show plus sign on positive numbers 1306 * @internal Technical Preview 1307 */ 1308 virtual void setSignAlwaysShown(UBool value); 1309 1310 /** 1311 * Get the multiplier for use in percent, permill, etc. 1312 * For a percentage, set the suffixes to have "%" and the multiplier to be 100. 1313 * (For Arabic, use arabic percent symbol). 1314 * For a permill, set the suffixes to have "\\u2031" and the multiplier to be 1000. 1315 * 1316 * The number may also be multiplied by a power of ten; see getMultiplierScale(). 1317 * 1318 * @return the multiplier for use in percent, permill, etc. 1319 * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 1320 * @stable ICU 2.0 1321 */ 1322 int32_t getMultiplier(void) const; 1323 1324 /** 1325 * Set the multiplier for use in percent, permill, etc. 1326 * For a percentage, set the suffixes to have "%" and the multiplier to be 100. 1327 * (For Arabic, use arabic percent symbol). 1328 * For a permill, set the suffixes to have "\\u2031" and the multiplier to be 1000. 1329 * 1330 * This method only supports integer multipliers. To multiply by a non-integer, pair this 1331 * method with setMultiplierScale(). 1332 * 1333 * @param newValue the new value of the multiplier for use in percent, permill, etc. 1334 * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 1335 * @stable ICU 2.0 1336 */ 1337 virtual void setMultiplier(int32_t newValue); 1338 1339 #ifndef U_HIDE_DRAFT_API 1340 /** 1341 * Gets the power of ten by which number should be multiplied before formatting, which 1342 * can be combined with setMultiplier() to multiply by any arbitrary decimal value. 1343 * 1344 * A multiplier scale of 2 corresponds to multiplication by 100, and a multiplier scale 1345 * of -2 corresponds to multiplication by 0.01. 1346 * 1347 * This method is analogous to UNUM_SCALE in getAttribute. 1348 * 1349 * @return the current value of the power-of-ten multiplier. 1350 * @draft ICU 62 1351 */ 1352 int32_t getMultiplierScale(void) const; 1353 #endif /* U_HIDE_DRAFT_API */ 1354 1355 /** 1356 * Sets a power of ten by which number should be multiplied before formatting, which 1357 * can be combined with setMultiplier() to multiply by any arbitrary decimal value. 1358 * 1359 * A multiplier scale of 2 corresponds to multiplication by 100, and a multiplier scale 1360 * of -2 corresponds to multiplication by 0.01. 1361 * 1362 * For example, to multiply numbers by 0.5 before formatting, you can do: 1363 * 1364 * <pre> 1365 * df.setMultiplier(5); 1366 * df.setMultiplierScale(-1); 1367 * </pre> 1368 * 1369 * This method is analogous to UNUM_SCALE in setAttribute. 1370 * 1371 * @param newValue the new value of the power-of-ten multiplier. 1372 * @draft ICU 62 1373 */ 1374 virtual void setMultiplierScale(int32_t newValue); 1375 1376 /** 1377 * Get the rounding increment. 1378 * @return A positive rounding increment, or 0.0 if a custom rounding 1379 * increment is not in effect. 1380 * @see #setRoundingIncrement 1381 * @see #getRoundingMode 1382 * @see #setRoundingMode 1383 * @stable ICU 2.0 1384 */ 1385 virtual double getRoundingIncrement(void) const; 1386 1387 /** 1388 * Set the rounding increment. In the absence of a rounding increment, 1389 * numbers will be rounded to the number of digits displayed. 1390 * @param newValue A positive rounding increment, or 0.0 to 1391 * use the default rounding increment. 1392 * Negative increments are equivalent to 0.0. 1393 * @see #getRoundingIncrement 1394 * @see #getRoundingMode 1395 * @see #setRoundingMode 1396 * @stable ICU 2.0 1397 */ 1398 virtual void setRoundingIncrement(double newValue); 1399 1400 /** 1401 * Get the rounding mode. 1402 * @return A rounding mode 1403 * @see #setRoundingIncrement 1404 * @see #getRoundingIncrement 1405 * @see #setRoundingMode 1406 * @stable ICU 2.0 1407 */ 1408 virtual ERoundingMode getRoundingMode(void) const U_OVERRIDE; 1409 1410 /** 1411 * Set the rounding mode. 1412 * @param roundingMode A rounding mode 1413 * @see #setRoundingIncrement 1414 * @see #getRoundingIncrement 1415 * @see #getRoundingMode 1416 * @stable ICU 2.0 1417 */ 1418 virtual void setRoundingMode(ERoundingMode roundingMode) U_OVERRIDE; 1419 1420 /** 1421 * Get the width to which the output of format() is padded. 1422 * The width is counted in 16-bit code units. 1423 * @return the format width, or zero if no padding is in effect 1424 * @see #setFormatWidth 1425 * @see #getPadCharacterString 1426 * @see #setPadCharacter 1427 * @see #getPadPosition 1428 * @see #setPadPosition 1429 * @stable ICU 2.0 1430 */ 1431 virtual int32_t getFormatWidth(void) const; 1432 1433 /** 1434 * Set the width to which the output of format() is padded. 1435 * The width is counted in 16-bit code units. 1436 * This method also controls whether padding is enabled. 1437 * @param width the width to which to pad the result of 1438 * format(), or zero to disable padding. A negative 1439 * width is equivalent to 0. 1440 * @see #getFormatWidth 1441 * @see #getPadCharacterString 1442 * @see #setPadCharacter 1443 * @see #getPadPosition 1444 * @see #setPadPosition 1445 * @stable ICU 2.0 1446 */ 1447 virtual void setFormatWidth(int32_t width); 1448 1449 /** 1450 * Get the pad character used to pad to the format width. The 1451 * default is ' '. 1452 * @return a string containing the pad character. This will always 1453 * have a length of one 32-bit code point. 1454 * @see #setFormatWidth 1455 * @see #getFormatWidth 1456 * @see #setPadCharacter 1457 * @see #getPadPosition 1458 * @see #setPadPosition 1459 * @stable ICU 2.0 1460 */ 1461 virtual UnicodeString getPadCharacterString() const; 1462 1463 /** 1464 * Set the character used to pad to the format width. If padding 1465 * is not enabled, then this will take effect if padding is later 1466 * enabled. 1467 * @param padChar a string containing the pad charcter. If the string 1468 * has length 0, then the pad characer is set to ' '. Otherwise 1469 * padChar.char32At(0) will be used as the pad character. 1470 * @see #setFormatWidth 1471 * @see #getFormatWidth 1472 * @see #getPadCharacterString 1473 * @see #getPadPosition 1474 * @see #setPadPosition 1475 * @stable ICU 2.0 1476 */ 1477 virtual void setPadCharacter(const UnicodeString& padChar); 1478 1479 /** 1480 * Get the position at which padding will take place. This is the location 1481 * at which padding will be inserted if the result of format() 1482 * is shorter than the format width. 1483 * @return the pad position, one of kPadBeforePrefix, 1484 * kPadAfterPrefix, kPadBeforeSuffix, or 1485 * kPadAfterSuffix. 1486 * @see #setFormatWidth 1487 * @see #getFormatWidth 1488 * @see #setPadCharacter 1489 * @see #getPadCharacterString 1490 * @see #setPadPosition 1491 * @see #EPadPosition 1492 * @stable ICU 2.0 1493 */ 1494 virtual EPadPosition getPadPosition(void) const; 1495 1496 /** 1497 * Set the position at which padding will take place. This is the location 1498 * at which padding will be inserted if the result of format() 1499 * is shorter than the format width. This has no effect unless padding is 1500 * enabled. 1501 * @param padPos the pad position, one of kPadBeforePrefix, 1502 * kPadAfterPrefix, kPadBeforeSuffix, or 1503 * kPadAfterSuffix. 1504 * @see #setFormatWidth 1505 * @see #getFormatWidth 1506 * @see #setPadCharacter 1507 * @see #getPadCharacterString 1508 * @see #getPadPosition 1509 * @see #EPadPosition 1510 * @stable ICU 2.0 1511 */ 1512 virtual void setPadPosition(EPadPosition padPos); 1513 1514 /** 1515 * Return whether or not scientific notation is used. 1516 * @return TRUE if this object formats and parses scientific notation 1517 * @see #setScientificNotation 1518 * @see #getMinimumExponentDigits 1519 * @see #setMinimumExponentDigits 1520 * @see #isExponentSignAlwaysShown 1521 * @see #setExponentSignAlwaysShown 1522 * @stable ICU 2.0 1523 */ 1524 virtual UBool isScientificNotation(void) const; 1525 1526 /** 1527 * Set whether or not scientific notation is used. When scientific notation 1528 * is used, the effective maximum number of integer digits is <= 8. If the 1529 * maximum number of integer digits is set to more than 8, the effective 1530 * maximum will be 1. This allows this call to generate a 'default' scientific 1531 * number format without additional changes. 1532 * @param useScientific TRUE if this object formats and parses scientific 1533 * notation 1534 * @see #isScientificNotation 1535 * @see #getMinimumExponentDigits 1536 * @see #setMinimumExponentDigits 1537 * @see #isExponentSignAlwaysShown 1538 * @see #setExponentSignAlwaysShown 1539 * @stable ICU 2.0 1540 */ 1541 virtual void setScientificNotation(UBool useScientific); 1542 1543 /** 1544 * Return the minimum exponent digits that will be shown. 1545 * @return the minimum exponent digits that will be shown 1546 * @see #setScientificNotation 1547 * @see #isScientificNotation 1548 * @see #setMinimumExponentDigits 1549 * @see #isExponentSignAlwaysShown 1550 * @see #setExponentSignAlwaysShown 1551 * @stable ICU 2.0 1552 */ 1553 virtual int8_t getMinimumExponentDigits(void) const; 1554 1555 /** 1556 * Set the minimum exponent digits that will be shown. This has no 1557 * effect unless scientific notation is in use. 1558 * @param minExpDig a value >= 1 indicating the fewest exponent digits 1559 * that will be shown. Values less than 1 will be treated as 1. 1560 * @see #setScientificNotation 1561 * @see #isScientificNotation 1562 * @see #getMinimumExponentDigits 1563 * @see #isExponentSignAlwaysShown 1564 * @see #setExponentSignAlwaysShown 1565 * @stable ICU 2.0 1566 */ 1567 virtual void setMinimumExponentDigits(int8_t minExpDig); 1568 1569 /** 1570 * Return whether the exponent sign is always shown. 1571 * @return TRUE if the exponent is always prefixed with either the 1572 * localized minus sign or the localized plus sign, false if only negative 1573 * exponents are prefixed with the localized minus sign. 1574 * @see #setScientificNotation 1575 * @see #isScientificNotation 1576 * @see #setMinimumExponentDigits 1577 * @see #getMinimumExponentDigits 1578 * @see #setExponentSignAlwaysShown 1579 * @stable ICU 2.0 1580 */ 1581 virtual UBool isExponentSignAlwaysShown(void) const; 1582 1583 /** 1584 * Set whether the exponent sign is always shown. This has no effect 1585 * unless scientific notation is in use. 1586 * @param expSignAlways TRUE if the exponent is always prefixed with either 1587 * the localized minus sign or the localized plus sign, false if only 1588 * negative exponents are prefixed with the localized minus sign. 1589 * @see #setScientificNotation 1590 * @see #isScientificNotation 1591 * @see #setMinimumExponentDigits 1592 * @see #getMinimumExponentDigits 1593 * @see #isExponentSignAlwaysShown 1594 * @stable ICU 2.0 1595 */ 1596 virtual void setExponentSignAlwaysShown(UBool expSignAlways); 1597 1598 /** 1599 * Return the grouping size. Grouping size is the number of digits between 1600 * grouping separators in the integer portion of a number. For example, 1601 * in the number "123,456.78", the grouping size is 3. 1602 * 1603 * @return the grouping size. 1604 * @see setGroupingSize 1605 * @see NumberFormat::isGroupingUsed 1606 * @see DecimalFormatSymbols::getGroupingSeparator 1607 * @stable ICU 2.0 1608 */ 1609 int32_t getGroupingSize(void) const; 1610 1611 /** 1612 * Set the grouping size. Grouping size is the number of digits between 1613 * grouping separators in the integer portion of a number. For example, 1614 * in the number "123,456.78", the grouping size is 3. 1615 * 1616 * @param newValue the new value of the grouping size. 1617 * @see getGroupingSize 1618 * @see NumberFormat::setGroupingUsed 1619 * @see DecimalFormatSymbols::setGroupingSeparator 1620 * @stable ICU 2.0 1621 */ 1622 virtual void setGroupingSize(int32_t newValue); 1623 1624 /** 1625 * Return the secondary grouping size. In some locales one 1626 * grouping interval is used for the least significant integer 1627 * digits (the primary grouping size), and another is used for all 1628 * others (the secondary grouping size). A formatter supporting a 1629 * secondary grouping size will return a positive integer unequal 1630 * to the primary grouping size returned by 1631 * getGroupingSize(). For example, if the primary 1632 * grouping size is 4, and the secondary grouping size is 2, then 1633 * the number 123456789 formats as "1,23,45,6789", and the pattern 1634 * appears as "#,##,###0". 1635 * @return the secondary grouping size, or a value less than 1636 * one if there is none 1637 * @see setSecondaryGroupingSize 1638 * @see NumberFormat::isGroupingUsed 1639 * @see DecimalFormatSymbols::getGroupingSeparator 1640 * @stable ICU 2.4 1641 */ 1642 int32_t getSecondaryGroupingSize(void) const; 1643 1644 /** 1645 * Set the secondary grouping size. If set to a value less than 1, 1646 * then secondary grouping is turned off, and the primary grouping 1647 * size is used for all intervals, not just the least significant. 1648 * 1649 * @param newValue the new value of the secondary grouping size. 1650 * @see getSecondaryGroupingSize 1651 * @see NumberFormat#setGroupingUsed 1652 * @see DecimalFormatSymbols::setGroupingSeparator 1653 * @stable ICU 2.4 1654 */ 1655 virtual void setSecondaryGroupingSize(int32_t newValue); 1656 1657 #ifndef U_HIDE_INTERNAL_API 1658 1659 /** 1660 * Returns the minimum number of grouping digits. 1661 * Grouping separators are output if there are at least this many 1662 * digits to the left of the first (rightmost) grouping separator, 1663 * that is, there are at least (minimum grouping + grouping size) integer digits. 1664 * (Subject to isGroupingUsed().) 1665 * 1666 * For example, if this value is 2, and the grouping size is 3, then 1667 * 9999 -> "9999" and 10000 -> "10,000" 1668 * 1669 * This is a technology preview. This API may change behavior or may be removed. 1670 * 1671 * The default value for this attribute is 0. 1672 * A value of 1, 0, or lower, means that the use of grouping separators 1673 * only depends on the grouping size (and on isGroupingUsed()). 1674 * Currently, the corresponding CLDR data is not used; this is likely to change. 1675 * 1676 * @see setMinimumGroupingDigits 1677 * @see getGroupingSize 1678 * @internal technology preview 1679 */ 1680 int32_t getMinimumGroupingDigits() const; 1681 1682 #endif /* U_HIDE_INTERNAL_API */ 1683 1684 /* Cannot use #ifndef U_HIDE_INTERNAL_API for the following draft method since it is virtual. */ 1685 /** 1686 * Sets the minimum grouping digits. Setting to a value less than or 1687 * equal to 1 turns off minimum grouping digits. 1688 * 1689 * @param newValue the new value of minimum grouping digits. 1690 * @see getMinimumGroupingDigits 1691 * @internal technology preview 1692 */ 1693 virtual void setMinimumGroupingDigits(int32_t newValue); 1694 1695 1696 /** 1697 * Allows you to get the behavior of the decimal separator with integers. 1698 * (The decimal separator will always appear with decimals.) 1699 * 1700 * @return TRUE if the decimal separator always appear with decimals. 1701 * Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345 1702 * @stable ICU 2.0 1703 */ 1704 UBool isDecimalSeparatorAlwaysShown(void) const; 1705 1706 /** 1707 * Allows you to set the behavior of the decimal separator with integers. 1708 * (The decimal separator will always appear with decimals.) 1709 * 1710 * @param newValue set TRUE if the decimal separator will always appear with decimals. 1711 * Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345 1712 * @stable ICU 2.0 1713 */ 1714 virtual void setDecimalSeparatorAlwaysShown(UBool newValue); 1715 1716 /** 1717 * Allows you to get the parse behavior of the pattern decimal mark. 1718 * 1719 * @return TRUE if input must contain a match to decimal mark in pattern 1720 * @stable ICU 54 1721 */ 1722 UBool isDecimalPatternMatchRequired(void) const; 1723 1724 /** 1725 * Allows you to set the parse behavior of the pattern decimal mark. 1726 * 1727 * if TRUE, the input must have a decimal mark if one was specified in the pattern. When 1728 * FALSE the decimal mark may be omitted from the input. 1729 * 1730 * @param newValue set TRUE if input must contain a match to decimal mark in pattern 1731 * @stable ICU 54 1732 */ 1733 virtual void setDecimalPatternMatchRequired(UBool newValue); 1734 1735 /** 1736 * Returns whether to ignore exponents when parsing. 1737 * 1738 * @see #setParseNoExponent 1739 * @internal This API is a technical preview. It may change in an upcoming release. 1740 */ 1741 virtual UBool isParseNoExponent() const; 1742 1743 /** 1744 * Specifies whether to stop parsing when an exponent separator is encountered. For 1745 * example, parses "123E4" to 123 (with parse position 3) instead of 1230000 (with parse position 1746 * 5). 1747 * 1748 * @param value true to prevent exponents from being parsed; false to allow them to be parsed. 1749 * @internal This API is a technical preview. It may change in an upcoming release. 1750 */ 1751 virtual void setParseNoExponent(UBool value); 1752 1753 /** 1754 * Returns whether parsing is sensitive to case (lowercase/uppercase). 1755 * 1756 * @see #setParseCaseSensitive 1757 * @internal This API is a technical preview. It may change in an upcoming release. 1758 */ 1759 virtual UBool isParseCaseSensitive() const; 1760 1761 /** 1762 * Whether to pay attention to case when parsing; default is to ignore case (perform 1763 * case-folding). For example, "A" == "a" in case-insensitive but not case-sensitive mode. 1764 * 1765 * Currency symbols are never case-folded. For example, "us$1.00" will not parse in case-insensitive 1766 * mode, even though "US$1.00" parses. 1767 * 1768 * @internal This API is a technical preview. It may change in an upcoming release. 1769 */ 1770 virtual void setParseCaseSensitive(UBool value); 1771 1772 /** 1773 * Returns whether truncation of high-order integer digits should result in an error. 1774 * By default, setMaximumIntegerDigits truncates high-order digits silently. 1775 * 1776 * @see setFormatFailIfMoreThanMaxDigits 1777 * @internal This API is a technical preview. It may change in an upcoming release. 1778 */ 1779 virtual UBool isFormatFailIfMoreThanMaxDigits() const; 1780 1781 /** 1782 * Sets whether truncation of high-order integer digits should result in an error. 1783 * By default, setMaximumIntegerDigits truncates high-order digits silently. 1784 * 1785 * @internal This API is a technical preview. It may change in an upcoming release. 1786 */ 1787 virtual void setFormatFailIfMoreThanMaxDigits(UBool value); 1788 1789 1790 /** 1791 * Synthesizes a pattern string that represents the current state 1792 * of this Format object. 1793 * 1794 * @param result Output param which will receive the pattern. 1795 * Previous contents are deleted. 1796 * @return A reference to 'result'. 1797 * @see applyPattern 1798 * @stable ICU 2.0 1799 */ 1800 virtual UnicodeString& toPattern(UnicodeString& result) const; 1801 1802 /** 1803 * Synthesizes a localized pattern string that represents the current 1804 * state of this Format object. 1805 * 1806 * @param result Output param which will receive the localized pattern. 1807 * Previous contents are deleted. 1808 * @return A reference to 'result'. 1809 * @see applyPattern 1810 * @stable ICU 2.0 1811 */ 1812 virtual UnicodeString& toLocalizedPattern(UnicodeString& result) const; 1813 1814 /** 1815 * Apply the given pattern to this Format object. A pattern is a 1816 * short-hand specification for the various formatting properties. 1817 * These properties can also be changed individually through the 1818 * various setter methods. 1819 * <P> 1820 * There is no limit to integer digits are set 1821 * by this routine, since that is the typical end-user desire; 1822 * use setMaximumInteger if you want to set a real value. 1823 * For negative numbers, use a second pattern, separated by a semicolon 1824 * <pre> 1825 * . Example "#,#00.0#" -> 1,234.56 1826 * </pre> 1827 * This means a minimum of 2 integer digits, 1 fraction digit, and 1828 * a maximum of 2 fraction digits. 1829 * <pre> 1830 * . Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses. 1831 * </pre> 1832 * In negative patterns, the minimum and maximum counts are ignored; 1833 * these are presumed to be set in the positive pattern. 1834 * 1835 * @param pattern The pattern to be applied. 1836 * @param parseError Struct to recieve information on position 1837 * of error if an error is encountered 1838 * @param status Output param set to success/failure code on 1839 * exit. If the pattern is invalid, this will be 1840 * set to a failure result. 1841 * @stable ICU 2.0 1842 */ 1843 virtual void applyPattern(const UnicodeString& pattern, UParseError& parseError, UErrorCode& status); 1844 1845 /** 1846 * Sets the pattern. 1847 * @param pattern The pattern to be applied. 1848 * @param status Output param set to success/failure code on 1849 * exit. If the pattern is invalid, this will be 1850 * set to a failure result. 1851 * @stable ICU 2.0 1852 */ 1853 virtual void applyPattern(const UnicodeString& pattern, UErrorCode& status); 1854 1855 /** 1856 * Apply the given pattern to this Format object. The pattern 1857 * is assumed to be in a localized notation. A pattern is a 1858 * short-hand specification for the various formatting properties. 1859 * These properties can also be changed individually through the 1860 * various setter methods. 1861 * <P> 1862 * There is no limit to integer digits are set 1863 * by this routine, since that is the typical end-user desire; 1864 * use setMaximumInteger if you want to set a real value. 1865 * For negative numbers, use a second pattern, separated by a semicolon 1866 * <pre> 1867 * . Example "#,#00.0#" -> 1,234.56 1868 * </pre> 1869 * This means a minimum of 2 integer digits, 1 fraction digit, and 1870 * a maximum of 2 fraction digits. 1871 * 1872 * Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses. 1873 * 1874 * In negative patterns, the minimum and maximum counts are ignored; 1875 * these are presumed to be set in the positive pattern. 1876 * 1877 * @param pattern The localized pattern to be applied. 1878 * @param parseError Struct to recieve information on position 1879 * of error if an error is encountered 1880 * @param status Output param set to success/failure code on 1881 * exit. If the pattern is invalid, this will be 1882 * set to a failure result. 1883 * @stable ICU 2.0 1884 */ 1885 virtual void applyLocalizedPattern(const UnicodeString& pattern, UParseError& parseError, 1886 UErrorCode& status); 1887 1888 /** 1889 * Apply the given pattern to this Format object. 1890 * 1891 * @param pattern The localized pattern to be applied. 1892 * @param status Output param set to success/failure code on 1893 * exit. If the pattern is invalid, this will be 1894 * set to a failure result. 1895 * @stable ICU 2.0 1896 */ 1897 virtual void applyLocalizedPattern(const UnicodeString& pattern, UErrorCode& status); 1898 1899 1900 /** 1901 * Sets the maximum number of digits allowed in the integer portion of a 1902 * number. This override limits the integer digit count to 309. 1903 * 1904 * @param newValue the new value of the maximum number of digits 1905 * allowed in the integer portion of a number. 1906 * @see NumberFormat#setMaximumIntegerDigits 1907 * @stable ICU 2.0 1908 */ 1909 void setMaximumIntegerDigits(int32_t newValue) U_OVERRIDE; 1910 1911 /** 1912 * Sets the minimum number of digits allowed in the integer portion of a 1913 * number. This override limits the integer digit count to 309. 1914 * 1915 * @param newValue the new value of the minimum number of digits 1916 * allowed in the integer portion of a number. 1917 * @see NumberFormat#setMinimumIntegerDigits 1918 * @stable ICU 2.0 1919 */ 1920 void setMinimumIntegerDigits(int32_t newValue) U_OVERRIDE; 1921 1922 /** 1923 * Sets the maximum number of digits allowed in the fraction portion of a 1924 * number. This override limits the fraction digit count to 340. 1925 * 1926 * @param newValue the new value of the maximum number of digits 1927 * allowed in the fraction portion of a number. 1928 * @see NumberFormat#setMaximumFractionDigits 1929 * @stable ICU 2.0 1930 */ 1931 void setMaximumFractionDigits(int32_t newValue) U_OVERRIDE; 1932 1933 /** 1934 * Sets the minimum number of digits allowed in the fraction portion of a 1935 * number. This override limits the fraction digit count to 340. 1936 * 1937 * @param newValue the new value of the minimum number of digits 1938 * allowed in the fraction portion of a number. 1939 * @see NumberFormat#setMinimumFractionDigits 1940 * @stable ICU 2.0 1941 */ 1942 void setMinimumFractionDigits(int32_t newValue) U_OVERRIDE; 1943 1944 /** 1945 * Returns the minimum number of significant digits that will be 1946 * displayed. This value has no effect unless areSignificantDigitsUsed() 1947 * returns true. 1948 * @return the fewest significant digits that will be shown 1949 * @stable ICU 3.0 1950 */ 1951 int32_t getMinimumSignificantDigits() const; 1952 1953 /** 1954 * Returns the maximum number of significant digits that will be 1955 * displayed. This value has no effect unless areSignificantDigitsUsed() 1956 * returns true. 1957 * @return the most significant digits that will be shown 1958 * @stable ICU 3.0 1959 */ 1960 int32_t getMaximumSignificantDigits() const; 1961 1962 /** 1963 * Sets the minimum number of significant digits that will be 1964 * displayed. If <code>min</code> is less than one then it is set 1965 * to one. If the maximum significant digits count is less than 1966 * <code>min</code>, then it is set to <code>min</code>. 1967 * This function also enables the use of significant digits 1968 * by this formatter - areSignificantDigitsUsed() will return TRUE. 1969 * @see #areSignificantDigitsUsed 1970 * @param min the fewest significant digits to be shown 1971 * @stable ICU 3.0 1972 */ 1973 void setMinimumSignificantDigits(int32_t min); 1974 1975 /** 1976 * Sets the maximum number of significant digits that will be 1977 * displayed. If <code>max</code> is less than one then it is set 1978 * to one. If the minimum significant digits count is greater 1979 * than <code>max</code>, then it is set to <code>max</code>. 1980 * This function also enables the use of significant digits 1981 * by this formatter - areSignificantDigitsUsed() will return TRUE. 1982 * @see #areSignificantDigitsUsed 1983 * @param max the most significant digits to be shown 1984 * @stable ICU 3.0 1985 */ 1986 void setMaximumSignificantDigits(int32_t max); 1987 1988 /** 1989 * Returns true if significant digits are in use, or false if 1990 * integer and fraction digit counts are in use. 1991 * @return true if significant digits are in use 1992 * @stable ICU 3.0 1993 */ 1994 UBool areSignificantDigitsUsed() const; 1995 1996 /** 1997 * Sets whether significant digits are in use, or integer and 1998 * fraction digit counts are in use. 1999 * @param useSignificantDigits true to use significant digits, or 2000 * false to use integer and fraction digit counts 2001 * @stable ICU 3.0 2002 */ 2003 void setSignificantDigitsUsed(UBool useSignificantDigits); 2004 2005 /** 2006 * Sets the currency used to display currency 2007 * amounts. This takes effect immediately, if this format is a 2008 * currency format. If this format is not a currency format, then 2009 * the currency is used if and when this object becomes a 2010 * currency format through the application of a new pattern. 2011 * @param theCurrency a 3-letter ISO code indicating new currency 2012 * to use. It need not be null-terminated. May be the empty 2013 * string or NULL to indicate no currency. 2014 * @param ec input-output error code 2015 * @stable ICU 3.0 2016 */ 2017 void setCurrency(const char16_t* theCurrency, UErrorCode& ec) U_OVERRIDE; 2018 2019 /** 2020 * Sets the currency used to display currency amounts. See 2021 * setCurrency(const char16_t*, UErrorCode&). 2022 * @deprecated ICU 3.0. Use setCurrency(const char16_t*, UErrorCode&). 2023 */ 2024 virtual void setCurrency(const char16_t* theCurrency); 2025 2026 /** 2027 * Sets the `Currency Usage` object used to display currency. 2028 * This takes effect immediately, if this format is a 2029 * currency format. 2030 * @param newUsage new currency usage object to use. 2031 * @param ec input-output error code 2032 * @stable ICU 54 2033 */ 2034 void setCurrencyUsage(UCurrencyUsage newUsage, UErrorCode* ec); 2035 2036 /** 2037 * Returns the `Currency Usage` object used to display currency 2038 * @stable ICU 54 2039 */ 2040 UCurrencyUsage getCurrencyUsage() const; 2041 2042 #ifndef U_HIDE_INTERNAL_API 2043 2044 /** 2045 * Format a number and save it into the given DecimalQuantity. 2046 * Internal, not intended for public use. 2047 * @internal 2048 */ 2049 void formatToDecimalQuantity(double number, number::impl::DecimalQuantity& output, 2050 UErrorCode& status) const; 2051 2052 /** 2053 * Get a DecimalQuantity corresponding to a formattable as it would be 2054 * formatted by this DecimalFormat. 2055 * Internal, not intended for public use. 2056 * @internal 2057 */ 2058 void formatToDecimalQuantity(const Formattable& number, number::impl::DecimalQuantity& output, 2059 UErrorCode& status) const; 2060 2061 #endif /* U_HIDE_INTERNAL_API */ 2062 2063 #ifndef U_HIDE_DRAFT_API 2064 /** 2065 * Converts this DecimalFormat to a NumberFormatter. Starting in ICU 60, 2066 * NumberFormatter is the recommended way to format numbers. 2067 * 2068 * NOTE: The returned LocalizedNumberFormatter is owned by this DecimalFormat. 2069 * If a non-const method is called on the DecimalFormat, or if the DecimalFormat 2070 * is deleted, the object becomes invalid. If you plan to keep the return value 2071 * beyond the lifetime of the DecimalFormat, copy it to a local variable: 2072 * 2073 * <pre> 2074 * LocalizedNumberFormatter f = df->toNumberFormatter(); 2075 * </pre> 2076 * 2077 * It is, however, safe to use the return value for chaining: 2078 * 2079 * <pre> 2080 * FormattedNumber result = df->toNumberFormatter().formatDouble(123, status); 2081 * </pre> 2082 * 2083 * @return The output variable, for chaining. 2084 * @draft ICU 62 2085 */ 2086 const number::LocalizedNumberFormatter& toNumberFormatter() const; 2087 #endif /* U_HIDE_DRAFT_API */ 2088 2089 /** 2090 * Return the class ID for this class. This is useful only for 2091 * comparing to a return value from getDynamicClassID(). For example: 2092 * <pre> 2093 * . Base* polymorphic_pointer = createPolymorphicObject(); 2094 * . if (polymorphic_pointer->getDynamicClassID() == 2095 * . Derived::getStaticClassID()) ... 2096 * </pre> 2097 * @return The class ID for all objects of this class. 2098 * @stable ICU 2.0 2099 */ 2100 static UClassID U_EXPORT2 getStaticClassID(void); 2101 2102 /** 2103 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 2104 * This method is to implement a simple version of RTTI, since not all 2105 * C++ compilers support genuine RTTI. Polymorphic operator==() and 2106 * clone() methods call this method. 2107 * 2108 * @return The class ID for this object. All objects of a 2109 * given class have the same class ID. Objects of 2110 * other classes have different class IDs. 2111 * @stable ICU 2.0 2112 */ 2113 UClassID getDynamicClassID(void) const U_OVERRIDE; 2114 2115 private: 2116 2117 /** Rebuilds the formatter object from the property bag. */ 2118 void touch(UErrorCode& status); 2119 2120 /** Rebuilds the formatter object, hiding the error code. */ 2121 void touchNoError(); 2122 2123 /** 2124 * Updates the property bag with settings from the given pattern. 2125 * 2126 * @param pattern The pattern string to parse. 2127 * @param ignoreRounding Whether to leave out rounding information (minFrac, maxFrac, and rounding 2128 * increment) when parsing the pattern. This may be desirable if a custom rounding mode, such 2129 * as CurrencyUsage, is to be used instead. One of {@link 2130 * PatternStringParser#IGNORE_ROUNDING_ALWAYS}, {@link PatternStringParser#IGNORE_ROUNDING_IF_CURRENCY}, 2131 * or {@link PatternStringParser#IGNORE_ROUNDING_NEVER}. 2132 * @see PatternAndPropertyUtils#parseToExistingProperties 2133 */ 2134 void setPropertiesFromPattern(const UnicodeString& pattern, int32_t ignoreRounding, 2135 UErrorCode& status); 2136 2137 const numparse::impl::NumberParserImpl* getParser(UErrorCode& status) const; 2138 2139 const numparse::impl::NumberParserImpl* getCurrencyParser(UErrorCode& status) const; 2140 2141 static void fieldPositionHelper(const number::FormattedNumber& formatted, FieldPosition& fieldPosition, 2142 int32_t offset, UErrorCode& status); 2143 2144 static void fieldPositionIteratorHelper(const number::FormattedNumber& formatted, 2145 FieldPositionIterator* fpi, int32_t offset, UErrorCode& status); 2146 2147 void setupFastFormat(); 2148 2149 bool fastFormatDouble(double input, UnicodeString& output) const; 2150 2151 bool fastFormatInt64(int64_t input, UnicodeString& output) const; 2152 2153 void doFastFormatInt32(int32_t input, bool isNegative, UnicodeString& output) const; 2154 2155 //=====================================================================================// 2156 // INSTANCE FIELDS // 2157 //=====================================================================================// 2158 2159 // Only one instance field: keep all fields inside of an implementation class defined in number_mapper.h 2160 number::impl::DecimalFormatFields* fields; 2161 2162 // Allow child class CompactDecimalFormat to access fProperties: 2163 friend class CompactDecimalFormat; 2164 2165 }; 2166 2167 U_NAMESPACE_END 2168 2169 #endif /* #if !UCONFIG_NO_FORMATTING */ 2170 2171 #endif // _DECIMFMT 2172 //eof 2173