2 *******************************************************************************
\r
3 * Copyright (C) 1996-2006, International Business Machines Corporation and *
\r
4 * others. All Rights Reserved. *
\r
5 *******************************************************************************
\r
8 package com.ibm.icu.text;
\r
11 * <code>DecimalFormat</code> is a concrete subclass of
\r
12 * {@link NumberFormat} that formats decimal numbers.
\r
14 * <p>To obtain a {@link NumberFormat} for a specific locale (including the
\r
15 * default locale) call one of <code>NumberFormat</code>'s factory methods such
\r
16 * as {@link NumberFormat#getInstance}. Do not call the <code>DecimalFormat</code>
\r
17 * constructors directly, unless you know what you are doing, since the
\r
18 * {@link NumberFormat} factory methods may return subclasses other than
\r
19 * <code>DecimalFormat</code>. If you need to customize the format object, do
\r
20 * something like this:
\r
23 * NumberFormat f = NumberFormat.getInstance(loc);
\r
24 * if (f instanceof DecimalFormat) {
\r
25 * ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true);
\r
26 * }</pre></blockquote>
\r
28 * <p><strong>Example Usage</strong>
\r
31 * <strong>// Print out a number using the localized number, currency,
\r
32 * // and percent format for each locale</strong>
\r
33 * Locale[] locales = NumberFormat.getAvailableLocales();
\r
34 * double myNumber = -1234.56;
\r
35 * NumberFormat format;
\r
36 * for (int j=0; j<3; ++j) {
\r
37 * System.out.println("FORMAT");
\r
38 * for (int i = 0; i < locales.length; ++i) {
\r
39 * if (locales[i].getCountry().length() == 0) {
\r
40 * // Skip language-only locales
\r
43 * System.out.print(locales[i].getDisplayName());
\r
46 * format = NumberFormat.getInstance(locales[i]); break;
\r
48 * format = NumberFormat.getCurrencyInstance(locales[i]); break;
\r
50 * format = NumberFormat.getPercentInstance(locales[i]); break;
\r
53 * // Assume format is a DecimalFormat
\r
54 * System.out.print(": " + ((DecimalFormat) format).toPattern()
\r
55 * + " -> " + form.format(myNumber));
\r
56 * } catch (Exception e) {}
\r
58 * System.out.println(" -> " + format.parse(form.format(myNumber)));
\r
59 * } catch (ParseException e) {}
\r
61 * }</pre></blockquote>
\r
65 * <p>A <code>DecimalFormat</code> consists of a <em>pattern</em> and a set of
\r
66 * <em>symbols</em>. The pattern may be set directly using
\r
67 * {@link #applyPattern}, or indirectly using other API methods which
\r
68 * manipulate aspects of the pattern, such as the minimum number of integer
\r
69 * digits. The symbols are stored in a {@link DecimalFormatSymbols}
\r
70 * object. When using the {@link NumberFormat} factory methods, the
\r
71 * pattern and symbols are read from ICU's locale data.
\r
73 * <h4>Special Pattern Characters</h4>
\r
75 * <p>Many characters in a pattern are taken literally; they are matched during
\r
76 * parsing and output unchanged during formatting. Special characters, on the
\r
77 * other hand, stand for other characters, strings, or classes of characters.
\r
78 * For example, the '#' character is replaced by a localized digit. Often the
\r
79 * replacement character is the same as the pattern character; in the U.S. locale,
\r
80 * the ',' grouping character is replaced by ','. However, the replacement is
\r
81 * still happening, and if the symbols are modified, the grouping character
\r
82 * changes. Some special characters affect the behavior of the formatter by
\r
83 * their presence; for example, if the percent character is seen, then the
\r
84 * value is multiplied by 100 before being displayed.
\r
86 * <p>To insert a special character in a pattern as a literal, that is, without
\r
87 * any special meaning, the character must be quoted. There are some exceptions to
\r
88 * this which are noted below.
\r
90 * <p>The characters listed here are used in non-localized patterns. Localized
\r
91 * patterns use the corresponding characters taken from this formatter's
\r
92 * {@link DecimalFormatSymbols} object instead, and these characters lose
\r
93 * their special status. Two exceptions are the currency sign and quote, which
\r
94 * are not localized.
\r
97 * <table border=0 cellspacing=3 cellpadding=0 summary="Chart showing symbol,
\r
98 * location, localized, and meaning.">
\r
99 * <tr bgcolor="#ccccff">
\r
100 * <th align=left>Symbol
\r
101 * <th align=left>Location
\r
102 * <th align=left>Localized?
\r
103 * <th align=left>Meaning
\r
105 * <td><code>0</code>
\r
109 * <tr valign=top bgcolor="#eeeeff">
\r
110 * <td><code>1-9</code>
\r
113 * <td><strong><font face=helvetica color=red>NEW</font></strong>
\r
114 * '1' through '9' indicate rounding.
\r
116 * <td><code>@</code>
\r
119 * <td><strong><font face=helvetica color=red>NEW</font></strong>
\r
120 * Significant digit
\r
121 * <tr valign=top bgcolor="#eeeeff">
\r
122 * <td><code>#</code>
\r
125 * <td>Digit, zero shows as absent
\r
127 * <td><code>.</code>
\r
130 * <td>Decimal separator or monetary decimal separator
\r
131 * <tr valign=top bgcolor="#eeeeff">
\r
132 * <td><code>-</code>
\r
137 * <td><code>,</code>
\r
140 * <td>Grouping separator
\r
141 * <tr valign=top bgcolor="#eeeeff">
\r
142 * <td><code>E</code>
\r
145 * <td>Separates mantissa and exponent in scientific notation.
\r
146 * <em>Need not be quoted in prefix or suffix.</em>
\r
148 * <td><code>+</code>
\r
151 * <td><strong><font face=helvetica color=red>NEW</font></strong>
\r
152 * Prefix positive exponents with localized plus sign.
\r
153 * <em>Need not be quoted in prefix or suffix.</em>
\r
154 * <tr valign=top bgcolor="#eeeeff">
\r
155 * <td><code>;</code>
\r
156 * <td>Subpattern boundary
\r
158 * <td>Separates positive and negative subpatterns
\r
160 * <td><code>%</code>
\r
161 * <td>Prefix or suffix
\r
163 * <td>Multiply by 100 and show as percentage
\r
164 * <tr valign=top bgcolor="#eeeeff">
\r
165 * <td><code>\u2030</code>
\r
166 * <td>Prefix or suffix
\r
168 * <td>Multiply by 1000 and show as per mille
\r
170 * <td><code>¤</code> (<code>\u00A4</code>)
\r
171 * <td>Prefix or suffix
\r
173 * <td>Currency sign, replaced by currency symbol. If
\r
174 * doubled, replaced by international currency symbol.
\r
175 * If present in a pattern, the monetary decimal separator
\r
176 * is used instead of the decimal separator.
\r
177 * <tr valign=top bgcolor="#eeeeff">
\r
178 * <td><code>'</code>
\r
179 * <td>Prefix or suffix
\r
181 * <td>Used to quote special characters in a prefix or suffix,
\r
182 * for example, <code>"'#'#"</code> formats 123 to
\r
183 * <code>"#123"</code>. To create a single quote
\r
184 * itself, use two in a row: <code>"# o''clock"</code>.
\r
186 * <td><code>*</code>
\r
187 * <td>Prefix or suffix boundary
\r
189 * <td><strong><font face=helvetica color=red>NEW</font></strong>
\r
190 * Pad escape, precedes pad character
\r
194 * <p>A <code>DecimalFormat</code> pattern contains a postive and negative
\r
195 * subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a
\r
196 * prefix, a numeric part, and a suffix. If there is no explicit negative
\r
197 * subpattern, the negative subpattern is the localized minus sign prefixed to the
\r
198 * positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there
\r
199 * is an explicit negative subpattern, it serves only to specify the negative
\r
200 * prefix and suffix; the number of digits, minimal digits, and other
\r
201 * characteristics are ignored in the negative subpattern. That means that
\r
202 * "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)".
\r
204 * <p>The prefixes, suffixes, and various symbols used for infinity, digits,
\r
205 * thousands separators, decimal separators, etc. may be set to arbitrary
\r
206 * values, and they will appear properly during formatting. However, care must
\r
207 * be taken that the symbols and strings do not conflict, or parsing will be
\r
208 * unreliable. For example, either the positive and negative prefixes or the
\r
209 * suffixes must be distinct for {@link #parse} to be able
\r
210 * to distinguish positive from negative values. Another example is that the
\r
211 * decimal separator and thousands separator should be distinct characters, or
\r
212 * parsing will be impossible.
\r
214 * <p>The <em>grouping separator</em> is a character that separates clusters of
\r
215 * integer digits to make large numbers more legible. It commonly used for
\r
216 * thousands, but in some locales it separates ten-thousands. The <em>grouping
\r
217 * size</em> is the number of digits between the grouping separators, such as 3
\r
218 * for "100,000,000" or 4 for "1 0000 0000". There are actually two different
\r
219 * grouping sizes: One used for the least significant integer digits, the
\r
220 * <em>primary grouping size</em>, and one used for all others, the
\r
221 * <em>secondary grouping size</em>. In most locales these are the same, but
\r
222 * sometimes they are different. For example, if the primary grouping interval
\r
223 * is 3, and the secondary is 2, then this corresponds to the pattern
\r
224 * "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a
\r
225 * pattern contains multiple grouping separators, the interval between the last
\r
226 * one and the end of the integer defines the primary grouping size, and the
\r
227 * interval between the last two defines the secondary grouping size. All others
\r
228 * are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####".
\r
230 * <p>Illegal patterns, such as "#.#.#" or "#.###,###", will cause
\r
231 * <code>DecimalFormat</code> to throw an {@link IllegalArgumentException}
\r
232 * with a message that describes the problem.
\r
234 * <h4>Pattern BNF</h4>
\r
237 * pattern := subpattern (';' subpattern)?
\r
238 * subpattern := prefix? number exponent? suffix?
\r
239 * number := (integer ('.' fraction)?) | sigDigits
\r
240 * prefix := '\u0000'..'\uFFFD' - specialCharacters
\r
241 * suffix := '\u0000'..'\uFFFD' - specialCharacters
\r
242 * integer := '#'* '0'* '0'
\r
243 * fraction := '0'* '#'*
\r
244 * sigDigits := '#'* '@' '@'* '#'*
\r
245 * exponent := 'E' '+'? '0'* '0'
\r
246 * padSpec := '*' padChar
\r
247 * padChar := '\u0000'..'\uFFFD' - quote
\r
250 * X* 0 or more instances of X
\r
251 * X? 0 or 1 instances of X
\r
252 * X|Y either X or Y
\r
253 * C..D any character from C up to D, inclusive
\r
254 * S-T characters in S, except those in T
\r
256 * The first subpattern is for positive numbers. The second (optional)
\r
257 * subpattern is for negative numbers.
\r
259 * <p>Not indicated in the BNF syntax above:
\r
261 * <ul><li>The grouping separator ',' can occur inside the integer and
\r
262 * sigDigits elements, between any two pattern characters of that
\r
263 * element, as long as the integer or sigDigits element is not
\r
264 * followed by the exponent element.
\r
266 * <li><font color=red face=helvetica><strong>NEW</strong></font>
\r
267 * Two grouping intervals are recognized: That between the
\r
268 * decimal point and the first grouping symbol, and that
\r
269 * between the first and second grouping symbols. These
\r
270 * intervals are identical in most locales, but in some
\r
271 * locales they differ. For example, the pattern
\r
272 * "#,##,###" formats the number 123456789 as
\r
273 * "12,34,56,789".</li>
\r
276 * <strong><font face=helvetica color=red>NEW</font></strong>
\r
277 * The pad specifier <code>padSpec</code> may appear before the prefix,
\r
278 * after the prefix, before the suffix, after the suffix, or not at all.
\r
281 * <strong><font face=helvetica color=red>NEW</font></strong>
\r
282 * In place of '0', the digits '1' through '9' may be used to
\r
283 * indicate a rounding increment.
\r
288 * <p><code>DecimalFormat</code> parses all Unicode characters that represent
\r
289 * decimal digits, as defined by {@link UCharacter#digit}. In addition,
\r
290 * <code>DecimalFormat</code> also recognizes as digits the ten consecutive
\r
291 * characters starting with the localized zero digit defined in the
\r
292 * {@link DecimalFormatSymbols} object. During formatting, the
\r
293 * {@link DecimalFormatSymbols}-based digits are output.
\r
295 * <p>During parsing, grouping separators are ignored.
\r
297 * <p>If {@link #parse(String, ParsePosition)} fails to parse
\r
298 * a string, it returns <code>null</code> and leaves the parse position
\r
299 * unchanged. The convenience method {@link #parse(String)}
\r
300 * indicates parse failure by throwing a {@link java.text.ParseException}.
\r
302 * <h4>Formatting</h4>
\r
304 * <p>Formatting is guided by several parameters, all of which can be
\r
305 * specified either using a pattern or using the API. The following
\r
306 * description applies to formats that do not use <a href="#sci">scientific
\r
307 * notation</a> or <a href="#sigdig">significant digits</a>.
\r
309 * <ul><li>If the number of actual integer digits exceeds the
\r
310 * <em>maximum integer digits</em>, then only the least significant
\r
311 * digits are shown. For example, 1997 is formatted as "97" if the
\r
312 * maximum integer digits is set to 2.
\r
314 * <li>If the number of actual integer digits is less than the
\r
315 * <em>minimum integer digits</em>, then leading zeros are added. For
\r
316 * example, 1997 is formatted as "01997" if the minimum integer digits
\r
319 * <li>If the number of actual fraction digits exceeds the <em>maximum
\r
320 * fraction digits</em>, then half-even rounding it performed to the
\r
321 * maximum fraction digits. For example, 0.125 is formatted as "0.12"
\r
322 * if the maximum fraction digits is 2. This behavior can be changed
\r
323 * by specifying a rounding increment and a rounding mode.
\r
325 * <li>If the number of actual fraction digits is less than the
\r
326 * <em>minimum fraction digits</em>, then trailing zeros are added.
\r
327 * For example, 0.125 is formatted as "0.1250" if the mimimum fraction
\r
328 * digits is set to 4.
\r
330 * <li>Trailing fractional zeros are not displayed if they occur
\r
331 * <em>j</em> positions after the decimal, where <em>j</em> is less
\r
332 * than the maximum fraction digits. For example, 0.10004 is
\r
333 * formatted as "0.1" if the maximum fraction digits is four or less.
\r
336 * <p><strong>Special Values</strong>
\r
338 * <p><code>NaN</code> is represented as a single character, typically
\r
339 * <code>\uFFFD</code>. This character is determined by the
\r
340 * {@link DecimalFormatSymbols} object. This is the only value for which
\r
341 * the prefixes and suffixes are not used.
\r
343 * <p>Infinity is represented as a single character, typically
\r
344 * <code>\u221E</code>, with the positive or negative prefixes and suffixes
\r
345 * applied. The infinity character is determined by the
\r
346 * {@link DecimalFormatSymbols} object.
\r
348 * <a name="sci"><h4>Scientific Notation</h4></a>
\r
350 * <p>Numbers in scientific notation are expressed as the product of a mantissa
\r
351 * and a power of ten, for example, 1234 can be expressed as 1.234 x 10<sup>3</sup>. The
\r
352 * mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0),
\r
353 * but it need not be. <code>DecimalFormat</code> supports arbitrary mantissas.
\r
354 * <code>DecimalFormat</code> can be instructed to use scientific
\r
355 * notation through the API or through the pattern. In a pattern, the exponent
\r
356 * character immediately followed by one or more digit characters indicates
\r
357 * scientific notation. Example: "0.###E0" formats the number 1234 as
\r
361 * <li>The number of digit characters after the exponent character gives the
\r
362 * minimum exponent digit count. There is no maximum. Negative exponents are
\r
363 * formatted using the localized minus sign, <em>not</em> the prefix and suffix
\r
364 * from the pattern. This allows patterns such as "0.###E0 m/s". To prefix
\r
365 * positive exponents with a localized plus sign, specify '+' between the
\r
366 * exponent and the digits: "0.###E+0" will produce formats "1E+1", "1E+0",
\r
367 * "1E-1", etc. (In localized patterns, use the localized plus sign rather than
\r
370 * <li>The minimum number of integer digits is achieved by adjusting the
\r
371 * exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This
\r
372 * only happens if there is no maximum number of integer digits. If there is a
\r
373 * maximum, then the minimum number of integer digits is fixed at one.
\r
375 * <li>The maximum number of integer digits, if present, specifies the exponent
\r
376 * grouping. The most common use of this is to generate <em>engineering
\r
377 * notation</em>, in which the exponent is a multiple of three, e.g.,
\r
378 * "##0.###E0". The number 12345 is formatted using "##0.####E0" as "12.345E3".
\r
380 * <li>When using scientific notation, the formatter controls the
\r
381 * digit counts using significant digits logic. The maximum number of
\r
382 * significant digits limits the total number of integer and fraction
\r
383 * digits that will be shown in the mantissa; it does not affect
\r
384 * parsing. For example, 12345 formatted with "##0.##E0" is "12.3E3".
\r
385 * See the section on significant digits for more details.
\r
387 * <li>The number of significant digits shown is determined as
\r
388 * follows: If areSignificantDigitsUsed() returns false, then the
\r
389 * minimum number of significant digits shown is one, and the maximum
\r
390 * number of significant digits shown is the sum of the <em>minimum
\r
391 * integer</em> and <em>maximum fraction</em> digits, and is
\r
392 * unaffected by the maximum integer digits. If this sum is zero,
\r
393 * then all significant digits are shown. If
\r
394 * areSignificantDigitsUsed() returns true, then the significant digit
\r
395 * counts are specified by getMinimumSignificantDigits() and
\r
396 * getMaximumSignificantDigits(). In this case, the number of
\r
397 * integer digits is fixed at one, and there is no exponent grouping.
\r
399 * <li>Exponential patterns may not contain grouping separators.
\r
402 * <a name="sigdig"><h4>
\r
403 * <strong><font face=helvetica color=red>NEW</font></strong>
\r
404 * Significant Digits</h4></a>
\r
406 * <code>DecimalFormat</code> has two ways of controlling how many
\r
407 * digits are shows: (a) significant digits counts, or (b) integer and
\r
408 * fraction digit counts. Integer and fraction digit counts are
\r
409 * described above. When a formatter is using significant digits
\r
410 * counts, the number of integer and fraction digits is not specified
\r
411 * directly, and the formatter settings for these counts are ignored.
\r
412 * Instead, the formatter uses however many integer and fraction
\r
413 * digits are required to display the specified number of significant
\r
414 * digits. Examples:
\r
417 * <table border=0 cellspacing=3 cellpadding=0>
\r
418 * <tr bgcolor="#ccccff">
\r
419 * <th align=left>Pattern
\r
420 * <th align=left>Minimum significant digits
\r
421 * <th align=left>Maximum significant digits
\r
422 * <th align=left>Number
\r
423 * <th align=left>Output of format()
\r
425 * <td><code>@@@</code>
\r
429 * <td><code>12300</code>
\r
430 * <tr valign=top bgcolor="#eeeeff">
\r
431 * <td><code>@@@</code>
\r
435 * <td><code>0.123</code>
\r
437 * <td><code>@@##</code>
\r
441 * <td><code>3.142</code>
\r
442 * <tr valign=top bgcolor="#eeeeff">
\r
443 * <td><code>@@##</code>
\r
447 * <td><code>1.23</code>
\r
452 * <li>Significant digit counts may be expressed using patterns that
\r
453 * specify a minimum and maximum number of significant digits. These
\r
454 * are indicated by the <code>'@'</code> and <code>'#'</code>
\r
455 * characters. The minimum number of significant digits is the number
\r
456 * of <code>'@'</code> characters. The maximum number of significant
\r
457 * digits is the number of <code>'@'</code> characters plus the number
\r
458 * of <code>'#'</code> characters following on the right. For
\r
459 * example, the pattern <code>"@@@"</code> indicates exactly 3
\r
460 * significant digits. The pattern <code>"@##"</code> indicates from
\r
461 * 1 to 3 significant digits. Trailing zero digits to the right of
\r
462 * the decimal separator are suppressed after the minimum number of
\r
463 * significant digits have been shown. For example, the pattern
\r
464 * <code>"@##"</code> formats the number 0.1203 as
\r
465 * <code>"0.12"</code>.
\r
467 * <li>If a pattern uses significant digits, it may not contain a
\r
468 * decimal separator, nor the <code>'0'</code> pattern character.
\r
469 * Patterns such as <code>"@00"</code> or <code>"@.###"</code> are
\r
472 * <li>Any number of <code>'#'</code> characters may be prepended to
\r
473 * the left of the leftmost <code>'@'</code> character. These have no
\r
474 * effect on the minimum and maximum significant digits counts, but
\r
475 * may be used to position grouping separators. For example,
\r
476 * <code>"#,#@#"</code> indicates a minimum of one significant digits,
\r
477 * a maximum of two significant digits, and a grouping size of three.
\r
479 * <li>In order to enable significant digits formatting, use a pattern
\r
480 * containing the <code>'@'</code> pattern character. Alternatively,
\r
481 * call {@link #setSignificantDigitsUsed setSignificantDigitsUsed(true)}.
\r
483 * <li>In order to disable significant digits formatting, use a
\r
484 * pattern that does not contain the <code>'@'</code> pattern
\r
485 * character. Alternatively, call {@link #setSignificantDigitsUsed
\r
486 * setSignificantDigitsUsed(false)}.
\r
488 * <li>The number of significant digits has no effect on parsing.
\r
490 * <li>Significant digits may be used together with exponential notation. Such
\r
491 * patterns are equivalent to a normal exponential pattern with a minimum and
\r
492 * maximum integer digit count of one, a minimum fraction digit count of
\r
493 * <code>getMinimumSignificantDigits() - 1</code>, and a maximum fraction digit
\r
494 * count of <code>getMaximumSignificantDigits() - 1</code>. For example, the
\r
495 * pattern <code>"@@###E0"</code> is equivalent to <code>"0.0###E0"</code>.
\r
497 * <li>If signficant digits are in use, then the integer and fraction
\r
498 * digit counts, as set via the API, are ignored. If significant
\r
499 * digits are not in use, then the signficant digit counts, as set via
\r
500 * the API, are ignored.
\r
505 * <strong><font face=helvetica color=red>NEW</font></strong>
\r
508 * <p><code>DecimalFormat</code> supports padding the result of
\r
509 * {@link #format} to a specific width. Padding may be specified either
\r
510 * through the API or through the pattern syntax. In a pattern the pad escape
\r
511 * character, followed by a single pad character, causes padding to be parsed
\r
512 * and formatted. The pad escape character is '*' in unlocalized patterns, and
\r
513 * can be localized using {@link DecimalFormatSymbols#setPadEscape}. For
\r
514 * example, <code>"$*x#,##0.00"</code> formats 123 to <code>"$xx123.00"</code>,
\r
515 * and 1234 to <code>"$1,234.00"</code>.
\r
518 * <li>When padding is in effect, the width of the positive subpattern,
\r
519 * including prefix and suffix, determines the format width. For example, in
\r
520 * the pattern <code>"* #0 o''clock"</code>, the format width is 10.
\r
522 * <li>The width is counted in 16-bit code units (Java <code>char</code>s).
\r
524 * <li>Some parameters which usually do not matter have meaning when padding is
\r
525 * used, because the pattern width is significant with padding. In the pattern
\r
526 * "* ##,##,#,##0.##", the format width is 14. The initial characters "##,##,"
\r
527 * do not affect the grouping size or maximum integer digits, but they do affect
\r
528 * the format width.
\r
530 * <li>Padding may be inserted at one of four locations: before the prefix,
\r
531 * after the prefix, before the suffix, or after the suffix. If padding is
\r
532 * specified in any other location, {@link #applyPattern} throws an {@link
\r
533 * IllegalArgumentException}. If there is no prefix, before the
\r
534 * prefix and after the prefix are equivalent, likewise for the suffix.
\r
536 * <li>When specified in a pattern, the 16-bit <code>char</code> immediately
\r
537 * following the pad escape is the pad character. This may be any character,
\r
538 * including a special pattern character. That is, the pad escape
\r
539 * <em>escapes</em> the following character. If there is no character after
\r
540 * the pad escape, then the pattern is illegal.
\r
545 * <strong><font face=helvetica color=red>NEW</font></strong>
\r
546 * <strong>Rounding</strong>
\r
548 * <p><code>DecimalFormat</code> supports rounding to a specific increment. For
\r
549 * example, 1230 rounded to the nearest 50 is 1250. 1.234 rounded to the
\r
550 * nearest 0.65 is 1.3. The rounding increment may be specified through the API
\r
551 * or in a pattern. To specify a rounding increment in a pattern, include the
\r
552 * increment in the pattern itself. "#,#50" specifies a rounding increment of
\r
553 * 50. "#,##0.05" specifies a rounding increment of 0.05.
\r
556 * <li>Rounding only affects the string produced by formatting. It does
\r
557 * not affect parsing or change any numerical values.
\r
559 * <li>A <em>rounding mode</em> determines how values are rounded; see the
\r
560 * {@link com.ibm.icu.math.BigDecimal} documentation for a description of the
\r
561 * modes. Rounding increments specified in patterns use the default mode,
\r
562 * {@link com.ibm.icu.math.BigDecimal#ROUND_HALF_EVEN}.
\r
564 * <li>Some locales use rounding in their currency formats to reflect the
\r
565 * smallest currency denomination.
\r
567 * <li>In a pattern, digits '1' through '9' specify rounding, but otherwise
\r
568 * behave identically to digit '0'.
\r
571 * <h4>Synchronization</h4>
\r
573 * <p><code>DecimalFormat</code> objects are not synchronized. Multiple
\r
574 * threads should not access one formatter concurrently.
\r
576 * @see java.text.Format
\r
577 * @see NumberFormat
\r
578 * @author Mark Davis
\r
582 public class DecimalFormat extends NumberFormat {
\r
584 private static final long serialVersionUID = 1L;
\r
587 * @param delegate the NumberFormat to which to delegate
\r
589 public DecimalFormat(java.text.DecimalFormat delegate) {
\r
594 * Create a DecimalFormat using the default pattern and symbols
\r
595 * for the default locale. This is a convenient way to obtain a
\r
596 * DecimalFormat when internationalization is not the main concern.
\r
598 * To obtain standard formats for a given locale, use the factory methods
\r
599 * on NumberFormat such as getNumberInstance. These factories will
\r
600 * return the most appropriate sub-class of NumberFormat for a given
\r
602 * @see NumberFormat#getInstance
\r
603 * @see NumberFormat#getNumberInstance
\r
604 * @see NumberFormat#getCurrencyInstance
\r
605 * @see NumberFormat#getPercentInstance
\r
608 public DecimalFormat() {
\r
609 this(new java.text.DecimalFormat());
\r
613 * Create a DecimalFormat from the given pattern and the symbols
\r
614 * for the default locale. This is a convenient way to obtain a
\r
615 * DecimalFormat when internationalization is not the main concern.
\r
617 * To obtain standard formats for a given locale, use the factory methods
\r
618 * on NumberFormat such as getNumberInstance. These factories will
\r
619 * return the most appropriate sub-class of NumberFormat for a given
\r
621 * @param pattern A non-localized pattern string.
\r
622 * @exception IllegalArgumentException if the given pattern is invalid.
\r
623 * @see NumberFormat#getInstance
\r
624 * @see NumberFormat#getNumberInstance
\r
625 * @see NumberFormat#getCurrencyInstance
\r
626 * @see NumberFormat#getPercentInstance
\r
629 public DecimalFormat(String pattern) {
\r
630 this(new java.text.DecimalFormat(pattern));
\r
635 * Create a DecimalFormat from the given pattern and symbols.
\r
636 * Use this constructor when you need to completely customize the
\r
637 * behavior of the format.
\r
639 * To obtain standard formats for a given
\r
640 * locale, use the factory methods on NumberFormat such as
\r
641 * getInstance or getCurrencyInstance. If you need only minor adjustments
\r
642 * to a standard format, you can modify the format returned by
\r
643 * a NumberFormat factory method.
\r
644 * @param pattern a non-localized pattern string
\r
645 * @param symbols the set of symbols to be used
\r
646 * @exception IllegalArgumentException if the given pattern is invalid
\r
647 * @see NumberFormat#getInstance
\r
648 * @see NumberFormat#getNumberInstance
\r
649 * @see NumberFormat#getCurrencyInstance
\r
650 * @see NumberFormat#getPercentInstance
\r
651 * @see DecimalFormatSymbols
\r
654 public DecimalFormat(String pattern, DecimalFormatSymbols symbols) {
\r
655 this(new java.text.DecimalFormat(pattern, symbols.dfs));
\r
659 * Returns a copy of the decimal format symbols used by this format.
\r
660 * @return desired DecimalFormatSymbols
\r
661 * @see DecimalFormatSymbols
\r
664 public DecimalFormatSymbols getDecimalFormatSymbols() {
\r
665 return new DecimalFormatSymbols(((java.text.DecimalFormat)numberFormat).getDecimalFormatSymbols());
\r
669 * Sets the decimal format symbols used by this format. The
\r
670 * format uses a copy of the provided symbols.
\r
671 * @param newSymbols desired DecimalFormatSymbols
\r
672 * @see DecimalFormatSymbols
\r
675 public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols) {
\r
676 ((java.text.DecimalFormat)numberFormat).setDecimalFormatSymbols(newSymbols.dfs);
\r
681 * Get the positive prefix.
\r
682 * <P>Examples: +123, $123, sFr123
\r
685 public String getPositivePrefix() {
\r
686 return ((java.text.DecimalFormat)numberFormat).getPositivePrefix();
\r
690 * Set the positive prefix.
\r
691 * <P>Examples: +123, $123, sFr123
\r
694 public void setPositivePrefix(String newValue) {
\r
695 ((java.text.DecimalFormat)numberFormat).setPositivePrefix(newValue);
\r
699 * Get the negative prefix.
\r
700 * <P>Examples: -123, ($123) (with negative suffix), sFr-123
\r
703 public String getNegativePrefix () {
\r
704 return ((java.text.DecimalFormat)numberFormat).getNegativePrefix();
\r
708 * Set the negative prefix.
\r
709 * <P>Examples: -123, ($123) (with negative suffix), sFr-123
\r
712 public void setNegativePrefix (String newValue) {
\r
713 ((java.text.DecimalFormat)numberFormat).setNegativePrefix(newValue);
\r
717 * Get the positive suffix.
\r
721 public String getPositiveSuffix () {
\r
722 return ((java.text.DecimalFormat)numberFormat).getPositiveSuffix();
\r
726 * Set the positive suffix.
\r
730 public void setPositiveSuffix (String newValue) {
\r
731 ((java.text.DecimalFormat)numberFormat).setPositiveSuffix(newValue);
\r
735 * Get the negative suffix.
\r
736 * <P>Examples: -123%, ($123) (with positive suffixes)
\r
739 public String getNegativeSuffix () {
\r
740 return ((java.text.DecimalFormat)numberFormat).getNegativeSuffix();
\r
744 * Set the positive suffix.
\r
745 * <P>Examples: 123%
\r
748 public void setNegativeSuffix (String newValue) {
\r
749 ((java.text.DecimalFormat)numberFormat).setNegativeSuffix(newValue);
\r
753 * Get the multiplier for use in percent, permill, etc.
\r
754 * For a percentage, set the suffixes to have "%" and the multiplier to be 100.
\r
755 * (For Arabic, use arabic percent symbol).
\r
756 * For a permill, set the suffixes to have "\u2031" and the multiplier to be 1000.
\r
757 * <P>Examples: with 100, 1.23 -> "123", and "123" -> 1.23
\r
760 public int getMultiplier () {
\r
761 return ((java.text.DecimalFormat)numberFormat).getMultiplier();
\r
765 * Set the multiplier for use in percent, permill, etc.
\r
766 * For a percentage, set the suffixes to have "%" and the multiplier to be 100.
\r
767 * (For Arabic, use arabic percent symbol).
\r
768 * For a permill, set the suffixes to have "\u2031" and the multiplier to be 1000.
\r
769 * <P>Examples: with 100, 1.23 -> "123", and "123" -> 1.23
\r
772 public void setMultiplier (int newValue) {
\r
773 ((java.text.DecimalFormat)numberFormat).setMultiplier(newValue);
\r
777 * Return the grouping size. Grouping size is the number of digits between
\r
778 * grouping separators in the integer portion of a number. For example,
\r
779 * in the number "123,456.78", the grouping size is 3.
\r
780 * @see #setGroupingSize
\r
781 * @see NumberFormat#isGroupingUsed
\r
782 * @see DecimalFormatSymbols#getGroupingSeparator
\r
785 public int getGroupingSize () {
\r
786 return ((java.text.DecimalFormat)numberFormat).getGroupingSize();
\r
790 * Set the grouping size. Grouping size is the number of digits between
\r
791 * grouping separators in the integer portion of a number. For example,
\r
792 * in the number "123,456.78", the grouping size is 3.
\r
793 * @see #getGroupingSize
\r
794 * @see NumberFormat#setGroupingUsed
\r
795 * @see DecimalFormatSymbols#setGroupingSeparator
\r
798 public void setGroupingSize (int newValue) {
\r
799 ((java.text.DecimalFormat)numberFormat).setGroupingSize(newValue);
\r
803 * Allows you to get the behavior of the decimal separator with integers.
\r
804 * (The decimal separator will always appear with decimals.)
\r
805 * <P>Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
\r
808 public boolean isDecimalSeparatorAlwaysShown() {
\r
809 return ((java.text.DecimalFormat)numberFormat).isDecimalSeparatorAlwaysShown();
\r
813 * Allows you to set the behavior of the decimal separator with integers.
\r
814 * (The decimal separator will always appear with decimals.)
\r
816 * <p>This only affects formatting, and only where
\r
817 * there might be no digits after the decimal point, e.g.,
\r
818 * if true, 3456.00 -> "3,456."
\r
819 * if false, 3456.00 -> "3456"
\r
820 * This is independent of parsing. If you want parsing to stop at the decimal
\r
821 * point, use setParseIntegerOnly.
\r
823 * <P>Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
\r
826 public void setDecimalSeparatorAlwaysShown(boolean newValue) {
\r
827 ((java.text.DecimalFormat)numberFormat).setDecimalSeparatorAlwaysShown(newValue);
\r
831 * Standard override; no change in semantics.
\r
834 public Object clone() {
\r
835 return new DecimalFormatSymbols((java.text.DecimalFormatSymbols)numberFormat.clone());
\r
839 * Synthesizes a pattern string that represents the current state
\r
840 * of this Format object.
\r
841 * @see #applyPattern
\r
844 public String toPattern() {
\r
845 return ((java.text.DecimalFormat)numberFormat).toPattern();
\r
849 * Synthesizes a localized pattern string that represents the current
\r
850 * state of this Format object.
\r
851 * @see #applyPattern
\r
854 public String toLocalizedPattern() {
\r
855 return ((java.text.DecimalFormat)numberFormat).toLocalizedPattern();
\r
860 * Apply the given pattern to this Format object. A pattern is a
\r
861 * short-hand specification for the various formatting properties.
\r
862 * These properties can also be changed individually through the
\r
863 * various setter methods.
\r
865 * There is no limit to integer digits are set
\r
866 * by this routine, since that is the typical end-user desire;
\r
867 * use setMaximumInteger if you want to set a real value.
\r
868 * For negative numbers, use a second pattern, separated by a semicolon
\r
869 * <P>Example "#,#00.0#" -> 1,234.56
\r
870 * <P>This means a minimum of 2 integer digits, 1 fraction digit, and
\r
871 * a maximum of 2 fraction digits.
\r
872 * <p>Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses.
\r
873 * <p>In negative patterns, the minimum and maximum counts are ignored;
\r
874 * these are presumed to be set in the positive pattern.
\r
877 public void applyPattern(String pattern) {
\r
878 ((java.text.DecimalFormat)numberFormat).applyPattern(pattern);
\r
882 * Apply the given pattern to this Format object. The pattern
\r
883 * is assumed to be in a localized notation. A pattern is a
\r
884 * short-hand specification for the various formatting properties.
\r
885 * These properties can also be changed individually through the
\r
886 * various setter methods.
\r
888 * There is no limit to integer digits are set
\r
889 * by this routine, since that is the typical end-user desire;
\r
890 * use setMaximumInteger if you want to set a real value.
\r
891 * For negative numbers, use a second pattern, separated by a semicolon
\r
892 * <P>Example "#,#00.0#" -> 1,234.56
\r
893 * <P>This means a minimum of 2 integer digits, 1 fraction digit, and
\r
894 * a maximum of 2 fraction digits.
\r
895 * <p>Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses.
\r
896 * <p>In negative patterns, the minimum and maximum counts are ignored;
\r
897 * these are presumed to be set in the positive pattern.
\r
900 public void applyLocalizedPattern(String pattern) {
\r
901 ((java.text.DecimalFormat)numberFormat).applyLocalizedPattern(pattern);
\r
projects / Dictionary.git / blob