Where Online Learning is simpler!
The C and C++ Include Header Files
/usr/include/unicode/decimfmt.h
$ cat -n /usr/include/unicode/decimfmt.h 1 // © 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 #if U_SHOW_CPLUSPLUS_API 33 34 /** 35 * \file 36 * \brief C++ API: Compatibility APIs for decimal formatting. 37 */ 38 39 #if !UCONFIG_NO_FORMATTING 40 41 #include "unicode/dcfmtsym.h" 42 #include "unicode/numfmt.h" 43 #include "unicode/locid.h" 44 #include "unicode/fpositer.h" 45 #include "unicode/stringpiece.h" 46 #include "unicode/curramt.h" 47 #include "unicode/enumset.h" 48 49 U_NAMESPACE_BEGIN 50 51 class CurrencyPluralInfo; 52 class CompactDecimalFormat; 53 54 namespace number { 55 class LocalizedNumberFormatter; 56 namespace impl { 57 class DecimalQuantity; 58 struct DecimalFormatFields; 59 class UFormattedNumberData; 60 } 61 } 62 63 namespace numparse { 64 namespace impl { 65 class NumberParserImpl; 66 } 67 } 68 69 /** 70 * **IMPORTANT:** New users are strongly encouraged to see if 71 * numberformatter.h fits their use case. Although not deprecated, this header 72 * is provided for backwards compatibility only. 73 * 74 * DecimalFormat is a concrete subclass of NumberFormat that formats decimal 75 * numbers. It has a variety of features designed to make it possible to parse 76 * and format numbers in any locale, including support for Western, Arabic, or 77 * Indic digits. It also supports different flavors of numbers, including 78 * integers ("123"), fixed-point numbers ("123.4"), scientific notation 79 * ("1.23E4"), percentages ("12%"), and currency amounts ("$123", "USD123", 80 * "123 US dollars"). All of these flavors can be easily localized. 81 * 82 * To obtain a NumberFormat for a specific locale (including the default 83 * locale) call one of NumberFormat's factory methods such as 84 * createInstance(). Do not call the DecimalFormat constructors directly, unless 85 * you know what you are doing, since the NumberFormat factory methods may 86 * return subclasses other than DecimalFormat. 87 * 88 * **Example Usage** 89 * 90 * \code 91 * // Normally we would have a GUI with a menu for this 92 * int32_t locCount; 93 * const Locale* locales = NumberFormat::getAvailableLocales(locCount); 94 * 95 * double myNumber = -1234.56; 96 * UErrorCode success = U_ZERO_ERROR; 97 * NumberFormat* form; 98 * 99 * // Print out a number with the localized number, currency and percent 100 * // format for each locale. 101 * UnicodeString countryName; 102 * UnicodeString displayName; 103 * UnicodeString str; 104 * UnicodeString pattern; 105 * Formattable fmtable; 106 * for (int32_t j = 0; j < 3; ++j) { 107 * cout << endl << "FORMAT " << j << endl; 108 * for (int32_t i = 0; i < locCount; ++i) { 109 * if (locales[i].getCountry(countryName).size() == 0) { 110 * // skip language-only 111 * continue; 112 * } 113 * switch (j) { 114 * case 0: 115 * form = NumberFormat::createInstance(locales[i], success ); break; 116 * case 1: 117 * form = NumberFormat::createCurrencyInstance(locales[i], success ); break; 118 * default: 119 * form = NumberFormat::createPercentInstance(locales[i], success ); break; 120 * } 121 * if (form) { 122 * str.remove(); 123 * pattern = ((DecimalFormat*)form)->toPattern(pattern); 124 * cout << locales[i].getDisplayName(displayName) << ": " << pattern; 125 * cout << " -> " << form->format(myNumber,str) << endl; 126 * form->parse(form->format(myNumber,str), fmtable, success); 127 * delete form; 128 * } 129 * } 130 * } 131 * \endcode 132 * 133 * **Another example use createInstance(style)** 134 * 135 * \code 136 * // Print out a number using the localized number, currency, 137 * // percent, scientific, integer, iso currency, and plural currency 138 * // format for each locale</strong> 139 * Locale* locale = new Locale("en", "US"); 140 * double myNumber = 1234.56; 141 * UErrorCode success = U_ZERO_ERROR; 142 * UnicodeString str; 143 * Formattable fmtable; 144 * for (int j=NumberFormat::kNumberStyle; 145 * j<=NumberFormat::kPluralCurrencyStyle; 146 * ++j) { 147 * NumberFormat* form = NumberFormat::createInstance(locale, j, success); 148 * str.remove(); 149 * cout << "format result " << form->format(myNumber, str) << endl; 150 * format->parse(form->format(myNumber, str), fmtable, success); 151 * delete form; 152 * } 153 * \endcode 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 positive 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 minimum 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 significant 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 significant 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 (char16_ts). 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 absence 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 * Pad position. 672 * @stable ICU 2.4 673 */ 674 enum EPadPosition { 675 kPadBeforePrefix, kPadAfterPrefix, kPadBeforeSuffix, kPadAfterSuffix 676 }; 677 678 /** 679 * Create a DecimalFormat using the default pattern and symbols 680 * for the default locale. This is a convenient way to obtain a 681 * DecimalFormat when internationalization is not the main concern. 682 * <P> 683 * To obtain standard formats for a given locale, use the factory methods 684 * on NumberFormat such as createInstance. These factories will 685 * return the most appropriate sub-class of NumberFormat for a given 686 * locale. 687 * <p> 688 * <strong>NOTE:</strong> New users are strongly encouraged to use 689 * #icu::number::NumberFormatter instead of DecimalFormat. 690 * @param status Output param set to success/failure code. If the 691 * pattern is invalid this will be set to a failure code. 692 * @stable ICU 2.0 693 */ 694 DecimalFormat(UErrorCode& status); 695 696 /** 697 * Create a DecimalFormat from the given pattern and the symbols 698 * for the default locale. This is a convenient way to obtain a 699 * DecimalFormat when internationalization is not the main concern. 700 * <P> 701 * To obtain standard formats for a given locale, use the factory methods 702 * on NumberFormat such as createInstance. These factories will 703 * return the most appropriate sub-class of NumberFormat for a given 704 * locale. 705 * <p> 706 * <strong>NOTE:</strong> New users are strongly encouraged to use 707 * #icu::number::NumberFormatter instead of DecimalFormat. 708 * @param pattern A non-localized pattern string. 709 * @param status Output param set to success/failure code. If the 710 * pattern is invalid this will be set to a failure code. 711 * @stable ICU 2.0 712 */ 713 DecimalFormat(const UnicodeString& pattern, UErrorCode& status); 714 715 /** 716 * Create a DecimalFormat from the given pattern and symbols. 717 * Use this constructor when you need to completely customize the 718 * behavior of the format. 719 * <P> 720 * To obtain standard formats for a given 721 * locale, use the factory methods on NumberFormat such as 722 * createInstance or createCurrencyInstance. If you need only minor adjustments 723 * to a standard format, you can modify the format returned by 724 * a NumberFormat factory method. 725 * <p> 726 * <strong>NOTE:</strong> New users are strongly encouraged to use 727 * #icu::number::NumberFormatter instead of DecimalFormat. 728 * 729 * @param pattern a non-localized pattern string 730 * @param symbolsToAdopt the set of symbols to be used. The caller should not 731 * delete this object after making this call. 732 * @param status Output param set to success/failure code. If the 733 * pattern is invalid this will be set to a failure code. 734 * @stable ICU 2.0 735 */ 736 DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, UErrorCode& status); 737 738 #ifndef U_HIDE_INTERNAL_API 739 740 /** 741 * This API is for ICU use only. 742 * Create a DecimalFormat from the given pattern, symbols, and style. 743 * 744 * @param pattern a non-localized pattern string 745 * @param symbolsToAdopt the set of symbols to be used. The caller should not 746 * delete this object after making this call. 747 * @param style style of decimal format 748 * @param status Output param set to success/failure code. If the 749 * pattern is invalid this will be set to a failure code. 750 * @internal 751 */ 752 DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, 753 UNumberFormatStyle style, UErrorCode& status); 754 755 #if UCONFIG_HAVE_PARSEALLINPUT 756 757 /** 758 * @internal 759 */ 760 void setParseAllInput(UNumberFormatAttributeValue value); 761 762 #endif 763 764 #endif /* U_HIDE_INTERNAL_API */ 765 766 private: 767 768 /** 769 * Internal constructor for DecimalFormat; sets up internal fields. All public constructors should 770 * call this constructor. 771 */ 772 DecimalFormat(const DecimalFormatSymbols* symbolsToAdopt, UErrorCode& status); 773 774 public: 775 776 /** 777 * Set an integer attribute on this DecimalFormat. 778 * May return U_UNSUPPORTED_ERROR if this instance does not support 779 * the specified attribute. 780 * @param attr the attribute to set 781 * @param newValue new value 782 * @param status the error type 783 * @return *this - for chaining (example: format.setAttribute(...).setAttribute(...) ) 784 * @stable ICU 51 785 */ 786 virtual DecimalFormat& setAttribute(UNumberFormatAttribute attr, int32_t newValue, UErrorCode& status); 787 788 /** 789 * Get an integer 790 * May return U_UNSUPPORTED_ERROR if this instance does not support 791 * the specified attribute. 792 * @param attr the attribute to set 793 * @param status the error type 794 * @return the attribute value. Undefined if there is an error. 795 * @stable ICU 51 796 */ 797 virtual int32_t getAttribute(UNumberFormatAttribute attr, UErrorCode& status) const; 798 799 800 /** 801 * Set whether or not grouping will be used in this format. 802 * @param newValue True, grouping will be used in this format. 803 * @see getGroupingUsed 804 * @stable ICU 53 805 */ 806 void setGroupingUsed(UBool newValue) override; 807 808 /** 809 * Sets whether or not numbers should be parsed as integers only. 810 * @param value set True, this format will parse numbers as integers 811 * only. 812 * @see isParseIntegerOnly 813 * @stable ICU 53 814 */ 815 void setParseIntegerOnly(UBool value) override; 816 817 /** 818 * Sets whether lenient parsing should be enabled (it is off by default). 819 * 820 * @param enable \c true if lenient parsing should be used, 821 * \c false otherwise. 822 * @stable ICU 4.8 823 */ 824 void setLenient(UBool enable) override; 825 826 /** 827 * Create a DecimalFormat from the given pattern and symbols. 828 * Use this constructor when you need to completely customize the 829 * behavior of the format. 830 * <P> 831 * To obtain standard formats for a given 832 * locale, use the factory methods on NumberFormat such as 833 * createInstance or createCurrencyInstance. If you need only minor adjustments 834 * to a standard format, you can modify the format returned by 835 * a NumberFormat factory method. 836 * <p> 837 * <strong>NOTE:</strong> New users are strongly encouraged to use 838 * #icu::number::NumberFormatter instead of DecimalFormat. 839 * 840 * @param pattern a non-localized pattern string 841 * @param symbolsToAdopt the set of symbols to be used. The caller should not 842 * delete this object after making this call. 843 * @param parseError Output param to receive errors occurred during parsing 844 * @param status Output param set to success/failure code. If the 845 * pattern is invalid this will be set to a failure code. 846 * @stable ICU 2.0 847 */ 848 DecimalFormat(const UnicodeString& pattern, DecimalFormatSymbols* symbolsToAdopt, 849 UParseError& parseError, UErrorCode& status); 850 851 /** 852 * Create a DecimalFormat from the given pattern and symbols. 853 * Use this constructor when you need to completely customize the 854 * behavior of the format. 855 * <P> 856 * To obtain standard formats for a given 857 * locale, use the factory methods on NumberFormat such as 858 * createInstance or createCurrencyInstance. If you need only minor adjustments 859 * to a standard format, you can modify the format returned by 860 * a NumberFormat factory method. 861 * <p> 862 * <strong>NOTE:</strong> New users are strongly encouraged to use 863 * #icu::number::NumberFormatter instead of DecimalFormat. 864 * 865 * @param pattern a non-localized pattern string 866 * @param symbols the set of symbols to be used 867 * @param status Output param set to success/failure code. If the 868 * pattern is invalid this will be set to a failure code. 869 * @stable ICU 2.0 870 */ 871 DecimalFormat(const UnicodeString& pattern, const DecimalFormatSymbols& symbols, UErrorCode& status); 872 873 /** 874 * Copy constructor. 875 * 876 * @param source the DecimalFormat object to be copied from. 877 * @stable ICU 2.0 878 */ 879 DecimalFormat(const DecimalFormat& source); 880 881 /** 882 * Assignment operator. 883 * 884 * @param rhs the DecimalFormat object to be copied. 885 * @stable ICU 2.0 886 */ 887 DecimalFormat& operator=(const DecimalFormat& rhs); 888 889 /** 890 * Destructor. 891 * @stable ICU 2.0 892 */ 893 ~DecimalFormat() override; 894 895 /** 896 * Clone this Format object polymorphically. The caller owns the 897 * result and should delete it when done. 898 * 899 * @return a polymorphic copy of this DecimalFormat. 900 * @stable ICU 2.0 901 */ 902 DecimalFormat* clone() const override; 903 904 /** 905 * Return true if the given Format objects are semantically equal. 906 * Objects of different subclasses are considered unequal. 907 * 908 * @param other the object to be compared with. 909 * @return true if the given Format objects are semantically equal. 910 * @stable ICU 2.0 911 */ 912 bool operator==(const Format& other) const override; 913 914 915 using NumberFormat::format; 916 917 /** 918 * Format a double or long number using base-10 representation. 919 * 920 * @param number The value to be formatted. 921 * @param appendTo Output parameter to receive result. 922 * Result is appended to existing contents. 923 * @param pos On input: an alignment field, if desired. 924 * On output: the offsets of the alignment field. 925 * @return Reference to 'appendTo' parameter. 926 * @stable ICU 2.0 927 */ 928 UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos) const override; 929 930 #ifndef U_HIDE_INTERNAL_API 931 /** 932 * Format a double or long number using base-10 representation. 933 * 934 * @param number The value to be formatted. 935 * @param appendTo Output parameter to receive result. 936 * Result is appended to existing contents. 937 * @param pos On input: an alignment field, if desired. 938 * On output: the offsets of the alignment field. 939 * @param status 940 * @return Reference to 'appendTo' parameter. 941 * @internal 942 */ 943 UnicodeString& format(double number, UnicodeString& appendTo, FieldPosition& pos, 944 UErrorCode& status) const override; 945 #endif /* U_HIDE_INTERNAL_API */ 946 947 /** 948 * Format a double or long number using base-10 representation. 949 * 950 * @param number The value to be formatted. 951 * @param appendTo Output parameter to receive result. 952 * Result is appended to existing contents. 953 * @param posIter On return, can be used to iterate over positions 954 * of fields generated by this format call. 955 * Can be nullptr. 956 * @param status Output param filled with success/failure status. 957 * @return Reference to 'appendTo' parameter. 958 * @stable ICU 4.4 959 */ 960 UnicodeString& format(double number, UnicodeString& appendTo, FieldPositionIterator* posIter, 961 UErrorCode& status) const override; 962 963 /** 964 * Format a long number using base-10 representation. 965 * 966 * @param number The value to be formatted. 967 * @param appendTo Output parameter to receive result. 968 * Result is appended to existing contents. 969 * @param pos On input: an alignment field, if desired. 970 * On output: the offsets of the alignment field. 971 * @return Reference to 'appendTo' parameter. 972 * @stable ICU 2.0 973 */ 974 UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPosition& pos) const override; 975 976 #ifndef U_HIDE_INTERNAL_API 977 /** 978 * Format a long number using base-10 representation. 979 * 980 * @param number The value to be formatted. 981 * @param appendTo Output parameter to receive result. 982 * Result is appended to existing contents. 983 * @param pos On input: an alignment field, if desired. 984 * On output: the offsets of the alignment field. 985 * @param status Output param filled with success/failure status. 986 * @return Reference to 'appendTo' parameter. 987 * @internal 988 */ 989 UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPosition& pos, 990 UErrorCode& status) const override; 991 #endif /* U_HIDE_INTERNAL_API */ 992 993 /** 994 * Format a long number using base-10 representation. 995 * 996 * @param number The value to be formatted. 997 * @param appendTo Output parameter to receive result. 998 * Result is appended to existing contents. 999 * @param posIter On return, can be used to iterate over positions 1000 * of fields generated by this format call. 1001 * Can be nullptr. 1002 * @param status Output param filled with success/failure status. 1003 * @return Reference to 'appendTo' parameter. 1004 * @stable ICU 4.4 1005 */ 1006 UnicodeString& format(int32_t number, UnicodeString& appendTo, FieldPositionIterator* posIter, 1007 UErrorCode& status) const override; 1008 1009 /** 1010 * Format an int64 number using base-10 representation. 1011 * 1012 * @param number The value to be formatted. 1013 * @param appendTo Output parameter to receive result. 1014 * Result is appended to existing contents. 1015 * @param pos On input: an alignment field, if desired. 1016 * On output: the offsets of the alignment field. 1017 * @return Reference to 'appendTo' parameter. 1018 * @stable ICU 2.8 1019 */ 1020 UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos) const override; 1021 1022 #ifndef U_HIDE_INTERNAL_API 1023 /** 1024 * Format an int64 number using base-10 representation. 1025 * 1026 * @param number The value to be formatted. 1027 * @param appendTo Output parameter to receive result. 1028 * Result is appended to existing contents. 1029 * @param pos On input: an alignment field, if desired. 1030 * On output: the offsets of the alignment field. 1031 * @param status Output param filled with success/failure status. 1032 * @return Reference to 'appendTo' parameter. 1033 * @internal 1034 */ 1035 UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPosition& pos, 1036 UErrorCode& status) const override; 1037 #endif /* U_HIDE_INTERNAL_API */ 1038 1039 /** 1040 * Format an int64 number using base-10 representation. 1041 * 1042 * @param number The value to be formatted. 1043 * @param appendTo Output parameter to receive result. 1044 * Result is appended to existing contents. 1045 * @param posIter On return, can be used to iterate over positions 1046 * of fields generated by this format call. 1047 * Can be nullptr. 1048 * @param status Output param filled with success/failure status. 1049 * @return Reference to 'appendTo' parameter. 1050 * @stable ICU 4.4 1051 */ 1052 UnicodeString& format(int64_t number, UnicodeString& appendTo, FieldPositionIterator* posIter, 1053 UErrorCode& status) const override; 1054 1055 /** 1056 * Format a decimal number. 1057 * The syntax of the unformatted number is a "numeric string" 1058 * as defined in the Decimal Arithmetic Specification, available at 1059 * http://speleotrove.com/decimal 1060 * 1061 * @param number The unformatted number, as a string. 1062 * @param appendTo Output parameter to receive result. 1063 * Result is appended to existing contents. 1064 * @param posIter On return, can be used to iterate over positions 1065 * of fields generated by this format call. 1066 * Can be nullptr. 1067 * @param status Output param filled with success/failure status. 1068 * @return Reference to 'appendTo' parameter. 1069 * @stable ICU 4.4 1070 */ 1071 UnicodeString& format(StringPiece number, UnicodeString& appendTo, FieldPositionIterator* posIter, 1072 UErrorCode& status) const override; 1073 1074 #ifndef U_HIDE_INTERNAL_API 1075 1076 /** 1077 * Format a decimal number. 1078 * The number is a DecimalQuantity wrapper onto a floating point decimal number. 1079 * The default implementation in NumberFormat converts the decimal number 1080 * to a double and formats that. 1081 * 1082 * @param number The number, a DecimalQuantity format Decimal Floating Point. 1083 * @param appendTo Output parameter to receive result. 1084 * Result is appended to existing contents. 1085 * @param posIter On return, can be used to iterate over positions 1086 * of fields generated by this format call. 1087 * @param status Output param filled with success/failure status. 1088 * @return Reference to 'appendTo' parameter. 1089 * @internal 1090 */ 1091 UnicodeString& format(const number::impl::DecimalQuantity& number, UnicodeString& appendTo, 1092 FieldPositionIterator* posIter, UErrorCode& status) const override; 1093 1094 /** 1095 * Format a decimal number. 1096 * The number is a DecimalQuantity wrapper onto a floating point decimal number. 1097 * The default implementation in NumberFormat converts the decimal number 1098 * to a double and formats that. 1099 * 1100 * @param number The number, a DecimalQuantity format Decimal Floating Point. 1101 * @param appendTo Output parameter to receive result. 1102 * Result is appended to existing contents. 1103 * @param pos On input: an alignment field, if desired. 1104 * On output: the offsets of the alignment field. 1105 * @param status Output param filled with success/failure status. 1106 * @return Reference to 'appendTo' parameter. 1107 * @internal 1108 */ 1109 UnicodeString& format(const number::impl::DecimalQuantity& number, UnicodeString& appendTo, 1110 FieldPosition& pos, UErrorCode& status) const override; 1111 1112 #endif // U_HIDE_INTERNAL_API 1113 1114 using NumberFormat::parse; 1115 1116 /** 1117 * Parse the given string using this object's choices. The method 1118 * does string comparisons to try to find an optimal match. 1119 * If no object can be parsed, index is unchanged, and nullptr is 1120 * returned. The result is returned as the most parsimonious 1121 * type of Formattable that will accommodate all of the 1122 * necessary precision. For example, if the result is exactly 12, 1123 * it will be returned as a long. However, if it is 1.5, it will 1124 * be returned as a double. 1125 * 1126 * @param text The text to be parsed. 1127 * @param result Formattable to be set to the parse result. 1128 * If parse fails, return contents are undefined. 1129 * @param parsePosition The position to start parsing at on input. 1130 * On output, moved to after the last successfully 1131 * parse character. On parse failure, does not change. 1132 * @see Formattable 1133 * @stable ICU 2.0 1134 */ 1135 void parse(const UnicodeString& text, Formattable& result, 1136 ParsePosition& parsePosition) const override; 1137 1138 /** 1139 * Parses text from the given string as a currency amount. Unlike 1140 * the parse() method, this method will attempt to parse a generic 1141 * currency name, searching for a match of this object's locale's 1142 * currency display names, or for a 3-letter ISO currency code. 1143 * This method will fail if this format is not a currency format, 1144 * that is, if it does not contain the currency pattern symbol 1145 * (U+00A4) in its prefix or suffix. 1146 * 1147 * @param text the string to parse 1148 * @param pos input-output position; on input, the position within text 1149 * to match; must have 0 <= pos.getIndex() < text.length(); 1150 * on output, the position after the last matched character. 1151 * If the parse fails, the position in unchanged upon output. 1152 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount 1153 * object (owned by the caller) containing information about 1154 * the parsed currency; if parse fails, this is nullptr. 1155 * @stable ICU 49 1156 */ 1157 CurrencyAmount* parseCurrency(const UnicodeString& text, ParsePosition& pos) const override; 1158 1159 /** 1160 * Returns the decimal format symbols, which is generally not changed 1161 * by the programmer or user. 1162 * @return desired DecimalFormatSymbols 1163 * @see DecimalFormatSymbols 1164 * @stable ICU 2.0 1165 */ 1166 virtual const DecimalFormatSymbols* getDecimalFormatSymbols(void) const; 1167 1168 /** 1169 * Sets the decimal format symbols, which is generally not changed 1170 * by the programmer or user. 1171 * @param symbolsToAdopt DecimalFormatSymbols to be adopted. 1172 * @stable ICU 2.0 1173 */ 1174 virtual void adoptDecimalFormatSymbols(DecimalFormatSymbols* symbolsToAdopt); 1175 1176 /** 1177 * Sets the decimal format symbols, which is generally not changed 1178 * by the programmer or user. 1179 * @param symbols DecimalFormatSymbols. 1180 * @stable ICU 2.0 1181 */ 1182 virtual void setDecimalFormatSymbols(const DecimalFormatSymbols& symbols); 1183 1184 1185 /** 1186 * Returns the currency plural format information, 1187 * which is generally not changed by the programmer or user. 1188 * @return desired CurrencyPluralInfo 1189 * @stable ICU 4.2 1190 */ 1191 virtual const CurrencyPluralInfo* getCurrencyPluralInfo(void) const; 1192 1193 /** 1194 * Sets the currency plural format information, 1195 * which is generally not changed by the programmer or user. 1196 * @param toAdopt CurrencyPluralInfo to be adopted. 1197 * @stable ICU 4.2 1198 */ 1199 virtual void adoptCurrencyPluralInfo(CurrencyPluralInfo* toAdopt); 1200 1201 /** 1202 * Sets the currency plural format information, 1203 * which is generally not changed by the programmer or user. 1204 * @param info Currency Plural Info. 1205 * @stable ICU 4.2 1206 */ 1207 virtual void setCurrencyPluralInfo(const CurrencyPluralInfo& info); 1208 1209 1210 /** 1211 * Get the positive prefix. 1212 * 1213 * @param result Output param which will receive the positive prefix. 1214 * @return A reference to 'result'. 1215 * Examples: +123, $123, sFr123 1216 * @stable ICU 2.0 1217 */ 1218 UnicodeString& getPositivePrefix(UnicodeString& result) const; 1219 1220 /** 1221 * Set the positive prefix. 1222 * 1223 * @param newValue the new value of the the positive prefix to be set. 1224 * Examples: +123, $123, sFr123 1225 * @stable ICU 2.0 1226 */ 1227 virtual void setPositivePrefix(const UnicodeString& newValue); 1228 1229 /** 1230 * Get the negative prefix. 1231 * 1232 * @param result Output param which will receive the negative prefix. 1233 * @return A reference to 'result'. 1234 * Examples: -123, ($123) (with negative suffix), sFr-123 1235 * @stable ICU 2.0 1236 */ 1237 UnicodeString& getNegativePrefix(UnicodeString& result) const; 1238 1239 /** 1240 * Set the negative prefix. 1241 * 1242 * @param newValue the new value of the the negative prefix to be set. 1243 * Examples: -123, ($123) (with negative suffix), sFr-123 1244 * @stable ICU 2.0 1245 */ 1246 virtual void setNegativePrefix(const UnicodeString& newValue); 1247 1248 /** 1249 * Get the positive suffix. 1250 * 1251 * @param result Output param which will receive the positive suffix. 1252 * @return A reference to 'result'. 1253 * Example: 123% 1254 * @stable ICU 2.0 1255 */ 1256 UnicodeString& getPositiveSuffix(UnicodeString& result) const; 1257 1258 /** 1259 * Set the positive suffix. 1260 * 1261 * @param newValue the new value of the positive suffix to be set. 1262 * Example: 123% 1263 * @stable ICU 2.0 1264 */ 1265 virtual void setPositiveSuffix(const UnicodeString& newValue); 1266 1267 /** 1268 * Get the negative suffix. 1269 * 1270 * @param result Output param which will receive the negative suffix. 1271 * @return A reference to 'result'. 1272 * Examples: -123%, ($123) (with positive suffixes) 1273 * @stable ICU 2.0 1274 */ 1275 UnicodeString& getNegativeSuffix(UnicodeString& result) const; 1276 1277 /** 1278 * Set the negative suffix. 1279 * 1280 * @param newValue the new value of the negative suffix to be set. 1281 * Examples: 123% 1282 * @stable ICU 2.0 1283 */ 1284 virtual void setNegativeSuffix(const UnicodeString& newValue); 1285 1286 /** 1287 * Whether to show the plus sign on positive (non-negative) numbers; for example, "+12" 1288 * 1289 * For more control over sign display, use NumberFormatter. 1290 * 1291 * @return Whether the sign is shown on positive numbers and zero. 1292 * @stable ICU 64 1293 */ 1294 UBool isSignAlwaysShown() const; 1295 1296 /** 1297 * Set whether to show the plus sign on positive (non-negative) numbers; for example, "+12". 1298 * 1299 * For more control over sign display, use NumberFormatter. 1300 * 1301 * @param value true to always show a sign; false to hide the sign on positive numbers and zero. 1302 * @stable ICU 64 1303 */ 1304 void setSignAlwaysShown(UBool value); 1305 1306 /** 1307 * Get the multiplier for use in percent, permill, etc. 1308 * For a percentage, set the suffixes to have "%" and the multiplier to be 100. 1309 * (For Arabic, use arabic percent symbol). 1310 * For a permill, set the suffixes to have "\\u2031" and the multiplier to be 1000. 1311 * 1312 * The number may also be multiplied by a power of ten; see getMultiplierScale(). 1313 * 1314 * @return the multiplier for use in percent, permill, etc. 1315 * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 1316 * @stable ICU 2.0 1317 */ 1318 int32_t getMultiplier(void) const; 1319 1320 /** 1321 * Set the multiplier for use in percent, permill, etc. 1322 * For a percentage, set the suffixes to have "%" and the multiplier to be 100. 1323 * (For Arabic, use arabic percent symbol). 1324 * For a permill, set the suffixes to have "\\u2031" and the multiplier to be 1000. 1325 * 1326 * This method only supports integer multipliers. To multiply by a non-integer, pair this 1327 * method with setMultiplierScale(). 1328 * 1329 * @param newValue the new value of the multiplier for use in percent, permill, etc. 1330 * Examples: with 100, 1.23 -> "123", and "123" -> 1.23 1331 * @stable ICU 2.0 1332 */ 1333 virtual void setMultiplier(int32_t newValue); 1334 1335 /** 1336 * Gets the power of ten by which number should be multiplied before formatting, which 1337 * can be combined with setMultiplier() to multiply by any arbitrary decimal value. 1338 * 1339 * A multiplier scale of 2 corresponds to multiplication by 100, and a multiplier scale 1340 * of -2 corresponds to multiplication by 0.01. 1341 * 1342 * This method is analogous to UNUM_SCALE in getAttribute. 1343 * 1344 * @return the current value of the power-of-ten multiplier. 1345 * @stable ICU 62 1346 */ 1347 int32_t getMultiplierScale(void) const; 1348 1349 /** 1350 * Sets a power of ten by which number should be multiplied before formatting, which 1351 * can be combined with setMultiplier() to multiply by any arbitrary decimal value. 1352 * 1353 * A multiplier scale of 2 corresponds to multiplication by 100, and a multiplier scale 1354 * of -2 corresponds to multiplication by 0.01. 1355 * 1356 * For example, to multiply numbers by 0.5 before formatting, you can do: 1357 * 1358 * <pre> 1359 * df.setMultiplier(5); 1360 * df.setMultiplierScale(-1); 1361 * </pre> 1362 * 1363 * This method is analogous to UNUM_SCALE in setAttribute. 1364 * 1365 * @param newValue the new value of the power-of-ten multiplier. 1366 * @stable ICU 62 1367 */ 1368 void setMultiplierScale(int32_t newValue); 1369 1370 /** 1371 * Get the rounding increment. 1372 * @return A positive rounding increment, or 0.0 if a custom rounding 1373 * increment is not in effect. 1374 * @see #setRoundingIncrement 1375 * @see #getRoundingMode 1376 * @see #setRoundingMode 1377 * @stable ICU 2.0 1378 */ 1379 virtual double getRoundingIncrement(void) const; 1380 1381 /** 1382 * Set the rounding increment. In the absence of a rounding increment, 1383 * numbers will be rounded to the number of digits displayed. 1384 * @param newValue A positive rounding increment, or 0.0 to 1385 * use the default rounding increment. 1386 * Negative increments are equivalent to 0.0. 1387 * @see #getRoundingIncrement 1388 * @see #getRoundingMode 1389 * @see #setRoundingMode 1390 * @stable ICU 2.0 1391 */ 1392 virtual void setRoundingIncrement(double newValue); 1393 1394 /** 1395 * Get the rounding mode. 1396 * @return A rounding mode 1397 * @see #setRoundingIncrement 1398 * @see #getRoundingIncrement 1399 * @see #setRoundingMode 1400 * @stable ICU 2.0 1401 */ 1402 virtual ERoundingMode getRoundingMode(void) const override; 1403 1404 /** 1405 * Set the rounding mode. 1406 * @param roundingMode A rounding mode 1407 * @see #setRoundingIncrement 1408 * @see #getRoundingIncrement 1409 * @see #getRoundingMode 1410 * @stable ICU 2.0 1411 */ 1412 virtual void setRoundingMode(ERoundingMode roundingMode) override; 1413 1414 /** 1415 * Get the width to which the output of format() is padded. 1416 * The width is counted in 16-bit code units. 1417 * @return the format width, or zero if no padding is in effect 1418 * @see #setFormatWidth 1419 * @see #getPadCharacterString 1420 * @see #setPadCharacter 1421 * @see #getPadPosition 1422 * @see #setPadPosition 1423 * @stable ICU 2.0 1424 */ 1425 virtual int32_t getFormatWidth(void) const; 1426 1427 /** 1428 * Set the width to which the output of format() is padded. 1429 * The width is counted in 16-bit code units. 1430 * This method also controls whether padding is enabled. 1431 * @param width the width to which to pad the result of 1432 * format(), or zero to disable padding. A negative 1433 * width is equivalent to 0. 1434 * @see #getFormatWidth 1435 * @see #getPadCharacterString 1436 * @see #setPadCharacter 1437 * @see #getPadPosition 1438 * @see #setPadPosition 1439 * @stable ICU 2.0 1440 */ 1441 virtual void setFormatWidth(int32_t width); 1442 1443 /** 1444 * Get the pad character used to pad to the format width. The 1445 * default is ' '. 1446 * @return a string containing the pad character. This will always 1447 * have a length of one 32-bit code point. 1448 * @see #setFormatWidth 1449 * @see #getFormatWidth 1450 * @see #setPadCharacter 1451 * @see #getPadPosition 1452 * @see #setPadPosition 1453 * @stable ICU 2.0 1454 */ 1455 virtual UnicodeString getPadCharacterString() const; 1456 1457 /** 1458 * Set the character used to pad to the format width. If padding 1459 * is not enabled, then this will take effect if padding is later 1460 * enabled. 1461 * @param padChar a string containing the pad character. If the string 1462 * has length 0, then the pad character is set to ' '. Otherwise 1463 * padChar.char32At(0) will be used as the pad character. 1464 * @see #setFormatWidth 1465 * @see #getFormatWidth 1466 * @see #getPadCharacterString 1467 * @see #getPadPosition 1468 * @see #setPadPosition 1469 * @stable ICU 2.0 1470 */ 1471 virtual void setPadCharacter(const UnicodeString& padChar); 1472 1473 /** 1474 * Get the position at which padding will take place. This is the location 1475 * at which padding will be inserted if the result of format() 1476 * is shorter than the format width. 1477 * @return the pad position, one of kPadBeforePrefix, 1478 * kPadAfterPrefix, kPadBeforeSuffix, or 1479 * kPadAfterSuffix. 1480 * @see #setFormatWidth 1481 * @see #getFormatWidth 1482 * @see #setPadCharacter 1483 * @see #getPadCharacterString 1484 * @see #setPadPosition 1485 * @see #EPadPosition 1486 * @stable ICU 2.0 1487 */ 1488 virtual EPadPosition getPadPosition(void) const; 1489 1490 /** 1491 * Set the position at which padding will take place. This is the location 1492 * at which padding will be inserted if the result of format() 1493 * is shorter than the format width. This has no effect unless padding is 1494 * enabled. 1495 * @param padPos the pad position, one of kPadBeforePrefix, 1496 * kPadAfterPrefix, kPadBeforeSuffix, or 1497 * kPadAfterSuffix. 1498 * @see #setFormatWidth 1499 * @see #getFormatWidth 1500 * @see #setPadCharacter 1501 * @see #getPadCharacterString 1502 * @see #getPadPosition 1503 * @see #EPadPosition 1504 * @stable ICU 2.0 1505 */ 1506 virtual void setPadPosition(EPadPosition padPos); 1507 1508 /** 1509 * Return whether or not scientific notation is used. 1510 * @return true if this object formats and parses scientific notation 1511 * @see #setScientificNotation 1512 * @see #getMinimumExponentDigits 1513 * @see #setMinimumExponentDigits 1514 * @see #isExponentSignAlwaysShown 1515 * @see #setExponentSignAlwaysShown 1516 * @stable ICU 2.0 1517 */ 1518 virtual UBool isScientificNotation(void) const; 1519 1520 /** 1521 * Set whether or not scientific notation is used. When scientific notation 1522 * is used, the effective maximum number of integer digits is <= 8. If the 1523 * maximum number of integer digits is set to more than 8, the effective 1524 * maximum will be 1. This allows this call to generate a 'default' scientific 1525 * number format without additional changes. 1526 * @param useScientific true if this object formats and parses scientific 1527 * notation 1528 * @see #isScientificNotation 1529 * @see #getMinimumExponentDigits 1530 * @see #setMinimumExponentDigits 1531 * @see #isExponentSignAlwaysShown 1532 * @see #setExponentSignAlwaysShown 1533 * @stable ICU 2.0 1534 */ 1535 virtual void setScientificNotation(UBool useScientific); 1536 1537 /** 1538 * Return the minimum exponent digits that will be shown. 1539 * @return the minimum exponent digits that will be shown 1540 * @see #setScientificNotation 1541 * @see #isScientificNotation 1542 * @see #setMinimumExponentDigits 1543 * @see #isExponentSignAlwaysShown 1544 * @see #setExponentSignAlwaysShown 1545 * @stable ICU 2.0 1546 */ 1547 virtual int8_t getMinimumExponentDigits(void) const; 1548 1549 /** 1550 * Set the minimum exponent digits that will be shown. This has no 1551 * effect unless scientific notation is in use. 1552 * @param minExpDig a value >= 1 indicating the fewest exponent digits 1553 * that will be shown. Values less than 1 will be treated as 1. 1554 * @see #setScientificNotation 1555 * @see #isScientificNotation 1556 * @see #getMinimumExponentDigits 1557 * @see #isExponentSignAlwaysShown 1558 * @see #setExponentSignAlwaysShown 1559 * @stable ICU 2.0 1560 */ 1561 virtual void setMinimumExponentDigits(int8_t minExpDig); 1562 1563 /** 1564 * Return whether the exponent sign is always shown. 1565 * @return true if the exponent is always prefixed with either the 1566 * localized minus sign or the localized plus sign, false if only negative 1567 * exponents are prefixed with the localized minus sign. 1568 * @see #setScientificNotation 1569 * @see #isScientificNotation 1570 * @see #setMinimumExponentDigits 1571 * @see #getMinimumExponentDigits 1572 * @see #setExponentSignAlwaysShown 1573 * @stable ICU 2.0 1574 */ 1575 virtual UBool isExponentSignAlwaysShown(void) const; 1576 1577 /** 1578 * Set whether the exponent sign is always shown. This has no effect 1579 * unless scientific notation is in use. 1580 * @param expSignAlways true if the exponent is always prefixed with either 1581 * the localized minus sign or the localized plus sign, false if only 1582 * negative exponents are prefixed with the localized minus sign. 1583 * @see #setScientificNotation 1584 * @see #isScientificNotation 1585 * @see #setMinimumExponentDigits 1586 * @see #getMinimumExponentDigits 1587 * @see #isExponentSignAlwaysShown 1588 * @stable ICU 2.0 1589 */ 1590 virtual void setExponentSignAlwaysShown(UBool expSignAlways); 1591 1592 /** 1593 * Return the grouping size. Grouping size is the number of digits between 1594 * grouping separators in the integer portion of a number. For example, 1595 * in the number "123,456.78", the grouping size is 3. 1596 * 1597 * @return the grouping size. 1598 * @see setGroupingSize 1599 * @see NumberFormat::isGroupingUsed 1600 * @see DecimalFormatSymbols::getGroupingSeparator 1601 * @stable ICU 2.0 1602 */ 1603 int32_t getGroupingSize(void) const; 1604 1605 /** 1606 * Set the grouping size. Grouping size is the number of digits between 1607 * grouping separators in the integer portion of a number. For example, 1608 * in the number "123,456.78", the grouping size is 3. 1609 * 1610 * @param newValue the new value of the grouping size. 1611 * @see getGroupingSize 1612 * @see NumberFormat::setGroupingUsed 1613 * @see DecimalFormatSymbols::setGroupingSeparator 1614 * @stable ICU 2.0 1615 */ 1616 virtual void setGroupingSize(int32_t newValue); 1617 1618 /** 1619 * Return the secondary grouping size. In some locales one 1620 * grouping interval is used for the least significant integer 1621 * digits (the primary grouping size), and another is used for all 1622 * others (the secondary grouping size). A formatter supporting a 1623 * secondary grouping size will return a positive integer unequal 1624 * to the primary grouping size returned by 1625 * getGroupingSize(). For example, if the primary 1626 * grouping size is 4, and the secondary grouping size is 2, then 1627 * the number 123456789 formats as "1,23,45,6789", and the pattern 1628 * appears as "#,##,###0". 1629 * @return the secondary grouping size, or a value less than 1630 * one if there is none 1631 * @see setSecondaryGroupingSize 1632 * @see NumberFormat::isGroupingUsed 1633 * @see DecimalFormatSymbols::getGroupingSeparator 1634 * @stable ICU 2.4 1635 */ 1636 int32_t getSecondaryGroupingSize(void) const; 1637 1638 /** 1639 * Set the secondary grouping size. If set to a value less than 1, 1640 * then secondary grouping is turned off, and the primary grouping 1641 * size is used for all intervals, not just the least significant. 1642 * 1643 * @param newValue the new value of the secondary grouping size. 1644 * @see getSecondaryGroupingSize 1645 * @see NumberFormat#setGroupingUsed 1646 * @see DecimalFormatSymbols::setGroupingSeparator 1647 * @stable ICU 2.4 1648 */ 1649 virtual void setSecondaryGroupingSize(int32_t newValue); 1650 1651 /** 1652 * Returns the minimum number of grouping digits. 1653 * Grouping separators are output if there are at least this many 1654 * digits to the left of the first (rightmost) grouping separator, 1655 * that is, there are at least (minimum grouping + grouping size) integer digits. 1656 * (Subject to isGroupingUsed().) 1657 * 1658 * For example, if this value is 2, and the grouping size is 3, then 1659 * 9999 -> "9999" and 10000 -> "10,000" 1660 * 1661 * The default value for this attribute is 0. 1662 * A value of 1, 0, or lower, means that the use of grouping separators 1663 * only depends on the grouping size (and on isGroupingUsed()). 1664 * 1665 * NOTE: The CLDR data is used in NumberFormatter but not in DecimalFormat. 1666 * This is for backwards compatibility reasons. 1667 * 1668 * For more control over grouping strategies, use NumberFormatter. 1669 * 1670 * @see setMinimumGroupingDigits 1671 * @see getGroupingSize 1672 * @stable ICU 64 1673 */ 1674 int32_t getMinimumGroupingDigits() const; 1675 1676 /** 1677 * Sets the minimum grouping digits. Setting the value to 1678 * - 1: Turns off minimum grouping digits. 1679 * - 0 or -1: The behavior is undefined. 1680 * - UNUM_MINIMUM_GROUPING_DIGITS_AUTO: Display grouping using the default 1681 * strategy for all locales. 1682 * - UNUM_MINIMUM_GROUPING_DIGITS_MIN2: Display grouping using locale 1683 * defaults, except do not show grouping on values smaller than 10000 1684 * (such that there is a minimum of two digits before the first 1685 * separator). 1686 * 1687 * For more control over grouping strategies, use NumberFormatter. 1688 * 1689 * @param newValue the new value of minimum grouping digits. 1690 * @see getMinimumGroupingDigits 1691 * @stable ICU 64 1692 */ 1693 void setMinimumGroupingDigits(int32_t newValue); 1694 1695 /** 1696 * Allows you to get the behavior of the decimal separator with integers. 1697 * (The decimal separator will always appear with decimals.) 1698 * 1699 * @return true if the decimal separator always appear with decimals. 1700 * Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345 1701 * @stable ICU 2.0 1702 */ 1703 UBool isDecimalSeparatorAlwaysShown(void) const; 1704 1705 /** 1706 * Allows you to set the behavior of the decimal separator with integers. 1707 * (The decimal separator will always appear with decimals.) 1708 * 1709 * @param newValue set true if the decimal separator will always appear with decimals. 1710 * Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345 1711 * @stable ICU 2.0 1712 */ 1713 virtual void setDecimalSeparatorAlwaysShown(UBool newValue); 1714 1715 /** 1716 * Allows you to get the parse behavior of the pattern decimal mark. 1717 * 1718 * @return true if input must contain a match to decimal mark in pattern 1719 * @stable ICU 54 1720 */ 1721 UBool isDecimalPatternMatchRequired(void) const; 1722 1723 /** 1724 * Allows you to set the parse behavior of the pattern decimal mark. 1725 * 1726 * if true, the input must have a decimal mark if one was specified in the pattern. When 1727 * false the decimal mark may be omitted from the input. 1728 * 1729 * @param newValue set true if input must contain a match to decimal mark in pattern 1730 * @stable ICU 54 1731 */ 1732 virtual void setDecimalPatternMatchRequired(UBool newValue); 1733 1734 /** 1735 * Returns whether to ignore exponents when parsing. 1736 * 1737 * @return Whether to ignore exponents when parsing. 1738 * @see #setParseNoExponent 1739 * @stable ICU 64 1740 */ 1741 UBool isParseNoExponent() const; 1742 1743 /** 1744 * Specifies whether to stop parsing when an exponent separator is encountered. For 1745 * example, parses "123E4" to 123 (with parse position 3) instead of 1230000 (with parse position 1746 * 5). 1747 * 1748 * @param value true to prevent exponents from being parsed; false to allow them to be parsed. 1749 * @stable ICU 64 1750 */ 1751 void setParseNoExponent(UBool value); 1752 1753 /** 1754 * Returns whether parsing is sensitive to case (lowercase/uppercase). 1755 * 1756 * @return Whether parsing is case-sensitive. 1757 * @see #setParseCaseSensitive 1758 * @stable ICU 64 1759 */ 1760 UBool isParseCaseSensitive() const; 1761 1762 /** 1763 * Whether to pay attention to case when parsing; default is to ignore case (perform 1764 * case-folding). For example, "A" == "a" in case-insensitive but not case-sensitive mode. 1765 * 1766 * Currency symbols are never case-folded. For example, "us$1.00" will not parse in case-insensitive 1767 * mode, even though "US$1.00" parses. 1768 * 1769 * @param value true to enable case-sensitive parsing (the default); false to force 1770 * case-sensitive parsing behavior. 1771 * @stable ICU 64 1772 */ 1773 void setParseCaseSensitive(UBool value); 1774 1775 /** 1776 * Returns whether truncation of high-order integer digits should result in an error. 1777 * By default, setMaximumIntegerDigits truncates high-order digits silently. 1778 * 1779 * @return Whether an error code is set if high-order digits are truncated. 1780 * @see setFormatFailIfMoreThanMaxDigits 1781 * @stable ICU 64 1782 */ 1783 UBool isFormatFailIfMoreThanMaxDigits() const; 1784 1785 /** 1786 * Sets whether truncation of high-order integer digits should result in an error. 1787 * By default, setMaximumIntegerDigits truncates high-order digits silently. 1788 * 1789 * @param value Whether to set an error code if high-order digits are truncated. 1790 * @stable ICU 64 1791 */ 1792 void setFormatFailIfMoreThanMaxDigits(UBool value); 1793 1794 /** 1795 * Synthesizes a pattern string that represents the current state 1796 * of this Format object. 1797 * 1798 * @param result Output param which will receive the pattern. 1799 * Previous contents are deleted. 1800 * @return A reference to 'result'. 1801 * @see applyPattern 1802 * @stable ICU 2.0 1803 */ 1804 virtual UnicodeString& toPattern(UnicodeString& result) const; 1805 1806 /** 1807 * Synthesizes a localized pattern string that represents the current 1808 * state of this Format object. 1809 * 1810 * @param result Output param which will receive the localized pattern. 1811 * Previous contents are deleted. 1812 * @return A reference to 'result'. 1813 * @see applyPattern 1814 * @stable ICU 2.0 1815 */ 1816 virtual UnicodeString& toLocalizedPattern(UnicodeString& result) const; 1817 1818 /** 1819 * Apply the given pattern to this Format object. A pattern is a 1820 * short-hand specification for the various formatting properties. 1821 * These properties can also be changed individually through the 1822 * various setter methods. 1823 * <P> 1824 * There is no limit to integer digits are set 1825 * by this routine, since that is the typical end-user desire; 1826 * use setMaximumInteger if you want to set a real value. 1827 * For negative numbers, use a second pattern, separated by a semicolon 1828 * <pre> 1829 * . Example "#,#00.0#" -> 1,234.56 1830 * </pre> 1831 * This means a minimum of 2 integer digits, 1 fraction digit, and 1832 * a maximum of 2 fraction digits. 1833 * <pre> 1834 * . Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses. 1835 * </pre> 1836 * In negative patterns, the minimum and maximum counts are ignored; 1837 * these are presumed to be set in the positive pattern. 1838 * 1839 * @param pattern The pattern to be applied. 1840 * @param parseError Struct to receive information on position 1841 * of error if an error is encountered 1842 * @param status Output param set to success/failure code on 1843 * exit. If the pattern is invalid, this will be 1844 * set to a failure result. 1845 * @stable ICU 2.0 1846 */ 1847 virtual void applyPattern(const UnicodeString& pattern, UParseError& parseError, UErrorCode& status); 1848 1849 /** 1850 * Sets the pattern. 1851 * @param pattern The pattern to be applied. 1852 * @param status Output param set to success/failure code on 1853 * exit. If the pattern is invalid, this will be 1854 * set to a failure result. 1855 * @stable ICU 2.0 1856 */ 1857 virtual void applyPattern(const UnicodeString& pattern, UErrorCode& status); 1858 1859 /** 1860 * Apply the given pattern to this Format object. The pattern 1861 * is assumed to be in a localized notation. A pattern is a 1862 * short-hand specification for the various formatting properties. 1863 * These properties can also be changed individually through the 1864 * various setter methods. 1865 * <P> 1866 * There is no limit to integer digits are set 1867 * by this routine, since that is the typical end-user desire; 1868 * use setMaximumInteger if you want to set a real value. 1869 * For negative numbers, use a second pattern, separated by a semicolon 1870 * <pre> 1871 * . Example "#,#00.0#" -> 1,234.56 1872 * </pre> 1873 * This means a minimum of 2 integer digits, 1 fraction digit, and 1874 * a maximum of 2 fraction digits. 1875 * 1876 * Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses. 1877 * 1878 * In negative patterns, the minimum and maximum counts are ignored; 1879 * these are presumed to be set in the positive pattern. 1880 * 1881 * @param pattern The localized pattern to be applied. 1882 * @param parseError Struct to receive information on position 1883 * of error if an error is encountered 1884 * @param status Output param set to success/failure code on 1885 * exit. If the pattern is invalid, this will be 1886 * set to a failure result. 1887 * @stable ICU 2.0 1888 */ 1889 virtual void applyLocalizedPattern(const UnicodeString& pattern, UParseError& parseError, 1890 UErrorCode& status); 1891 1892 /** 1893 * Apply the given pattern to this Format object. 1894 * 1895 * @param pattern The localized pattern to be applied. 1896 * @param status Output param set to success/failure code on 1897 * exit. If the pattern is invalid, this will be 1898 * set to a failure result. 1899 * @stable ICU 2.0 1900 */ 1901 virtual void applyLocalizedPattern(const UnicodeString& pattern, UErrorCode& status); 1902 1903 1904 /** 1905 * Sets the maximum number of digits allowed in the integer portion of a 1906 * number. This override limits the integer digit count to 309. 1907 * 1908 * @param newValue the new value of the maximum number of digits 1909 * allowed in the integer portion of a number. 1910 * @see NumberFormat#setMaximumIntegerDigits 1911 * @stable ICU 2.0 1912 */ 1913 void setMaximumIntegerDigits(int32_t newValue) override; 1914 1915 /** 1916 * Sets the minimum number of digits allowed in the integer portion of a 1917 * number. This override limits the integer digit count to 309. 1918 * 1919 * @param newValue the new value of the minimum number of digits 1920 * allowed in the integer portion of a number. 1921 * @see NumberFormat#setMinimumIntegerDigits 1922 * @stable ICU 2.0 1923 */ 1924 void setMinimumIntegerDigits(int32_t newValue) override; 1925 1926 /** 1927 * Sets the maximum number of digits allowed in the fraction portion of a 1928 * number. This override limits the fraction digit count to 340. 1929 * 1930 * @param newValue the new value of the maximum number of digits 1931 * allowed in the fraction portion of a number. 1932 * @see NumberFormat#setMaximumFractionDigits 1933 * @stable ICU 2.0 1934 */ 1935 void setMaximumFractionDigits(int32_t newValue) override; 1936 1937 /** 1938 * Sets the minimum number of digits allowed in the fraction portion of a 1939 * number. This override limits the fraction digit count to 340. 1940 * 1941 * @param newValue the new value of the minimum number of digits 1942 * allowed in the fraction portion of a number. 1943 * @see NumberFormat#setMinimumFractionDigits 1944 * @stable ICU 2.0 1945 */ 1946 void setMinimumFractionDigits(int32_t newValue) override; 1947 1948 /** 1949 * Returns the minimum number of significant digits that will be 1950 * displayed. This value has no effect unless areSignificantDigitsUsed() 1951 * returns true. 1952 * @return the fewest significant digits that will be shown 1953 * @stable ICU 3.0 1954 */ 1955 int32_t getMinimumSignificantDigits() const; 1956 1957 /** 1958 * Returns the maximum number of significant digits that will be 1959 * displayed. This value has no effect unless areSignificantDigitsUsed() 1960 * returns true. 1961 * @return the most significant digits that will be shown 1962 * @stable ICU 3.0 1963 */ 1964 int32_t getMaximumSignificantDigits() const; 1965 1966 /** 1967 * Sets the minimum number of significant digits that will be 1968 * displayed. If <code>min</code> is less than one then it is set 1969 * to one. If the maximum significant digits count is less than 1970 * <code>min</code>, then it is set to <code>min</code>. 1971 * This function also enables the use of significant digits 1972 * by this formatter - areSignificantDigitsUsed() will return true. 1973 * @see #areSignificantDigitsUsed 1974 * @param min the fewest significant digits to be shown 1975 * @stable ICU 3.0 1976 */ 1977 void setMinimumSignificantDigits(int32_t min); 1978 1979 /** 1980 * Sets the maximum number of significant digits that will be 1981 * displayed. If <code>max</code> is less than one then it is set 1982 * to one. If the minimum significant digits count is greater 1983 * than <code>max</code>, then it is set to <code>max</code>. 1984 * This function also enables the use of significant digits 1985 * by this formatter - areSignificantDigitsUsed() will return true. 1986 * @see #areSignificantDigitsUsed 1987 * @param max the most significant digits to be shown 1988 * @stable ICU 3.0 1989 */ 1990 void setMaximumSignificantDigits(int32_t max); 1991 1992 /** 1993 * Returns true if significant digits are in use, or false if 1994 * integer and fraction digit counts are in use. 1995 * @return true if significant digits are in use 1996 * @stable ICU 3.0 1997 */ 1998 UBool areSignificantDigitsUsed() const; 1999 2000 /** 2001 * Sets whether significant digits are in use, or integer and 2002 * fraction digit counts are in use. 2003 * @param useSignificantDigits true to use significant digits, or 2004 * false to use integer and fraction digit counts 2005 * @stable ICU 3.0 2006 */ 2007 void setSignificantDigitsUsed(UBool useSignificantDigits); 2008 2009 /** 2010 * Sets the currency used to display currency 2011 * amounts. This takes effect immediately, if this format is a 2012 * currency format. If this format is not a currency format, then 2013 * the currency is used if and when this object becomes a 2014 * currency format through the application of a new pattern. 2015 * @param theCurrency a 3-letter ISO code indicating new currency 2016 * to use. It need not be null-terminated. May be the empty 2017 * string or nullptr to indicate no currency. 2018 * @param ec input-output error code 2019 * @stable ICU 3.0 2020 */ 2021 void setCurrency(const char16_t* theCurrency, UErrorCode& ec) override; 2022 2023 #ifndef U_FORCE_HIDE_DEPRECATED_API 2024 /** 2025 * Sets the currency used to display currency amounts. See 2026 * setCurrency(const char16_t*, UErrorCode&). 2027 * @deprecated ICU 3.0. Use setCurrency(const char16_t*, UErrorCode&). 2028 */ 2029 virtual void setCurrency(const char16_t* theCurrency); 2030 #endif // U_FORCE_HIDE_DEPRECATED_API 2031 2032 /** 2033 * Sets the `Currency Usage` object used to display currency. 2034 * This takes effect immediately, if this format is a 2035 * currency format. 2036 * @param newUsage new currency usage object to use. 2037 * @param ec input-output error code 2038 * @stable ICU 54 2039 */ 2040 void setCurrencyUsage(UCurrencyUsage newUsage, UErrorCode* ec); 2041 2042 /** 2043 * Returns the `Currency Usage` object used to display currency 2044 * @stable ICU 54 2045 */ 2046 UCurrencyUsage getCurrencyUsage() const; 2047 2048 #ifndef U_HIDE_INTERNAL_API 2049 2050 /** 2051 * Format a number and save it into the given DecimalQuantity. 2052 * Internal, not intended for public use. 2053 * @internal 2054 */ 2055 void formatToDecimalQuantity(double number, number::impl::DecimalQuantity& output, 2056 UErrorCode& status) const; 2057 2058 /** 2059 * Get a DecimalQuantity corresponding to a formattable as it would be 2060 * formatted by this DecimalFormat. 2061 * Internal, not intended for public use. 2062 * @internal 2063 */ 2064 void formatToDecimalQuantity(const Formattable& number, number::impl::DecimalQuantity& output, 2065 UErrorCode& status) const; 2066 2067 #endif /* U_HIDE_INTERNAL_API */ 2068 2069 /** 2070 * Converts this DecimalFormat to a (Localized)NumberFormatter. Starting 2071 * in ICU 60, NumberFormatter is the recommended way to format numbers. 2072 * You can use the returned LocalizedNumberFormatter to format numbers and 2073 * get a FormattedNumber, which contains a string as well as additional 2074 * annotations about the formatted value. 2075 * 2076 * If a memory allocation failure occurs, the return value of this method 2077 * might be null. If you are concerned about correct recovery from 2078 * out-of-memory situations, use this pattern: 2079 * 2080 * <pre> 2081 * FormattedNumber result; 2082 * if (auto* ptr = df->toNumberFormatter(status)) { 2083 * result = ptr->formatDouble(123, status); 2084 * } 2085 * </pre> 2086 * 2087 * If you are not concerned about out-of-memory situations, or if your 2088 * environment throws exceptions when memory allocation failure occurs, 2089 * you can chain the methods, like this: 2090 * 2091 * <pre> 2092 * FormattedNumber result = df 2093 * ->toNumberFormatter(status) 2094 * ->formatDouble(123, status); 2095 * </pre> 2096 * 2097 * NOTE: The returned LocalizedNumberFormatter is owned by this DecimalFormat. 2098 * If a non-const method is called on the DecimalFormat, or if the DecimalFormat 2099 * is deleted, the object becomes invalid. If you plan to keep the return value 2100 * beyond the lifetime of the DecimalFormat, copy it to a local variable: 2101 * 2102 * <pre> 2103 * LocalizedNumberFormatter lnf; 2104 * if (auto* ptr = df->toNumberFormatter(status)) { 2105 * lnf = *ptr; 2106 * } 2107 * </pre> 2108 * 2109 * @param status Set on failure, like U_MEMORY_ALLOCATION_ERROR. 2110 * @return A pointer to an internal object, or nullptr on failure. 2111 * Do not delete the return value! 2112 * @stable ICU 64 2113 */ 2114 const number::LocalizedNumberFormatter* toNumberFormatter(UErrorCode& status) const; 2115 2116 /** 2117 * Return the class ID for this class. This is useful only for 2118 * comparing to a return value from getDynamicClassID(). For example: 2119 * <pre> 2120 * . Base* polymorphic_pointer = createPolymorphicObject(); 2121 * . if (polymorphic_pointer->getDynamicClassID() == 2122 * . Derived::getStaticClassID()) ... 2123 * </pre> 2124 * @return The class ID for all objects of this class. 2125 * @stable ICU 2.0 2126 */ 2127 static UClassID U_EXPORT2 getStaticClassID(void); 2128 2129 /** 2130 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. 2131 * This method is to implement a simple version of RTTI, since not all 2132 * C++ compilers support genuine RTTI. Polymorphic operator==() and 2133 * clone() methods call this method. 2134 * 2135 * @return The class ID for this object. All objects of a 2136 * given class have the same class ID. Objects of 2137 * other classes have different class IDs. 2138 * @stable ICU 2.0 2139 */ 2140 UClassID getDynamicClassID(void) const override; 2141 2142 private: 2143 2144 /** Rebuilds the formatter object from the property bag. */ 2145 void touch(UErrorCode& status); 2146 2147 /** Rebuilds the formatter object, ignoring any error code. */ 2148 void touchNoError(); 2149 2150 /** 2151 * Updates the property bag with settings from the given pattern. 2152 * 2153 * @param pattern The pattern string to parse. 2154 * @param ignoreRounding Whether to leave out rounding information (minFrac, maxFrac, and rounding 2155 * increment) when parsing the pattern. This may be desirable if a custom rounding mode, such 2156 * as CurrencyUsage, is to be used instead. One of {@link 2157 * PatternStringParser#IGNORE_ROUNDING_ALWAYS}, {@link PatternStringParser#IGNORE_ROUNDING_IF_CURRENCY}, 2158 * or {@link PatternStringParser#IGNORE_ROUNDING_NEVER}. 2159 * @see PatternAndPropertyUtils#parseToExistingProperties 2160 */ 2161 void setPropertiesFromPattern(const UnicodeString& pattern, int32_t ignoreRounding, 2162 UErrorCode& status); 2163 2164 const numparse::impl::NumberParserImpl* getParser(UErrorCode& status) const; 2165 2166 const numparse::impl::NumberParserImpl* getCurrencyParser(UErrorCode& status) const; 2167 2168 static void fieldPositionHelper( 2169 const number::impl::UFormattedNumberData& formatted, 2170 FieldPosition& fieldPosition, 2171 int32_t offset, 2172 UErrorCode& status); 2173 2174 static void fieldPositionIteratorHelper( 2175 const number::impl::UFormattedNumberData& formatted, 2176 FieldPositionIterator* fpi, 2177 int32_t offset, 2178 UErrorCode& status); 2179 2180 void setupFastFormat(); 2181 2182 bool fastFormatDouble(double input, UnicodeString& output) const; 2183 2184 bool fastFormatInt64(int64_t input, UnicodeString& output) const; 2185 2186 void doFastFormatInt32(int32_t input, bool isNegative, UnicodeString& output) const; 2187 2188 //=====================================================================================// 2189 // INSTANCE FIELDS // 2190 //=====================================================================================// 2191 2192 2193 // One instance field for the implementation, keep all fields inside of an implementation 2194 // class defined in number_mapper.h 2195 number::impl::DecimalFormatFields* fields = nullptr; 2196 2197 // Allow child class CompactDecimalFormat to access fProperties: 2198 friend class CompactDecimalFormat; 2199 2200 // Allow MeasureFormat to use fieldPositionHelper: 2201 friend class MeasureFormat; 2202 2203 }; 2204 2205 U_NAMESPACE_END 2206 2207 #endif /* #if !UCONFIG_NO_FORMATTING */ 2208 2209 #endif /* U_SHOW_CPLUSPLUS_API */ 2210 2211 #endif // _DECIMFMT 2212 //eof
Contact us
|
About us
|
Term of use
|
Copyright © 2000-2025 MyWebUniversity.com ™
