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)));
     }
 }
Format: {prefix}integer{.decimal}{suffix} 
 prefix  any characters other than '#','0', or other digits.
 suffix  ditto
 integer zero or more '#', followed by 1 or more '0'. ',' can occur inside.
 decimal zero or more '0', followed by zero or more '#'.
Here are the other special characters. 
 Symbol Meaning                                Notes
 0      a digit
 *      a digit, zero shows as a star          Can't mix 0, *, and _ in same format
 _      a digit, zero shows as a space         Can't mix 0, *, and _ in same format
 #      a digit, zero shows as absent
 .      placeholder for decimal separator
 ,      placeholder for grouping delimiter.    Shows the interval to be used.
 ;      separates formats.                     There are two:
                                               positive and negative.
 -      if there is no explicit negative sign,
        - is prefixed                          "0.00" -> "0.00;-0.00"
 %      divide by 100 and show as percentage
 X      any other characters can be used in
        the prefix or suffix

Note : When specifying '0', '*' and '_' in the pattern, '*' takes precedence over '_' and '_' takes precedence over '0'.

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 decimal digit, and a maximum of 2 decimal 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