Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Text, Formatting and Regex

The DecimalFormat class

Reference for java.text.DecimalFormat: pattern symbols 0, #, comma, percent and exponent, rounding modes, parsing, locale symbols and thread-safety warnings.

java.text.DecimalFormat formats numbers according to a pattern you write, such as #,##0.00 or 000 or 0.0%, and parses text back into numbers. It is the tool for exact control: fixed digits, optional digits, grouping, prefixes, suffixes, scientific notation.

The symbols it prints (decimal point, grouping separator, minus sign) come from a DecimalFormatSymbols object. If you do not pass one, the default locale decides, so pass DecimalFormatSymbols.getInstance(Locale.US) (or Locale.ROOT) whenever the output must be predictable.

Java
DecimalFormat df = new DecimalFormat("#,##0.00", DecimalFormatSymbols.getInstance(Locale.US));
df.format(1234567.891);   // "1,234,567.89"

Try it

Java Common patterns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Rounding, parsing and locale symbols

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public class DecimalFormat extends NumberFormat

new DecimalFormat(String pattern)
new DecimalFormat(String pattern, DecimalFormatSymbols symbols)

Pattern symbols

Symbol Meaning
0 a digit that is always shown (padded with a zero)
# a digit that is shown only if needed
. decimal separator position
, grouping separator; the distance to the end of the integer part sets the group size
E scientific notation, followed by 0s for the minimum exponent digits (0.00E0)
; separates the positive pattern from the negative one
% multiply by 100 and show a percent sign
โ€ฐ multiply by 1000 (per mille)
ยค currency sign
' quotes special characters in a prefix or suffix; '' is a literal quote
Method Description
format(double), format(long), format(Object) formats a number; also accepts BigDecimal and BigInteger through format(Object)
parse(String) parses from the start of the text and returns a Long or Double; throws ParseException
setRoundingMode(RoundingMode) default is HALF_EVEN
setMaximumFractionDigits(int), setMinimumFractionDigits(int), setGroupingUsed(boolean) adjust the pattern after creation
setParseBigDecimal(boolean) make parse return BigDecimal
toPattern(), toLocalizedPattern() the pattern in invariant or localized symbols

Throws: IllegalArgumentException for an invalid pattern; ParseException from parse.

Usage notes

  • 0 versus #. Use 0 for digits that must appear ("000" gives 007) and # for digits that may be dropped. "0.##" prints 2 as 2 but 2.5 as 2.5.
  • Half-even rounding. DecimalFormat rounds ties to the nearest even digit, so 2.5 becomes 2 and 3.5 becomes 4. String.format("%.0f", 2.5) uses half-up and gives 3. Call setRoundingMode() if you want to match.
  • Not thread-safe. A DecimalFormat keeps mutable state. Create one per call or per thread, or guard it with a lock; never keep it in a shared static field.
  • Always give the symbols. new DecimalFormat("0.00") uses the default locale, so on a German machine the same code prints 3,14.
  • Doubles carry binary error. format(0.125) is exact, but 1.005 is stored slightly below 1.005, so the pattern 0.00 prints 1.00 (while String.format("%.2f", 1.005) prints 1.01). For money pass a BigDecimal.
  • Leading zero. With #.00 the integer part is optional, so 0.5 prints .50; use 0.00 to keep the zero.
  • Parsing is lenient. parse("42 apples") returns 42. Use parse(String, ParsePosition) and check that the whole text was consumed if you need strict validation.
  • Pattern limits. Patterns cannot express a fixed number of integer digits with grouping in arbitrary places; the grouping size is taken from the last comma.
  • Percent and per mille change the value, not just the suffix: 0.256 with "0.0%" prints 25.6%.