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