This section describes how to use the `DecimalFormat` class in the package. For general-purpose formatting use the `Formatter` API, introduced in Java SE 5. See for more information. You can use the `DecimalFormat` class to format decimal numbers into 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.

The text that follows uses examples that demonstrate the `DecimalFormat` and `DecimalFormatSymbols` classes. The code examples in this material are from a sample program called .

### Constructing Patterns

> You specify the formatting properties of `DecimalFormat` with a pattern `String`. The pattern determines what the formatted number looks like. The example that follows creates a formatter by passing a pattern `String` to the `DecimalFormat` constructor. The `format` method accepts a `double` value as an argument and returns the formatted number in a `String`: DecimalFormat myFormatter = new DecimalFormat(pattern); String output = myFormatter.format(value); System.out.println(value + " " + pattern + " " + output); The output for the preceding 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.

> Output from `DecimalFormatDemo` Program
> `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 0 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 it immediately precedes the leftmost digit in the formatted `output`.
> 12345.67 | \u00A5###,###.### | ¥12,345.67 | The `pattern` specifies the currency sign for Japanese yen (¥) with the Unicode value 00A5.

### Altering the Formatting Symbols

> You can use the `` class to 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.

> The next example demonstrates the `DecimalFormatSymbols` class by applying a strange format to a number. The unusual format is the result of the calls to the `setDecimalSeparator`, `setGroupingSeparator`, and `setGroupingSize` methods. DecimalFormatSymbols unusualSymbols = new DecimalFormatSymbols(currentLocale); 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);

> When run, this example prints the number in a bizarre format: 1^2345|678