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