icuSources/i18n/unicode/decimfmt.h

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