[ Home ] [ Up ] [ Using NumberFormat ] [ Using DecimalFormat ] [ DecimalFormat Example ] [ Using MessageFormat ]

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!)

Special cases:

• NaN (IEEE floating point "not-a-number") 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.

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:

Here are some examples of typical format string usage:

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 patterns, such as "#.#.#" or mixing '_' and '*' in the same pattern, will cause an IllegalArgumentException to be thrown. From the message of IllegalArgumentException, 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 "#,##,###,####" == "######,####" == "##,####,####".
• When calling DecimalFormat.parse(String, ParsePosition) and parsing fails, a null object will be returned. The unchanged parse position also reflects that an error has occurred during parsing. When calling the convenient method DecimalFormat.parse(String) and parsing fails, a ParseException will be thrown.
• 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.