public Class DecimalFormat

DecimalFormat is the primary concrete subclass of NumberFormat. It has a variety of features designed to make it possible to parse and format numbers in any locale, including support for Western, Arabic, or Indic digits. It supports different flavors of numbers, including integers ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts ("$123.00", "USD123.00", "123.00 US dollars"). All of these flavors can be easily localized.

To obtain a number formatter for a specific locale (including the default locale), call one of NumberFormat's factory methods such as NumberFormat#getInstance. Do not call DecimalFormat constructors directly unless you know what you are doing.

DecimalFormat aims to comply with the specification UTS #35. Read the specification for more information on how all the properties in DecimalFormat fit together.

Example Usage

Customize settings on a DecimalFormat instance from the NumberFormat factory:

NumberFormat f = NumberFormat.getInstance(loc);
if (f instanceof DecimalFormat) {
    ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true);
    ((DecimalFormat) f).setMinimumGroupingDigits(2);
}

Quick and dirty print out a number using the localized number, currency, and percent format for each locale:

for (ULocale uloc : ULocale.getAvailableLocales()) {
    System.out.print(uloc + ":\t");
    System.out.print(NumberFormat.getInstance(uloc).format(1.23));
    System.out.print("\t");
    System.out.print(NumberFormat.getCurrencyInstance(uloc).format(1.23));
    System.out.print("\t");
    System.out.print(NumberFormat.getPercentInstance(uloc).format(1.23));
    System.out.println();
}

Properties and Symbols

A DecimalFormat object encapsulates a set of properties and a set of symbols. Grouping size, rounding mode, and affixes are examples of properties. Locale digits and the characters used for grouping and decimal separators are examples of symbols.

To set a custom set of symbols, use setDecimalFormatSymbols. Use the various other setters in this class to set custom values for the properties.

Rounding

DecimalFormat provides three main strategies to specify the position at which numbers should be rounded:

1. Magnitude: Display a fixed number of fraction digits; this is the most common form.
2. Increment: Round numbers to the closest multiple of a certain increment, such as 0.05. This is common in currencies.
3. Significant Digits: Round numbers such that a fixed number of nonzero digits are shown. This is most common in scientific notation.

It is not possible to specify more than one rounding strategy. For example, setting a rounding increment in conjunction with significant digits results in undefined behavior.

It is also possible to specify the rounding mode to use. The default rounding mode is "half even", which rounds numbers to their closest increment, with ties broken in favor of trailing numbers being even. For more information, see setRoundingMode and the ICU User Guide.

Pattern Strings

A pattern string is a way to serialize some of the available properties for decimal formatting. However, not all properties are capable of being serialized into a pattern string; see applyPattern for more information.

Most users should not need to interface with pattern strings directly.

ICU DecimalFormat aims to follow the specification for pattern strings in UTS #35. Refer to that specification for more information on pattern string syntax.

Pattern String BNF

pattern    := subpattern (';' subpattern)?
subpattern := prefix? number exponent? suffix?
number     := (integer ('.' fraction)?) | sigDigits
prefix     := '\u0000'..'\uFFFD' - specialCharacters
suffix     := '\u0000'..'\uFFFD' - specialCharacters
integer    := '#'* '0'* '0'
fraction   := '0'* '#'*
sigDigits  := '#'* '@' '@'* '#'*
exponent   := 'E' '+'? '0'* '0'
padSpec    := '*' padChar
padChar    := '\u0000'..'\uFFFD' - quote
 
Notation:
  X*       0 or more instances of X
  X?       0 or 1 instances of X
  X|Y      either X or Y
  C..D     any character from C up to D, inclusive
  S-T      characters in S, except those in T

The first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers.

Not indicated in the BNF syntax above:

• The grouping separator ',' can occur inside the integer and sigDigits elements, between any two pattern characters of that element, as long as the integer or sigDigits element is not followed by the exponent element.
• Two grouping intervals are recognized: That between the decimal point and the first grouping symbol, and that between the first and second grouping symbols. These intervals are identical in most locales, but in some locales they differ. For example, the pattern "#,##,###" formats the number 123456789 as "12,34,56,789".
• The pad specifier padSpec may appear before the prefix, after the prefix, before the suffix, after the suffix, or not at all.
• In place of '0', the digits '1' through '9' may be used to indicate a rounding increment.

Parsing

DecimalFormat aims to be able to parse anything that it can output as a formatted string.

There are two primary parse modes: lenient and strict. Lenient mode should be used if the goal is to parse user input to a number; strict mode should be used if the goal is validation. The default is lenient mode. For more information, see setParseStrict.

DecimalFormat parses all Unicode characters that represent decimal digits, as defined by UCharacter#digit. In addition, DecimalFormat also recognizes as digits the ten consecutive characters starting with the localized zero digit defined in the DecimalFormatSymbols object. During formatting, the DecimalFormatSymbols-based digits are output.

Grouping separators are ignored in lenient mode (default). In strict mode, grouping separators must match the locale-specified grouping sizes.

When using parseCurrency, all currencies are accepted, not just the currency currently set in the formatter. In addition, the formatter is able to parse every currency style format for a particular locale no matter which style the formatter is constructed with. For example, a formatter instance gotten from NumberFormat.getInstance(ULocale, NumberFormat.CURRENCYSTYLE) can parse both "USD1.00" and "3.00 US dollars".

Whitespace characters (lenient mode) and control characters (lenient and strict mode), collectively called "ignorables", do not need to match in identity or quantity between the pattern string and the input string. For example, the pattern "# %" matches "35 %" (with a single space), "35%" (with no space), "35 %" (with a non-breaking space), and "35  %" (with multiple spaces). Arbitrary ignorables are also allowed at boundaries between the parts of the number: prefix, number, exponent separator, and suffix. Ignorable whitespace characters are those having the Unicode "blank" property for regular expressions, defined in UTS #18 Annex C, which is "horizontal" whitespace, like spaces and tabs, but not "vertical" whitespace, like line breaks. Ignorable control characters are those in the Unicode set [:Default_Ignorable_Code_Point:].

If parse(String, ParsePosition) fails to parse a string, it returns null and leaves the parse position unchanged. The convenience method parse(String) indicates parse failure by throwing a java.text.ParseException.

Under the hood, a state table parsing engine is used. To debug a parsing failure during development, use the following pattern to print details about the state table transitions:

com.ibm.icu.impl.number.Parse.DEBUGGING = true;
df.parse("123.45", ppos);
com.ibm.icu.impl.number.Parse.DEBUGGING = false;

Thread Safety and Best Practices

Starting with ICU 59, instances of DecimalFormat are thread-safe.

Under the hood, DecimalFormat maintains an immutable formatter object that is rebuilt whenever any of the property setters are called. It is therefore best practice to call property setters only during construction and not when formatting numbers online.