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