All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.text.DecimalFormat 

java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.NumberFormat
                   |
                   +----java.text.DecimalFormat
public class DecimalFormat
extends NumberFormat
Concrete class for formatting decimal numbers, allowing 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). 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.getDefault(locales[i]); break;
         case 1:
             form = NumberFormat.getDefaultCurrency(locales[i]); break;
         case 0:
             form = NumberFormat.getDefaultPercent(locales[i]); break;
         }
         System.out.print(": " + ((DecimalFormat)form).getPattern()
                          + " ->  + form.format(myNumber));
         System.out.println(" -> " + form.parse(form.format(myNumber)));
     }
 }
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 used 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 a star
 _      a digit, zero shows as a space
 #      a digit, zero shows as absent
 .      placeholder for decimal separator
 ,      placeholder for grouping delimiter.
 ;      separates formats.                     
 -      default negative prefix.               
 %      divide by 100 and show as percentage
 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 formats, such as "#.#.#" or mixing '_' and '*' in the same format, will cause an FormatException to be thrown. From that FormatException, you can find the place in the string where the error occurred.

The grouping delimiter 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 "#,##,###,####" == "######,####" == "##,####,####".

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.

See Also:
Format, NumberFormat, ChoiceFormat

Constructor Index

o DecimalFormat()
Create a decimal format from default pattern and data.
o DecimalFormat(String, NumberFormatData)
Create a decimal format from a pattern and data.

Method Index

o clone()
Standard override; no change in semantics.
o equals(Object)
Compares the equality of two decimal format objects.
o format(double, StringBuffer, FormatStatus)
Specialization of format.
o format(long, StringBuffer, FormatStatus)
Specialization of format.
o getFactor()
Get the factor for use in percent, permill, etc.
o getNegativePrefix()
Get the negative prefix

Examples: -123, ($123) (with negative suffix), sFr-123

o getNegativeSuffix()
Get the negative suffix

Examples: -123%, ($123) (with positive suffixes)

o getNumberFormatData()
Gets the number format data, which is generally not changed by the programmer or user.
o getPattern(boolean)
Gets the pattern for a number.
o getPositivePrefix()
Get the positive prefix

Examples: +123, $123, sFr123

o getPositiveSuffix()
Get the positive suffix

Example: 123%

o getThousandsInterval()
Get the thousands interval.
o hashCode()
Generates the hash code for the decimal format object
o parse(String, ParseStatus)
Returns a Long if possible (e.g.
o setFactor(int)
Set the factor for use in percent, permill, etc.
o setNegativePrefix(String)
Set the negative prefix

Examples: -123, ($123) (with negative suffix), sFr-123

o setNegativeSuffix(String)
Set the positive suffix

Examples: 123%

o setNumberFormatData(NumberFormatData)
Sets the number format data, which is generally not changed by the programmer or user.
o setPattern(String, boolean)
Sets the pattern for a number.
o setPositivePrefix(String)
Set the positive prefix

Examples: +123, $123, sFr123

o setPositiveSuffix(String)
Set the positive suffix

Example: 123%

o setThousandsInterval(int)
Set the thousands interval.

Constructors

o DecimalFormat 
  public DecimalFormat(String pattern,
                       NumberFormatData data) throws FormatException
Create a decimal format from a pattern and data. Generally you will use NumberFormat.getDefault() instead.

Throws: FormatException
if the pattern is incorrect, '*', '_' and '0' cannot be specified at the same time.
Throws: FormatException
if
See Also:
setPattern, setNumberFormatData
o DecimalFormat 
  public DecimalFormat()
Create a decimal format from default pattern and data. Generally you will use NumberFormat.getDefault() instead.

See Also:
setPattern, setNumberFormatData

Methods

o format 
  public StringBuffer format(double number,
                             StringBuffer result,
                             FormatStatus status)
Specialization of format.

Overrides:
format in class NumberFormat
o format 
  public StringBuffer format(long number,
                             StringBuffer result,
                             FormatStatus status)
Specialization of format.

Overrides:
format in class NumberFormat
o parse 
  public Number parse(String text,
                      ParseStatus status)
Returns a Long if possible (e.g.

Overrides:
parse in class NumberFormat
o setNumberFormatData 
  public void setNumberFormatData(NumberFormatData newElements)
Sets the number format data, which is generally not changed by the programmer or user.

Parameters:
newElements - desired NumberFormatData
See Also:
NumberFormatData
o getNumberFormatData 
  public NumberFormatData getNumberFormatData()
Gets the number format data, which is generally not changed by the programmer or user.

Returns:
desired NumberFormatData
See Also:
NumberFormatData
o getPositivePrefix 
  public String getPositivePrefix()
Get the positive prefix

Examples: +123, $123, sFr123

o setPositivePrefix 
  public void setPositivePrefix(String newValue)
Set the positive prefix

Examples: +123, $123, sFr123

o getNegativePrefix 
  public String getNegativePrefix()
Get the negative prefix

Examples: -123, ($123) (with negative suffix), sFr-123

o setNegativePrefix 
  public void setNegativePrefix(String newValue)
Set the negative prefix

Examples: -123, ($123) (with negative suffix), sFr-123

o getPositiveSuffix 
  public String getPositiveSuffix()
Get the positive suffix

Example: 123%

o setPositiveSuffix 
  public void setPositiveSuffix(String newValue)
Set the positive suffix

Example: 123%

o getNegativeSuffix 
  public String getNegativeSuffix()
Get the negative suffix

Examples: -123%, ($123) (with positive suffixes)

o setNegativeSuffix 
  public void setNegativeSuffix(String newValue)
Set the positive suffix

Examples: 123%

o getFactor 
  public int getFactor()
Get the factor for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the factor to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "?" and the factor to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23

o setFactor 
  public void setFactor(int newValue)
Set the factor for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the factor to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "?" and the factor to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23

o getThousandsInterval 
  public int getThousandsInterval()
Get the thousands interval. The default for most countries is 3, but some countries use 4.

o setThousandsInterval 
  public void setThousandsInterval(int newValue)
Set the thousands interval. The default for most countries is 3, but some countries use 4.

o clone 
  public synchronized Object clone()
Standard override; no change in semantics.

Overrides:
clone in class NumberFormat
o equals 
  public boolean equals(Object obj)
Compares the equality of two decimal format objects.

Parameters:
obj - the decimal format object to be compared with this.
Returns:
true if the current decimal format object is the same as the decimal format object obj; false otherwise.
Overrides:
equals in class Object
o hashCode 
  public synchronized int hashCode()
Generates the hash code for the decimal format object

Overrides:
hashCode in class Object
o getPattern 
  public String getPattern(boolean localized)
Gets the pattern for a number.

Parameters:
localized - If true, then the pattern is localized to the current locale before being returned. If false, then the pattern is returned unchanged.
See Also:
setPattern
o setPattern 
  public void setPattern(String pattern,
                         boolean localized) throws FormatException
Sets the pattern for a number. 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.

Parameters:
localized - True if the input pattern is localized to the current locale. False if the input pattern is not localized.
Throws: FormatException
if the pattern is incorrect, '*', '_' and '0' cannot be specified at the same time. 
All Packages  Class Hierarchy  This Package  Previous  Next  Index