All Packages Class Hierarchy This Package Previous Next Index
Object
|
+----Format
|
+----NumberFormat
|
+----java.text.DecimalFormat
DecimalFormat is a concrete subclass of NumberFormat
for formatting decimal numbers. This class allows for a variety
of parameters, and localization to Western, Arabic, or Indic numbers.
Normally, you get the proper NumberFormat for a specific
locale (including the default locale) using one of NumberFormat's
factory methods such as getInstance. You may then modify it
from there (after testing to make sure it is a DecimalFormat,
of course!)
Either the prefixes or the suffixes must be different for the parse to distinguish positive from negative. Parsing will be unreliable if the digits, thousands or decimal separators are the same, or if any of them occur in the prefixes or suffixes.
Special cases:
NaN is formatted as a single character, typically
\\uFFFD.
+/-Infinity is formatted as a single character, typically \\u221E,
plus the positive and negative pre/suffixes.
Note: this class is designed for common users; for very
large or small numbers, use a format that can express exponential values.
Example:
// normally we would have a GUI with a menu for this
Locale[] locales = NumberFormat.getAvailableLocales();
double myNumber = -1234.56;
NumberFormat form;
// just for fun, we print out a number with the locale number, currency
// and percent format for each locale we can.
for (int j = 0; j < 3; ++j) {
System.out.println("FORMAT");
for (int i = 0; i < locales.length; ++i) {
if (locales[i].getCountry().length() == 0) {
// skip language-only
continue;
}
System.out.print(locales[i].getDisplayName());
switch (j) {
default:
form = NumberFormat.getInstance(locales[i]); break;
case 1:
form = NumberFormat.getCurrencyInstance(locales[i]); break;
case 0:
form = NumberFormat.getPercentInstance(locales[i]); break;
}
try {
System.out.print(": " + ((DecimalFormat)form).toPattern()
+ " -> " + form.format(myNumber));
} catch (IllegalArgumentException iae) { }
try {
System.out.println(" -> " + form.parse(form.format(myNumber)));
} catch (ParseException pe) { }
}
}
The following shows the structure of the pattern.
pattern := subpattern{;subpattern}
subpattern := {prefix}integer{.fraction}{suffix}
prefix := '\\u0000'..'\\uFFFD' - specialCharacters
suffix := '\\u0000'..'\\uFFFD' - specialCharacters
integer := '#'* '0'* '0'
fraction := '0'* '#'*
Notation:
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
The first subpattern is for positive numbers. The second (optional)
subpattern is for negative numbers. (In both cases, ',' can occur
inside the integer portion--it is just too messy to indicate in BNF.)
Here are the special characters used in the parts of the subpattern, with notes on their usage.
Symbol Meaning
0 a digit
# a digit, zero shows as absent
. placeholder for decimal separator
, placeholder for grouping separator.
; 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.
Notes
If there is no explicit negative subpattern, - is prefixed to the positive form. That is, "0.00" alone is equivalent to "0.00;-0.00".
Illegal patterns, such as "#.#.#" or mixing '_' and '*' in the
same pattern, will cause an IllegalArgumentException to be
thrown. From the message of IllegalArgumentException, you can
find the place in the string where the error occurred.
The grouping separator is commonly used for thousands, but in some countries for ten-thousands. The interval is a constant number of digits between the grouping characters, such as 100,000,000 or 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 "#,##,###,####" == "######,####" == "##,####,####".
When calling DecimalFormat.parse(String, ParsePosition) and parsing fails, a null object will be returned. The unchanged parse position also reflects that an error has occurred during parsing. When calling the convenient method DecimalFormat.parse(String) and parsing fails, a ParseException will be thrown.
This class only handles localized digits where the 10 digits are contiguous in Unicode, from 0 to 9. Other digits sets (such as superscripts) would need a different subclass.
java.text.DecimalFormat()
java.text.DecimalFormat(String)
java.text.DecimalFormat(String, DecimalFormatSymbols)
applyLocalizedPattern(String)
applyPattern(String)
clone()
equals(Object)
format(double, StringBuffer, FieldPosition)
format(long, StringBuffer, FieldPosition)
getDecimalFormatSymbols()
getGroupingSize()
getMultiplier()
getNegativePrefix()
getNegativeSuffix()
getPositivePrefix()
getPositiveSuffix()
hashCode()
isDecimalSeparatorAlwaysShown()
parse(String, ParsePosition)
setDecimalFormatSymbols(DecimalFormatSymbols)
setDecimalSeparatorAlwaysShown(boolean)
setGroupingSize(int)
setMultiplier(int)
setNegativePrefix(String)
setNegativeSuffix(String)
setPositivePrefix(String)
setPositiveSuffix(String)
toLocalizedPattern()
toPattern()
DecimalFormat
public DecimalFormat()
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.
DecimalFormat
public DecimalFormat(String pattern)
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.
DecimalFormat
public DecimalFormat(String pattern,
DecimalFormatSymbols symbols)
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.
applyLocalizedPattern
public void applyLocalizedPattern(String 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 parantheses.
In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.
applyPattern
public void applyPattern(String 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 parantheses.
In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.
clone
public java.lang.Object clone()
equals
public boolean equals(Object obj)
format
public java.lang.StringBuffer format(double number,
StringBuffer result,
FieldPosition fieldPosition)
format
public java.lang.StringBuffer format(long number,
StringBuffer result,
FieldPosition fieldPosition)
getDecimalFormatSymbols
public java.text.DecimalFormatSymbols getDecimalFormatSymbols()
getGroupingSize
public int getGroupingSize()
getMultiplier
public int getMultiplier()
Examples: with 100, 1.23 -> "123", and "123" -> 1.23
getNegativePrefix
public java.lang.String getNegativePrefix()
Examples: -123, ($123) (with negative suffix), sFr-123
getNegativeSuffix
public java.lang.String getNegativeSuffix()
Examples: -123%, ($123) (with positive suffixes)
getPositivePrefix
public java.lang.String getPositivePrefix()
Examples: +123, $123, sFr123
getPositiveSuffix
public java.lang.String getPositiveSuffix()
Example: 123%
hashCode
public int hashCode()
isDecimalSeparatorAlwaysShown
public boolean isDecimalSeparatorAlwaysShown()
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
parse
public java.lang.Number parse(String text,
ParsePosition parsePosition)
setDecimalFormatSymbols
public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
setDecimalSeparatorAlwaysShown
public void setDecimalSeparatorAlwaysShown(boolean newValue)
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
setGroupingSize
public void setGroupingSize(int newValue)
setMultiplier
public void setMultiplier(int newValue)
Examples: with 100, 1.23 -> "123", and "123" -> 1.23
setNegativePrefix
public void setNegativePrefix(String newValue)
Examples: -123, ($123) (with negative suffix), sFr-123
setNegativeSuffix
public void setNegativeSuffix(String newValue)
Examples: 123%
setPositivePrefix
public void setPositivePrefix(String newValue)
Examples: +123, $123, sFr123
setPositiveSuffix
public void setPositiveSuffix(String newValue)
Example: 123%
toLocalizedPattern
public java.lang.String toLocalizedPattern()
toPattern
public java.lang.String toPattern()
All Packages Class Hierarchy This Package Previous Next Index