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