|
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.
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
DecimalFormatDemo.
DecimalFormat
with 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.
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);
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 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.
|
DecimalFormat object for
the default Locale. If you want a
DecimalFormat object for a nondefault Locale,
you instantiate a NumberFormat and then cast it to
DecimalFormat. 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 previous code example results in the output that follows.
The formatted number, which is 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 discussed here 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, such as 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 on the
DecimalFormat object.
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
pattern := subpattern{;subpattern}
subpattern := {prefix}integer{.fraction}{suffix}
prefix := '\\u0000'..'\\uFFFD' - specialCharacters
suffix := '\\u0000'..'\\uFFFD' - specialCharacters
integer := '#'* '0'* '0'
fraction := '0'* '#'*
| Notation | Description |
|---|---|
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 |
{X} | X is optional |
Although not noted in the BNF diagram, a comma may appear within the integer portion.
Within the subpatterns, you specify formatting with special symbols. These symbols are described in the following table:
| Symbol | Description |
|---|---|
| 0 | a digit |
| # | a digit, zero shows as absent |
| . | placeholder for decimal separator |
| , | placeholder for grouping separator |
| E | separates mantissa and exponent for exponential formats |
| ; | separates formats |
| - | default negative prefix |
| % | multiply by 100 and show as percentage |
| ? | multiply by 1000 and show as per mille |
| ¤ | currency sign; replaced by currency symbol; if doubled, replaced by international currency symbol; if present in a pattern, the monetary decimal separator is used instead of the decimal separator |
| X | any other characters can be used in the prefix or suffix |
| ' | used to quote special characters in a prefix or suffix |
|
