See Also: DecimalFormat Members
A concrete subclass of Java.Text.NumberFormat that formats decimal numbers. 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 also supports different flavors of numbers, including integers ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts ("$123"). All of these flavors can be easily localized.
This is an enhanced version of DecimalFormat that is based on the standard version in the RI. New or changed functionality is labeled NEW.
To obtain a Java.Text.NumberFormat for a specific locale (including the default locale), call one of NumberFormat's factory methods such as NumberFormat.getInstance. Do not call the DecimalFormat constructors directly, unless you know what you are doing, since the Java.Text.NumberFormat factory methods may return subclasses other than DecimalFormat. If you need to customize the format object, do something like this:
java Example
NumberFormat f = NumberFormat.getInstance(loc); if (f instanceof DecimalFormat) { ((DecimalFormat)f).setDecimalSeparatorAlwaysShown(true); }
A DecimalFormat consists of a pattern and a set of symbols. The pattern may be set directly using DecimalFormat.ApplyPattern(string), or indirectly using other API methods which manipulate aspects of the pattern, such as the minimum number of integer digits. The symbols are stored in a Java.Text.DecimalFormatSymbols object. When using the Java.Text.NumberFormat factory methods, the pattern and symbols are read from ICU's locale data.
Many characters in a pattern are taken literally; they are matched during parsing and are written out unchanged during formatting. On the other hand, special characters stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed.
To insert a special character in a pattern as a literal, that is, without any special meaning, the character must be quoted. There are some exceptions to this which are noted below.
The characters listed here are used in non-localized patterns. Localized patterns use the corresponding characters taken from this formatter's Java.Text.DecimalFormatSymbols object instead, and these characters lose their special status. Two exceptions are the currency sign and quote, which are not localized.
Symbol Location Localized? Meaning 0 Number Yes Digit. @ Number No NEW Significant digit. # Number Yes Digit, leading zeroes are not shown. . Number Yes Decimal separator or monetary decimal separator. - Number Yes Minus sign. , Number Yes Grouping separator. E Number Yes Separates mantissa and exponent in scientific notation. Does not need to be quoted in prefix or suffix. + Exponent Yes NEW Prefix positive exponents with localized plus sign. Does not need to be quoted in prefix or suffix. ; Subpattern boundary Yes Separates positive and negative subpatterns. % Prefix or suffix Yes Multiply by 100 and show as percentage. ‰ (\u2030) Prefix or suffix Yes Multiply by 1000 and show as per mille. ¤ (\u00A4) Prefix or suffix No 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. ' Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock". * Prefix or suffix boundary Yes NEW Pad escape, precedes pad character.
A DecimalFormat pattern contains a positive and negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part and a suffix. If there is no explicit negative subpattern, the negative subpattern is the localized minus sign prefixed to the positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are ignored in the negative subpattern. This means that "#,##0.0#;(#)" produces precisely the same result as "#,##0.0#;(#,##0.0#)".
The prefixes, suffixes, and various symbols used for infinity, digits, thousands separators, decimal separators, etc. may be set to arbitrary values, and they will appear properly during formatting. However, care must be taken that the symbols and strings do not conflict, or parsing will be unreliable. For example, either the positive and negative prefixes or the suffixes must be distinct for NumberFormat.Parse(string) to be able to distinguish positive from negative values. Another example is that the decimal separator and thousands separator should be distinct characters, or parsing will be impossible.
The grouping separator is a character that separates clusters of integer digits to make large numbers more legible. It is commonly used for thousands, but in some locales it separates ten-thousands. The grouping size is the number of digits between the grouping separators, such as 3 for "100,000,000" or 4 for "1 0000 0000". There are actually two different grouping sizes: One used for the least significant integer digits, the primary grouping size, and one used for all others, the secondary grouping size. In most locales these are the same, but sometimes they are different. For example, if the primary grouping interval is 3, and the secondary is 2, then this corresponds to the pattern "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a pattern contains multiple grouping separators, the interval between the last one and the end of the integer defines the primary grouping size, and the interval between the last two defines the secondary grouping size. All others are ignored, so "#,##,###,####", "###,###,####" and "##,#,###,####" produce the same result.
Illegal patterns, such as "#.#.#" or "#.###,###", will cause DecimalFormat to throw an Java.Lang.IllegalArgumentException with a message that describes the problem.
java Example
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
Not indicated in the BNF syntax above:
DecimalFormat parses all Unicode characters that represent decimal digits, as defined by Java.Lang.Character.Digit(int, System.Int32). In addition, DecimalFormat also recognizes as digits the ten consecutive characters starting with the localized zero digit defined in the Java.Text.DecimalFormatSymbols object. During formatting, the Java.Text.DecimalFormatSymbols-based digits are written out.
During parsing, grouping separators are ignored.
If DecimalFormat.Parse(string, Java.Text.ParsePosition) fails to parse a string, it returns null and leaves the parse position unchanged.
Formatting is guided by several parameters, all of which can be specified either using a pattern or using the API. The following description applies to formats that do not use or .
Special Values
NaN is represented as a single character, typically \uFFFD. This character is determined by the Java.Text.DecimalFormatSymbols object. This is the only value for which the prefixes and suffixes are not used.
Infinity is represented as a single character, typically \u221E, with the positive or negative prefixes and suffixes applied. The infinity character is determined by the Java.Text.DecimalFormatSymbols object.
Numbers in scientific notation are expressed as the product of a mantissa and a power of ten, for example, 1234 can be expressed as 1.234 x 103. The mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), but it does not need to be. DecimalFormat supports arbitrary mantissas. DecimalFormat can be instructed to use scientific notation through the API or through the pattern. In a pattern, the exponent character immediately followed by one or more digit characters indicates scientific notation. Example: "0.###E0" formats the number 1234 as "1.234E3".
Pattern Minimum significant digits Maximum significant digits Number Output of format() @@@ 3 3 12345 12300 @@@ 3 3 0.12345 0.123 @@## 2 4 3.14159 3.142 @@## 2 4 1.23004 1.23
DecimalFormat supports padding the result of format to a specific width. Padding may be specified either through the API or through the pattern syntax. In a pattern, the pad escape character followed by a single pad character causes padding to be parsed and formatted. The pad escape character is '*' in unlocalized patterns. For example, "$*x#,##0.00" formats 123 to "$xx123.00", and 1234 to "$1,234.00".
Features marked as NEW and patterns that use characters not documented above are unlikely to serialize/deserialize correctly.
DecimalFormat objects are not synchronized. Multiple threads should not access one formatter concurrently.