DecimalFormat is 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, and Indic digits. It also
supports different kinds of numbers, including integers (123), fixed-point
numbers (123.4), scientific notation (1.23E4), percentages (12%), and
currency amounts ($123). All of these can be localized.
To obtain a NumberFormat for a specific locale, including the
default locale, call one of NumberFormat's factory methods, such
as getInstance(). In general, do not call the
DecimalFormat constructors directly, 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 comprises a pattern and a set of
symbols. The pattern may be set directly using
applyPattern(), or indirectly using the API methods. The
symbols are stored in a DecimalFormatSymbols object. When using
the NumberFormat factory methods, the pattern and symbols are
read from localized ResourceBundles.
DecimalFormat patterns have the following syntax:
Pattern:
PositivePattern
PositivePattern ; NegativePattern
PositivePattern:
Prefixopt Number Suffixopt
NegativePattern:
Prefixopt Number Suffixopt
Prefix:
any Unicode characters except \uFFFE, \uFFFF, and special characters
Suffix:
any Unicode characters except \uFFFE, \uFFFF, and special characters
Number:
Integer Exponentopt
Integer . Fraction Exponentopt
Integer:
MinimumInteger
#
# Integer
# , Integer
MinimumInteger:
0
0 MinimumInteger
0 , MinimumInteger
Fraction:
MinimumFractionopt OptionalFractionopt
MinimumFraction:
0 MinimumFractionopt
OptionalFraction:
# OptionalFractionopt
Exponent:
E MinimumExponent
MinimumExponent:
0 MinimumExponentopt
A DecimalFormat pattern contains a positive and negative
subpattern, for example, "#,##0.00;(#,##0.00)". Each
subpattern has a prefix, numeric part, and suffix. The negative subpattern
is optional; if absent, then the positive subpattern prefixed with the
localized minus sign ('-' in most locales) is used as the
negative 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 all the same as the positive
pattern. That means that "#,##0.0#;(#)" produces precisely
the same behavior 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 DecimalFormat.parse() to be able
to distinguish positive from negative values. (If they are identical, then
DecimalFormat will behave as if no negative subpattern was
specified.) Another example is that the decimal separator and thousands
separator should be distinct characters, or parsing will be impossible.
The grouping separator is commonly used for thousands, but in some
countries it separates ten-thousands. The grouping size is a constant number
of digits between the grouping characters, such as 3 for 100,000,000 or 4 for
1,0000,0000. If you supply a pattern with multiple grouping characters, the
interval between the last one and the end of the integer is the one that is
used. So "#,##,###,####" == "######,####" ==
"##,####,####".
Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. They must be quoted, unless noted otherwise, if they are to appear in the prefix or suffix as literals.
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 0Number Yes Digit #Number Yes Digit, zero shows as absent .Number Yes Decimal separator or monetary decimal separator -Number Yes Minus sign ,Number Yes Grouping separator ENumber Yes Separates mantissa and exponent in scientific notation. Need not 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 \u2030Prefix or suffix Yes Multiply by 1000 and show as per mille value ¤(\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".
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 10^3. The
mantissa is often in the range 1.0 <= x < 10.0, but it need not be.
DecimalFormat can be instructed to format and parse scientific
notation only via a pattern; there is currently no factory method
that creates a scientific notation format. 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".
"0.###E0 m/s".
"##0.#####E0". Using this pattern, the number 12345
formats to "12.345E3", and 123456 formats to
"123.456E3".
"00.###E0" yields
"12.3E-4".
"##0.##E0" is "12.3E3". To show all digits, set
the significant digits count to zero. The number of significant digits
does not affect parsing.
DecimalFormat uses half-even rounding (see
ROUND_HALF_EVEN
) for
formatting.
DecimalFormat uses the ten consecutive
characters starting with the localized zero digit defined in the
DecimalFormatSymbols object as digits. For parsing, these
digits as well as all Unicode decimal digits, as defined by
Character.digit
, are recognized.
NaN is formatted 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 formatted as a single character, typically
\u221E, with the positive or negative prefixes and suffixes
applied. The infinity character is determined by the
DecimalFormatSymbols object.
Negative zero ("-0") parses to
BigDecimal(0) if isParseBigDecimal() is
true,
Long(0) if isParseBigDecimal() is false
and isParseIntegerOnly() is true,
Double(-0.0) if both isParseBigDecimal()
and isParseIntegerOnly() are false.
Decimal formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.
// Print out a number using the localized number, integer, currency,
// and percent format for each locale
Locale[] locales = NumberFormat.getAvailableLocales();
double myNumber = -1234.56;
NumberFormat form;
for (int j=0; j<4; ++j) {
System.out.println("FORMAT");
for (int i = 0; i < locales.length; ++i) {
if (locales[i].getCountry().length() == 0) {
continue; // Skip language-only locales
}
System.out.print(locales[i].getDisplayName());
switch (j) {
case 0:
form = NumberFormat.getInstance(locales[i]); break;
case 1:
form = NumberFormat.getIntegerInstance(locales[i]); break;
case 2:
form = NumberFormat.getCurrencyInstance(locales[i]); break;
default:
form = NumberFormat.getPercentInstance(locales[i]); break;
}
if (form instanceof DecimalFormat) {
System.out.print(": " + ((DecimalFormat) form).toPattern());
}
System.out.print(" -> " + form.format(myNumber));
try {
System.out.println(" -> " + form.parse(form.format(myNumber)));
} catch (ParseException e) {}
}
}
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance. If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method.
There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon
Example "#,#00.0#" -> 1,234.56
This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.
Example: "#,#00.0#;(#,#00.0#)" for negatives in
parentheses.
In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.
There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon
Example "#,#00.0#" -> 1,234.56
This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.
Example: "#,#00.0#;(#,#00.0#)" for negatives in
parentheses.
In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.
format
(obj,
new StringBuffer(), new FieldPosition(0)).toString();
This implementation uses the maximum precision permitted.
AttributedCharacterIterator.
You can use the returned AttributedCharacterIterator
to build the resulting String, as well as to determine information
about the resulting String.
Each attribute key of the AttributedCharacterIterator will be of type
NumberFormat.Field, with the attribute value being the
same as the attribute key.
get*Instance methods of this class can return
localized instances.
The array returned must contain at least a Locale
instance equal to Locale.US
.BigInteger and
BigDecimal objects, the lower of the return value and
340 is used.BigInteger and
BigDecimal objects, the lower of the return value and
309 is used.BigInteger and
BigDecimal objects, the lower of the return value and
340 is used.BigInteger and
BigDecimal objects, the lower of the return value and
309 is used.Examples: -123, ($123) (with negative suffix), sFr-123
Examples: -123%, ($123) (with positive suffixes)
Examples: +123, $123, sFr123
Example: 123%
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
Number.
The method attempts to parse text starting at the index given by
pos.
If parsing succeeds, then the index of pos is updated
to the index after the last character used (parsing does not necessarily
use all characters up to the end of the string), and the parsed
number is returned. The updated pos can be used to
indicate the starting point for the next call to this method.
If an error occurs, then the index of pos is not
changed, the error index of pos is set to the index of
the character where the error occurred, and null is returned.
The subclass returned depends on the value of #isParseBigDecimal as well as on the string being parsed.
isParseBigDecimal() is false (the default),
most integer values are returned as Long
objects, no matter how they are written: "17" and
"17.000" both parse to Long(17).
Values that cannot fit into a Long are returned as
Doubles. This includes values with a fractional part,
infinite values, NaN, and the value -0.0.
DecimalFormat does not decide whether to
return a Double or a Long based on the
presence of a decimal separator in the source string. Doing so
would prevent integers that overflow the mantissa of a double,
such as "-9,223,372,036,854,775,808.00", from being
parsed accurately.
Callers may use the Number methods
doubleValue, longValue, etc., to obtain
the type they want.
isParseBigDecimal() is true, values are returned
as BigDecimal objects. The values are the ones
constructed by
for corresponding strings in locale-independent format. The
special cases negative and positive infinity and NaN are returned
as Double instances holding the values of the
corresponding Double constants.
DecimalFormat parses all Unicode characters that represent
decimal digits, as defined by Character.digit(). In
addition, DecimalFormat also recognizes as digits the ten
consecutive characters starting with the localized zero digit defined in
the DecimalFormatSymbols object.
Number.
The method attempts to parse text starting at the index given by
pos.
If parsing succeeds, then the index of pos is updated
to the index after the last character used (parsing does not necessarily
use all characters up to the end of the string), and the parsed
number is returned. The updated pos can be used to
indicate the starting point for the next call to this method.
If an error occurs, then the index of pos is not
changed, the error index of pos is set to the index of
the character where the error occurred, and null is returned.
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
BigInteger and
BigDecimal objects, the lower of newValue and
340 is used. Negative input values are replaced with 0.BigInteger and
BigDecimal objects, the lower of newValue and
309 is used. Negative input values are replaced with 0.BigInteger and
BigDecimal objects, the lower of newValue and
340 is used. Negative input values are replaced with 0.BigInteger and
BigDecimal objects, the lower of newValue and
309 is used. Negative input values are replaced with 0.Example: with multiplier 100, 1.23 is formatted as "123", and "123" is parsed into 1.23.
Examples: -123, ($123) (with negative suffix), sFr-123
Examples: 123%
Examples: +123, $123, sFr123
Example: 123%
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.