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