Number and Currency Formatting

Formatting with Patterns

You can use the DecimalFormat class to format decimal numbers into locale-specific strings. This class allows you to control the display of leading and trailing zeros, prefixes and suffixes, grouping (thousands) separators, and the decimal separator. If you want to change formatting symbols such as the decimal separator, you can use the DecimalFormatSymbols in conjunction with the DecimalFormat class. These classes offer a great deal of flexibility in the formatting of numbers, but they can make your code more complex. Whenever possible, you should use the NumberFormat class, which is described in the previous section, instead of DecimalFormat and DecimalFormatSymbols.

Using examples, the text that follows shows you how to use the DecimalFormat and DecimalFormatSymbols classes. The code examples in this material are from a sample program called DecimalFormatDemo.java.

Constructing Patterns

You specify the formatting properties of DecimalFormat with a a pattern String. The pattern determines what the formatted number looks like. For a full description of the pattern syntax, see Number Format Pattern Syntax.

In the example that follows, we create a formatter by passing a pattern String to the DecimalFormat constructor. Then, we pass a double value to the format method, which returns a formatted String:

DecimalFormat myFormatter = new DecimalFormat(pattern);
String output = myFormatter.format(value);
System.out.println(value + "  " + pattern + "  " + output);

The output for the preceeding lines of code is described in the following table. The value is the number, a double, that is to be formatted. The pattern is the String that specifies the formatting properties. The output, which is a String, represents the formatted number.

value	pattern	output	Explanation
123456.789	###,###.###	123,456.789	The pound sign (#) denotes a digit, the comma is a placeholder for the grouping separator, and the period is a placeholder for the decimal separator.
123456.789	###.##	123456.79	The value has three digits to the right of the decimal point, but the pattern has only two. The format method handles this by rounding up.
123.78	000000.000	000123.780	The pattern specifies leading and trailing zeros, because the zero character is used instead of the pound sign (#).
12345.67	$###,###.###	$12,345.67	The first character in the pattern is the dollar sign ($). Note that the dollar sign immediately preceeds the left-most digit in the formatted output.
12345.67	\u00a5###,###.###	¥12,345.67	The pattern specifies the currency sign for Japanese yen (¥) with the Unicode value \u00a5.

Locale-sensitive Formatting

The preceeding example created a DecimalFormat object for the default Locale. If you want a DecimalFormat object for a non-default Locale, you instantiate a NumberFormat and then cast it to DecimalFormat. Then, the DecimalFormat object will format the patterns you define in a locale-sensitive manner. Here's an example:

NumberFormat nf = NumberFormat.getNumberInstance(loc);
DecimalFormat df = (DecimalFormat)nf;
df.applyPattern(pattern);
String output = df.format(value);
System.out.println(pattern + "  " + output + "  " + loc.toString());

Running the preceeding code example results in the output that follows. The formatted number, in the second column, varies with Locale:

###,###.###  123,456.789  en_US
###,###.###  123.456,789  de_DE
###,###.###  123 456,789  fr_FR

So far, the formatting patterns we've shown you follow the conventions of U.S. English. For example, in the pattern "###,###.##" the comma is the thousands-separator and the period represents the decimal point. This convention is fine, provided that your end-users aren't exposed to it. However, some applications, like spreadsheets and report generators, allow the end-users to define their own formatting patterns. For these applications, the formatting patterns specified by the end-users should use localized notation. In these cases, you'll want to invoke the applyLocalizedPattern method upon the DecimalFormat object.

Altering the Formatting Symbols

With the DecimalFormatSymbolsclass you can change the symbols that appear in the formatted numbers produced by the format method. These symbols include the decimal separator, the grouping separator, the minus sign, and the percent sign, among others.

In the example that follows, we illustrate the use of DecimalFormatSymbols by applying an unusual format to a number. We start by instantiating DecimalFormatSymbols without any arguments, which returns an object for the default Locale. (Because DecimalFormatSymbols is a locale-sensitive class, we could have specified a Locale when invoking the constructor.) Next, we modify the decimal and grouping separators. Then we specify the DecimalFormatSymbols when instantiating the DecimalFormat class. Just to make things more complicated, we change the grouping size of the formatter from three to four. Finally, we invoke the format method.

Here is the example code:

DecimalFormatSymbols unusualSymbols = new DecimalFormatSymbols();
unusualSymbols.setDecimalSeparator('|');
unusualSymbols.setGroupingSeparator('^');

String strange = "#,##0.###";
DecimalFormat weirdFormatter = new DecimalFormat(strange, unusualSymbols);
weirdFormatter.setGroupingSize(4);

String bizarre = weirdFormatter.format(12345.678);
System.out.println(bizarre);

This is what appears when we print this bizarrely formatted number:

1^2345|678

Number and Currency Formatting