java.lang.Object | |||
↳ | java.text.Format | ||
↳ | java.text.NumberFormat | ||
↳ | java.text.DecimalFormat |
A concrete subclass of 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 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
NumberFormat
factory methods may return subclasses other than
DecimalFormat
. If you need to customize the format object, do
something like this:
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
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 DecimalFormatSymbols
object. When
using the 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
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 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 IllegalArgumentException
with a
message that describes the problem.
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 TThe first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers.
Not indicated in the BNF syntax above:
padSpec
may appear before the prefix, after the prefix,
before the suffix, after the suffix or not at all.
DecimalFormat
parses all Unicode characters that represent decimal
digits, as defined by digit(int, int)
. 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 written out.
During parsing, grouping separators are ignored.
If parse(String, 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 scientific notation or significant digits.
Special Values
NaN
is represented as a single character, typically
\uFFFD
. This character is determined by the
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 DecimalFormatSymbols
object.
Scientific Notation
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".
DecimalFormat
has two ways of controlling how many digits are
shown: (a) significant digit counts or (b) integer and fraction digit counts.
Integer and fraction digit counts are described above. When a formatter uses
significant digits counts, the number of integer and fraction digits is not
specified directly, and the formatter settings for these counts are ignored.
Instead, the formatter uses as many integer and fraction digits as required
to display the specified number of significant digits.
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
'@'
and '#'
characters. The minimum number of significant
digits is the number of '@'
characters. The maximum number of
significant digits is the number of '@'
characters plus the number of
'#'
characters following on the right. For example, the pattern
"@@@"
indicates exactly 3 significant digits. The pattern
"@##"
indicates from 1 to 3 significant digits. Trailing zero digits
to the right of the decimal separator are suppressed after the minimum number
of significant digits have been shown. For example, the pattern "@##"
formats the number 0.1203 as "0.12"
.
'0'
pattern character. Patterns such as
"@00"
or "@.###"
are disallowed.
'#'
characters may be prepended to the left of the
leftmost '@'
character. These have no effect on the minimum and
maximum significant digit counts, but may be used to position grouping
separators. For example, "#,#@#"
indicates a minimum of one
significant digit, a maximum of two significant digits, and a grouping size
of three.
'@'
pattern character.
'@'
pattern character.
"@@###E0"
is equivalent to "0.0###E0"
.
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"
.
"* #0 o''clock"
, the format width is 10.char
s).applyPattern(String)
throws an IllegalArgumentException
. If there is no prefix, before the prefix and after
the prefix are equivalent, likewise for the suffix.char
immediately
following the pad escape is the pad character. This may be any character,
including a special pattern character. That is, the pad escape
escapes the following character. If there is no character after
the pad escape, then the pattern is illegal.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.
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.NumberFormat
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a new
DecimalFormat for formatting and parsing numbers
for the user's default locale. | |||||||||||
Constructs a new
DecimalFormat using the specified non-localized
pattern and the DecimalFormatSymbols for the user's default Locale. | |||||||||||
Constructs a new
DecimalFormat using the specified non-localized
pattern and DecimalFormatSymbols . |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Changes the pattern of this decimal format to the specified pattern which
uses localized pattern characters.
| |||||||||||
Changes the pattern of this decimal format to the specified pattern which
uses non-localized pattern characters.
| |||||||||||
Returns a new instance of
DecimalFormat with the same pattern and
properties. | |||||||||||
Compares the specified object to this decimal format and indicates if
they are equal.
| |||||||||||
Formats the specified long value as a string using the pattern of this
number format and appends the string to the specified string buffer.
| |||||||||||
Formats the specified double value as a string using the pattern of this
number format and appends the string to the specified string buffer.
| |||||||||||
Formats a number into a supplied buffer.
| |||||||||||
Formats the specified object using the rules of this decimal format and
returns an
AttributedCharacterIterator with the formatted number
and attributes. | |||||||||||
Returns the currency used by this decimal format.
| |||||||||||
Returns the
DecimalFormatSymbols used by this decimal format. | |||||||||||
Returns the number of digits grouped together by the grouping separator.
| |||||||||||
Returns the multiplier which is applied to the number before formatting
or after parsing.
| |||||||||||
Returns the prefix which is formatted or parsed before a negative number.
| |||||||||||
Returns the suffix which is formatted or parsed after a negative number.
| |||||||||||
Returns the prefix which is formatted or parsed before a positive number.
| |||||||||||
Returns the suffix which is formatted or parsed after a positive number.
| |||||||||||
Returns the
RoundingMode used by this NumberFormat . | |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Indicates whether the decimal separator is shown when there are no
fractional digits.
| |||||||||||
Returns true if digit grouping is used in this format.
| |||||||||||
This value indicates whether the return object of the parse operation is
of type
BigDecimal . | |||||||||||
Returns true if this number format only parses integer numbers.
| |||||||||||
Parses a
Long or Double from the specified string
starting at the index specified by position . | |||||||||||
Sets the currency used by this decimal format.
| |||||||||||
Sets the
DecimalFormatSymbols used by this decimal format. | |||||||||||
Sets whether the decimal separator is shown even when there are no fractional
digits.
| |||||||||||
Sets the number of digits grouped together by the grouping separator.
| |||||||||||
Sets whether or not digit grouping will be used in this format.
| |||||||||||
Sets the maximum number of digits after the decimal point.
| |||||||||||
Sets the maximum number of digits before the decimal point.
| |||||||||||
Sets the minimum number of digits after the decimal point.
| |||||||||||
Sets the minimum number of digits before the decimal point.
| |||||||||||
Sets the multiplier which is applied to the number before formatting or
after parsing.
| |||||||||||
Sets the prefix which is formatted or parsed before a negative number.
| |||||||||||
Sets the suffix which is formatted or parsed after a negative number.
| |||||||||||
Sets the behavior of the parse method.
| |||||||||||
Sets the flag that indicates whether numbers will be parsed as integers.
| |||||||||||
Sets the prefix which is formatted or parsed before a positive number.
| |||||||||||
Sets the suffix which is formatted or parsed after a positive number.
| |||||||||||
Sets the
RoundingMode used by this NumberFormat . | |||||||||||
Returns the pattern of this decimal format using localized pattern
characters.
| |||||||||||
Returns the pattern of this decimal format using non-localized pattern
characters.
| |||||||||||
Returns a string containing a concise, human-readable description of this
object.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.NumberFormat
| |||||||||||
From class
java.text.Format
| |||||||||||
From class
java.lang.Object
|
Constructs a new DecimalFormat
for formatting and parsing numbers
for the user's default locale.
See "Be wary of the default locale".
Constructs a new DecimalFormat
using the specified non-localized
pattern and the DecimalFormatSymbols
for the user's default Locale.
See "Be wary of the default locale".
pattern | the non-localized pattern. |
---|
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Constructs a new DecimalFormat
using the specified non-localized
pattern and DecimalFormatSymbols
.
pattern | the non-localized pattern. |
---|---|
value | the DecimalFormatSymbols. |
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Changes the pattern of this decimal format to the specified pattern which uses localized pattern characters.
pattern | the localized pattern. |
---|
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Changes the pattern of this decimal format to the specified pattern which uses non-localized pattern characters.
pattern | the non-localized pattern. |
---|
IllegalArgumentException | if the pattern cannot be parsed. |
---|
Returns a new instance of DecimalFormat
with the same pattern and
properties.
Compares the specified object to this decimal format and indicates if
they are equal. In order to be equal, object
must be an instance
of DecimalFormat
with the same pattern and properties.
object | the object to compare with this object. |
---|
true
if the specified object is equal to this decimal
format; false
otherwise.Formats the specified long value as a string using the pattern of this number format and appends the string to the specified string buffer.
If the field
member of position
contains a value
specifying a format field, then its beginIndex
and
endIndex
members will be updated with the position of the first
occurrence of this field in the formatted text.
value | the long to format. |
---|---|
buffer | the target string buffer to append the formatted long value to. |
position | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
Formats the specified double value as a string using the pattern of this number format and appends the string to the specified string buffer.
If the field
member of position
contains a value
specifying a format field, then its beginIndex
and
endIndex
members will be updated with the position of the first
occurrence of this field in the formatted text.
value | the double to format. |
---|---|
buffer | the target string buffer to append the formatted double value to. |
position | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
Formats a number into a supplied buffer.
The number must be a subclass of Number
. Instances of Byte
, Short
,
Integer
, and Long
have Number.longValue
invoked, as do instances of
BigInteger
where BigInteger.bitLength
returns less than 64. All other
values have Number.doubleValue
invoked instead.
If the field
member of field
contains a value specifying
a format field, then its beginIndex
and endIndex
members
will be updated with the position of the first occurrence of this field
in the formatted text.
number | the object to format, must be a Number . |
---|---|
buffer | the target string buffer to append the formatted number to. |
position | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
Formats the specified object using the rules of this decimal format and
returns an AttributedCharacterIterator
with the formatted number
and attributes.
object | the object to format. |
---|
IllegalArgumentException | if object cannot be formatted by this format. |
---|---|
NullPointerException | if object is null .
|
Returns the currency used by this decimal format.
Returns the DecimalFormatSymbols
used by this decimal format.
DecimalFormatSymbols
used by this decimal
format.
Returns the number of digits grouped together by the grouping separator. This only allows to get the primary grouping size. There is no API to get the secondary grouping size.
Returns the multiplier which is applied to the number before formatting or after parsing. The multiplier is meant for tasks like parsing percentages. For example, given a multiplier of 100, 1.23 would be formatted as "123" and "123" would be parsed as 1.23.
Returns the prefix which is formatted or parsed before a negative number.
Returns the suffix which is formatted or parsed after a negative number.
Returns the prefix which is formatted or parsed before a positive number.
Returns the suffix which is formatted or parsed after a positive number.
Returns the RoundingMode
used by this NumberFormat
.
Returns an integer hash code for this object. By contract, any two
objects for which equals(Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct
hashCode
method
if you intend implementing your own hashCode
method.
Indicates whether the decimal separator is shown when there are no fractional digits.
true
if the decimal separator should always be formatted;
false
otherwise.
Returns true if digit grouping is used in this format. Grouping affects both formatting and parsing.
true
if a grouping separator is used; false
otherwise.
This value indicates whether the return object of the parse operation is
of type BigDecimal
. This value defaults to false
.
true
if parse always returns BigDecimals
,
false
if the type of the result is Long
or
Double
.
Returns true if this number format only parses integer numbers. Parsing stops if a decimal separator is encountered.
Parses a Long
or Double
from the specified string
starting at the index specified by position
. If the string is
successfully parsed then the index of the ParsePosition
is
updated to the index following the parsed text. On error, the index is
unchanged and the error index of ParsePosition
is set to the
index where the error occurred.
string | the string to parse. |
---|---|
position | input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred. |
Long
or Double
resulting from the parse or
null
if there is an error. The result will be a
Long
if the parsed number is an integer in the range of a
long, otherwise the result is a Double
. If
isParseBigDecimal
is true
then it returns the
result as a BigDecimal
.
Sets the currency used by this decimal format. The min and max fraction digits remain the same.
currency | the new currency. |
---|
Sets the DecimalFormatSymbols
used by this decimal format.
Sets whether the decimal separator is shown even when there are no fractional digits.
Sets the number of digits grouped together by the grouping separator. This only allows to set the primary grouping size; the secondary grouping size can only be set with a pattern.
Sets whether or not digit grouping will be used in this format. Grouping affects both formatting and parsing.
value | true if a grouping separator is used; false
otherwise.
|
---|
Sets the maximum number of digits after the decimal point. If the value passed is negative then it is replaced by 0. Regardless of this setting, no more than 340 digits will be used.
value | the maximum number of fraction digits. |
---|
Sets the maximum number of digits before the decimal point. If the value passed is negative then it is replaced by 0. Regardless of this setting, no more than 309 digits will be used.
value | the new maximum number of integer numerals for display. |
---|
Sets the minimum number of digits after the decimal point. If the value passed is negative then it is replaced by 0. Regardless of this setting, no more than 340 digits will be used.
value | the minimum number of fraction digits. |
---|
Sets the minimum number of digits before the decimal point. If the value passed is negative then it is replaced by 0. Regardless of this setting, no more than 309 digits will be used.
value | the minimum number of integer digits. |
---|
Sets the multiplier which is applied to the number before formatting or after parsing. The multiplier meant for tasks like parsing percentages. For example, given a multiplier of 100, 1.23 would be formatted as "123" and "123" would be parsed as 1.23.
Sets the prefix which is formatted or parsed before a negative number.
Sets the suffix which is formatted or parsed after a negative number.
Sets the behavior of the parse method. If set to true
then all
the returned objects will be of type BigDecimal
.
newValue | true if all the returned objects should be of type
BigDecimal ; false otherwise.
|
---|
Sets the flag that indicates whether numbers will be parsed as integers.
When this decimal format is used for parsing and this value is set to
true
, then the resulting numbers will be of type
java.lang.Integer
. Special cases are NaN, positive and negative
infinity, which are still returned as java.lang.Double
.
value | true that the resulting numbers of parse operations
will be of type java.lang.Integer except for the
special cases described above.
|
---|
Sets the prefix which is formatted or parsed before a positive number.
Sets the suffix which is formatted or parsed after a positive number.
Sets the RoundingMode
used by this NumberFormat
.
Returns the pattern of this decimal format using localized pattern characters.
Returns the pattern of this decimal format using non-localized pattern characters.
Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:
getClass().getName() + '@' + Integer.toHexString(hashCode())
See Writing a useful
toString
method
if you intend implementing your own toString
method.