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