java.lang.Object
|
+----java.text.Format
|
+----java.text.NumberFormat
|
+----java.text.DecimalFormat
public class DecimalFormat
extends NumberFormat
DecimalFormat is a concrete subclass of NumberFormat for formatting decimal numbers. This class allows for a variety of parameters, and localization to Western, Arabic, or Indic numbers.
Normally, you get the proper NumberFormat for a specific locale (including the default locale) using one of NumberFormat's factory methods such as getInstance. You may then modify it from there (after testing to make sure it is a DecimalFormat, of course!)
Either the prefixes or the suffixes must be different for the parse to distinguish positive from negative. Parsing will be unreliable if the digits, thousands or decimal separators are the same, or if any of them occur in the prefixes or suffixes.
Special cases:
NaN is formatted as a single character, typically \\uFFFD.
+/-Infinity is formatted as a single character, typically \\u221E, plus the positive and negative pre/suffixes.
Note: this class is designed for common users; for very large or small numbers, use a format that can express exponential values.
Example:
// normally we would have a GUI with a menu for this
Locale[] locales = NumberFormat.getAvailableLocales();
double myNumber = -1234.56;
NumberFormat form;
// just for fun, we print out a number with the locale number, currency
// and percent format for each locale we can.
for (int j = 0; j < 3; ++j) {
System.out.println("FORMAT");
for (int i = 0; i < locales.length; ++i) {
if (locales[i].getCountry().length() == 0) {
// skip language-only
continue;
}
System.out.print(locales[i].getDisplayName());
switch (j) {
default:
form = NumberFormat.getInstance(locales[i]); break;
case 1:
form = NumberFormat.getCurrencyInstance(locales[i]); break;
case 0:
form = NumberFormat.getPercentInstance(locales[i]); break;
}
try {
System.out.print(": " + ((DecimalFormat)form).toPattern()
+ " -> " + form.format(myNumber));
} catch (IllegalArgumentException iae) { }
try {
System.out.println(" -> " + form.parse(form.format(myNumber)));
} catch (ParseException pe) { }
}
}
The following shows the structure of the pattern.
pattern := subpattern{;subpattern}
subpattern := {prefix}integer{.fraction}{suffix}
prefix := '\\u0000'..'\\uFFFD' - specialCharacters
suffix := '\\u0000'..'\\uFFFD' - specialCharacters
integer := '#'* '0'* '0'
fraction := '0'* '#'*
Notation:
X* 0 or more instances of X
(X | Y) either X or Y.
X..Y any character from X up to Y, inclusive.
S - T characters in S, except those in T
The first subpattern is for positive numbers. The second (optional)
subpattern is for negative numbers. (In both cases, ',' can occur
inside the integer portion--it is just too messy to indicate in BNF.)
Here are the special characters used in the parts of the subpattern, with notes on their usage.
Symbol Meaning 0 a digit # a digit, zero shows as absent . placeholder for decimal separator , placeholder for grouping separator. ; separates formats. - default negative prefix. % divide by 100 and show as percentage X any other characters can be used in the prefix or suffix ' used to quote special characters in a prefix or suffix.
Notes
If there is no explicit negative subpattern, - is prefixed to the positive form. That is, "0.00" alone is equivalent to "0.00;-0.00".
Illegal formats, such as "#.#.#" or mixing '_' and '*' in the same format, will cause an ParseException to be thrown. From that ParseException, you can find the place in the string where the error occurred.
The grouping separator is commonly used for thousands, but in some countries for ten-thousands. The interval is a constant number of digits between the grouping characters, such as 100,000,000 or 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. So "#,##,###,####" == "######,####" == "##,####,####".
This class only handles localized digits where the 10 digits are contiguous in Unicode, from 0 to 9. Other digits sets (such as superscripts) would need a different subclass.