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