1. Java Internationalization
2. Java Internationalization: Overview
3. Java Locale
4. Java ResourceBundle
5. Java NumberFormat
6. Java DecimalFormat
7. Java DateFormat
8. Java SimpleDateFormat
9. Java Internationalization: Time Zones
10. Java Internationalization: Character Methods
11. Java Internationalization: Collator - Sorting Strings
12. Java Internationalization: BreakIterator
13. Java Internationalization: Converting to and from Unicode

• Creating a DecimalFormat
  • applyPattern() + applyLocalizedPattern()
• Formatting Numbers
• Creating a DecimalFormat For a Specific Locale
• Number Format Pattern Syntax
• DecimalFormatSymbols
• Grouping Digits

The java.text.DecimalFormat class is used to format numbers using a formatting pattern you specify yourself. This text explains how to use the DecimalFormat class to format different types of numbers.

Creating a DecimalFormat

Creating a DecimalFormat instance is done like this:

String pattern = "###,###.###";
DecimalFormat decimalFormat = new DecimalFormat(pattern);

The pattern parameter passed to the DecimalFormat constructor is the number pattern that numbers should be formatted according to.

applyPattern() + applyLocalizedPattern()

As you can see, the DecimalFormat is created with a formatting pattern. You can change this pattern later using the applyPattern() or applyLocalizedPattern() method. Here are two examples:

decimalFormat.applyPattern("#0.##");

decimalFormat.applyLocalizedPattern("#0,##");

The applyPattern() method simply applies a new pattern to the DecimalFormat instance as if it were created with that pattern.

The applyLocalizedPattern() does the same as applyPattern() except it interpretes the characters in the pattern according to the Locale the DecimalFormat was created with. That means that the characters used to signal where the decimal separator should be etc. are now interpreted according to what characters are used for that Locale, instead of just using the standard marking characters in the pattern.

If you look at the example above, notice that the second pattern uses a comma as decimal (fraction) separator instead of the normal dot. In Danish we use a comma instead of a dot between the integer part and fraction part of numbers. Therefore the localized pattern uses a comma too.

Normally you don't need to use the applyLocalizedPattern() method. There are some situations where it makes sense, and that is when you allow the user to type in a formatting pattern. A Danish user would naturally use different symbols in such a pattern than an english user.

Constructing a DecimalFormat for a specific Locale is covered later in this text.

Formatting Numbers

You format a number using the format() method of the DecimalFormat instance. Here is an example:

String pattern = "###,###.###";
DecimalFormat decimalFormat = new DecimalFormat(pattern);

String format = decimalFormat.format(123456789.123);
System.out.println(format);

The output printed from this code would be:

123.456.789,123

Creating a DecimalFormat For a Specific Locale

The previous section created a DecimalFormat for the default Locale of the JVM (computer) the code is running on. If you want to create a DecimalFormat instance for a specific Locale, create a NumberFormat and cast it to a DecimalFormat. Here is an example:

Locale locale  = new Locale("en", "UK");
String pattern = "###.##";

DecimalFormat decimalFormat = (DecimalFormat)
        NumberFormat.getNumberInstance(locale);
decimalFormat.applyPattern(pattern);

String format = decimalFormat.format(123456789.123);
System.out.println(format);

The output printed from this code would be:

123456789.12

If you had used a Danish Locale instead, the output would have been:

123456789,12

Notice the use of a comma instead of a dot to separate the integer part from the fraction part of the number.

Number Format Pattern Syntax

You can use the following characters in the formatting pattern:

Here are a few examples, formatted using a UK Locale:

Notice that some numbers are rounded, just like with a NumberFormat instance.

DecimalFormatSymbols

You can customize which symbols are used as decimal separator, grouping separator etc. using a DecimalFormatSymbols instance. Here is an example:

Locale locale = new Locale("en", "UK");

DecimalFormatSymbols symbols = new DecimalFormatSymbols(locale);
symbols.setDecimalSeparator(';');
symbols.setGroupingSeparator(':');

String pattern = "#,##0.###";
DecimalFormat decimalFormat = new DecimalFormat(pattern, symbols);

String number = decimalFormat.format(123456789.123);
System.out.println(number);

The output printed from this code would be:

123:456:789;123

Notice the use of : as a thousand separator, and ; as a decimal separator (fraction separator). These were the symbols set on the DecimalFormatSymbols instance passed to the DecimalFormat constructor.

There are a whole lot more symbols you can set. Here is a list of the methods you can call on a DecimalFormatSymbols instance:

setDecimalSeparator();
setGroupingSeparator();
setCurrency();
setCurrencySymbol();
setDecimalSeparator();
setDigit();
setExponentSeparator();
setGroupingSeparator();
setInfinity();
setInternationalCurrencySymbol();
setMinusSign();
setMonetaryDecimalSeparator();
setNaN();
setPatternSeparator();
setPercent();
setPerMill();
setZeroDigit();

For a full explanation of what these methods do, see the JavaDoc for the DecimalFormatSymbols class.

Grouping Digits

The DecimalFormat class has a method called setGroupingSize() which sets how many digits of the integer part to group. Groups are separated by the grouping separator. Here is an example:

String pattern = "#,###.###";
DecimalFormat decimalFormat = new DecimalFormat(pattern);
decimalFormat.setGroupingSize(4);

String number = decimalFormat.format(123456789.123);
System.out.println(number);

The output printed from this code would be:

1,2345,6789.123

Notice how the integer part of the number is now grouped using 4 digits per group instead of the normal 3 digits.

The same effect could have been achieved by just changing the pattern string, like this:

String pattern = "####,####.###";
DecimalFormat decimalFormat = new DecimalFormat(pattern);

String number = decimalFormat.format(123456789.123);
System.out.println(number);

Notice how 4 # characters are used in each group in the pattern.