java.text
Class DecimalFormat

java.lang.Object
  extended by java.text.Format
      extended by java.text.NumberFormat
          extended by java.text.DecimalFormat
All Implemented Interfaces:
Serializable, Cloneable

public class DecimalFormat
extends NumberFormat

This class is a concrete implementation of NumberFormat used to format decimal numbers. The class can format numbers given a specific locale. Generally, to get an instance of DecimalFormat you should call the factory methods in the NumberFormat base class.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.text.NumberFormat
NumberFormat.Field
 
Field Summary
 
Fields inherited from class java.text.NumberFormat
FRACTION_FIELD, INTEGER_FIELD
 
Constructor Summary
DecimalFormat()
          Constructs a DecimalFormat which uses the default pattern and symbols.
DecimalFormat(String pattern)
          Constructs a DecimalFormat which uses the given pattern and the default symbols for formatting and parsing.
DecimalFormat(String pattern, DecimalFormatSymbols symbols)
          Constructs a DecimalFormat using the given pattern and formatting symbols.
 
Method Summary
 void applyLocalizedPattern(String pattern)
          Apply the given localized patern to the current DecimalFormat object.
 void applyPattern(String pattern)
          Apply the given localized pattern to the current DecimalFormat object.
 Object clone()
          Creates a copy of this object.
 boolean equals(Object obj)
          Tests this instance for equality with an arbitrary object.
 StringBuffer format(double number, StringBuffer dest, FieldPosition fieldPos)
          Produce a formatted String representation of this double.
 StringBuffer format(long number, StringBuffer dest, FieldPosition fieldPos)
          Produce a formatted String representation of this long.
 StringBuffer format(Object obj, StringBuffer sbuf, FieldPosition pos)
          Produce a formatted String representation of this object.
 AttributedCharacterIterator formatToCharacterIterator(Object value)
          Return an AttributedCharacterIterator as a result of the formatting of the passed Object.
 Currency getCurrency()
          Returns the currency corresponding to the currency symbol stored in the instance of DecimalFormatSymbols used by this DecimalFormat.
 DecimalFormatSymbols getDecimalFormatSymbols()
          Returns a copy of the symbols used by this instance.
 int getGroupingSize()
          Gets the interval used between a grouping separator and the next.
 int getMultiplier()
          Gets the multiplier used in percent and similar formats.
 String getNegativePrefix()
          Gets the negative prefix.
 String getNegativeSuffix()
          Gets the negative suffix.
 String getPositivePrefix()
          Gets the positive prefix.
 String getPositiveSuffix()
          Gets the positive suffix.
 int hashCode()
          Returns a hash code for this object.
 boolean isDecimalSeparatorAlwaysShown()
           
 boolean isParseBigDecimal()
          Returns true if parse(java.lang.String, java.text.ParsePosition) returns a BigDecimal, false otherwise.
 Number parse(String str, ParsePosition pos)
          This method parses the specified string into a Number.
 void setCurrency(Currency currency)
          Sets the Currency on the DecimalFormatSymbols used, which also sets the currency symbols on those symbols.
 void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
          Sets the symbols used by this instance.
 void setDecimalSeparatorAlwaysShown(boolean newValue)
          Define if the decimal separator should be always visible or only visible when needed.
 void setGroupingSize(int groupSize)
          Sets the number of digits used to group portions of the integer part of the number.
 void setMaximumFractionDigits(int newValue)
          Sets the maximum number of digits allowed in the fraction portion of a number to the specified value.
 void setMaximumIntegerDigits(int newValue)
          Sets the maximum number of digits allowed in the integer portion of a number to the specified value.
 void setMinimumFractionDigits(int newValue)
          Sets the minimum number of digits allowed in the fraction portion of a number to the specified value.
 void setMinimumIntegerDigits(int newValue)
          Sets the minimum number of digits allowed in the integer portion of a number to the specified value.
 void setMultiplier(int newValue)
          Sets the multiplier for use in percent and similar formats.
 void setNegativePrefix(String newValue)
          Sets the negative prefix.
 void setNegativeSuffix(String newValue)
          Sets the negative suffix.
 void setParseBigDecimal(boolean newValue)
          Define if parse(java.lang.String, java.text.ParsePosition) should return a BigDecimal or not.
 void setPositivePrefix(String newValue)
          Sets the positive prefix.
 void setPositiveSuffix(String newValue)
          Sets the new positive suffix.
 String toLocalizedPattern()
          This method returns a string with the formatting pattern being used by this object.
 String toPattern()
          This method returns a string with the formatting pattern being used by this object.
 
Methods inherited from class java.text.NumberFormat
format, format, getAvailableLocales, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, isGroupingUsed, isParseIntegerOnly, parse, parseObject, setGroupingUsed, setParseIntegerOnly
 
Methods inherited from class java.text.Format
format, parseObject
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DecimalFormat

public DecimalFormat()
Constructs a DecimalFormat which uses the default pattern and symbols.


DecimalFormat

public DecimalFormat(String pattern)
Constructs a DecimalFormat which uses the given pattern and the default symbols for formatting and parsing.

Parameters:
pattern - the non-localized pattern to use.
Throws:
NullPointerException - if any argument is null.
IllegalArgumentException - if the pattern is invalid.

DecimalFormat

public DecimalFormat(String pattern,
                     DecimalFormatSymbols symbols)
Constructs a DecimalFormat using the given pattern and formatting symbols. This construction method is used to give complete control over the formatting process.

Parameters:
pattern - the non-localized pattern to use.
symbols - the set of symbols used for parsing and formatting.
Throws:
NullPointerException - if any argument is null.
IllegalArgumentException - if the pattern is invalid.
Method Detail

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)
Apply the given localized patern to the current DecimalFormat object.

Parameters:
pattern - The localized pattern to apply.
Throws:
IllegalArgumentException - if the given pattern is invalid.
NullPointerException - if the input pattern is null.

applyPattern

public void applyPattern(String pattern)
Apply the given localized pattern to the current DecimalFormat object.

Parameters:
pattern - The localized pattern to apply.
Throws:
IllegalArgumentException - if the given pattern is invalid.
NullPointerException - if the input pattern is null.

clone

public Object clone()
Description copied from class: Format
Creates a copy of this object.

Overrides:
clone in class Format
Returns:
The copied Object.
See Also:
Cloneable

equals

public boolean equals(Object obj)
Tests this instance for equality with an arbitrary object. This method returns true if:

Overrides:
equals in class NumberFormat
Parameters:
obj - the object (null permitted).
Returns:
A boolean.
See Also:
Object.hashCode()

hashCode

public int hashCode()
Returns a hash code for this object.

Overrides:
hashCode in class NumberFormat
Returns:
A hash code.
See Also:
Object.equals(Object), System.identityHashCode(Object)

format

public final StringBuffer format(Object obj,
                                 StringBuffer sbuf,
                                 FieldPosition pos)
Produce a formatted String representation of this object. The passed object must be of type number.

Overrides:
format in class NumberFormat
Parameters:
obj - The Number to format.
sbuf - The destination String; text will be appended to this String.
pos - If used on input can be used to define an alignment field. If used on output defines the offsets of the alignment field.
Returns:
The String representation of this long.

format

public StringBuffer format(double number,
                           StringBuffer dest,
                           FieldPosition fieldPos)
Produce a formatted String representation of this double.

Specified by:
format in class NumberFormat
Parameters:
number - The double to format.
dest - The destination String; text will be appended to this String.
fieldPos - If used on input can be used to define an alignment field. If used on output defines the offsets of the alignment field.
Returns:
The String representation of this long.
Throws:
NullPointerException - if dest or fieldPos are null

format

public StringBuffer format(long number,
                           StringBuffer dest,
                           FieldPosition fieldPos)
Produce a formatted String representation of this long.

Specified by:
format in class NumberFormat
Parameters:
number - The long to format.
dest - The destination String; text will be appended to this String.
fieldPos - If used on input can be used to define an alignment field. If used on output defines the offsets of the alignment field.
Returns:
The String representation of this long.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object value)
Return an AttributedCharacterIterator as a result of the formatting of the passed Object.

Overrides:
formatToCharacterIterator in class Format
Returns:
An AttributedCharacterIterator.
Throws:
NullPointerException - if value is null.
IllegalArgumentException - if value is not an instance of Number.

getCurrency

public Currency getCurrency()
Returns the currency corresponding to the currency symbol stored in the instance of DecimalFormatSymbols used by this DecimalFormat.

Overrides:
getCurrency in class NumberFormat
Returns:
A new instance of Currency if the currency code matches a known one, null otherwise.

getDecimalFormatSymbols

public DecimalFormatSymbols getDecimalFormatSymbols()
Returns a copy of the symbols used by this instance.

Returns:
A copy of the symbols.

getGroupingSize

public int getGroupingSize()
Gets the interval used between a grouping separator and the next. For example, a grouping size of 3 means that the number 1234 is formatted as 1,234. The actual character used as grouping separator depends on the locale and is defined by DecimalFormatSymbols.getDecimalSeparator()

Returns:
The interval used between a grouping separator and the next.

getMultiplier

public int getMultiplier()
Gets the multiplier used in percent and similar formats.

Returns:
The multiplier used in percent and similar formats.

getNegativePrefix

public String getNegativePrefix()
Gets the negative prefix.

Returns:
The negative prefix.

getNegativeSuffix

public String getNegativeSuffix()
Gets the negative suffix.

Returns:
The negative suffix.

getPositivePrefix

public String getPositivePrefix()
Gets the positive prefix.

Returns:
The positive prefix.

getPositiveSuffix

public String getPositiveSuffix()
Gets the positive suffix.

Returns:
The positive suffix.

isDecimalSeparatorAlwaysShown

public boolean isDecimalSeparatorAlwaysShown()

setParseBigDecimal

public void setParseBigDecimal(boolean newValue)
Define if parse(java.lang.String, java.text.ParsePosition) should return a BigDecimal or not.

Parameters:
newValue -

isParseBigDecimal

public boolean isParseBigDecimal()
Returns true if parse(java.lang.String, java.text.ParsePosition) returns a BigDecimal, false otherwise. The default return value for this method is false.

Returns:
true if the parse method returns a BigDecimal, false otherwise.
Since:
1.5
See Also:
setParseBigDecimal(boolean)

parse

public Number parse(String str,
                    ParsePosition pos)
This method parses the specified string into a Number. The parsing starts at pos, which is updated as the parser consume characters in the passed string. On error, the Position object index is not updated, while error position is set appropriately, an null is returned.

Specified by:
parse in class NumberFormat
Parameters:
str - The string to parse.
pos - The desired ParsePosition.
Returns:
The parsed Number

setCurrency

public void setCurrency(Currency currency)
Sets the Currency on the DecimalFormatSymbols used, which also sets the currency symbols on those symbols.

Overrides:
setCurrency in class NumberFormat
Parameters:
currency - The new Currency on the DecimalFormatSymbols.

setDecimalFormatSymbols

public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
Sets the symbols used by this instance. This method makes a copy of the supplied symbols.

Parameters:
newSymbols - the symbols (null not permitted).

setDecimalSeparatorAlwaysShown

public void setDecimalSeparatorAlwaysShown(boolean newValue)
Define if the decimal separator should be always visible or only visible when needed. This method as effect only on integer values. Pass true if you want the decimal separator to be always shown, false otherwise.

Parameters:
newValue - true if you want the decimal separator to be always shown, false otherwise.

setGroupingSize

public void setGroupingSize(int groupSize)
Sets the number of digits used to group portions of the integer part of the number. For example, the number 123456, with a grouping size of 3, is rendered 123,456.

Parameters:
groupSize - The number of digits used while grouping portions of the integer part of a number.

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int newValue)
Sets the maximum number of digits allowed in the integer portion of a number to the specified value. The new value will be the choosen as the minimum between newvalue and 309. Any value below zero will be replaced by zero.

Overrides:
setMaximumIntegerDigits in class NumberFormat
Parameters:
newValue - The new maximum integer digits value.

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int newValue)
Sets the minimum number of digits allowed in the integer portion of a number to the specified value. The new value will be the choosen as the minimum between newvalue and 309. Any value below zero will be replaced by zero.

Overrides:
setMinimumIntegerDigits in class NumberFormat
Parameters:
newValue - The new minimum integer digits value.

setMaximumFractionDigits

public void setMaximumFractionDigits(int newValue)
Sets the maximum number of digits allowed in the fraction portion of a number to the specified value. The new value will be the choosen as the minimum between newvalue and 309. Any value below zero will be replaced by zero.

Overrides:
setMaximumFractionDigits in class NumberFormat
Parameters:
newValue - The new maximum fraction digits value.

setMinimumFractionDigits

public void setMinimumFractionDigits(int newValue)
Sets the minimum number of digits allowed in the fraction portion of a number to the specified value. The new value will be the choosen as the minimum between newvalue and 309. Any value below zero will be replaced by zero.

Overrides:
setMinimumFractionDigits in class NumberFormat
Parameters:
newValue - The new minimum fraction digits value.

setMultiplier

public void setMultiplier(int newValue)
Sets the multiplier for use in percent and similar formats. For example, for percent set the multiplier to 100, for permille, set the miltiplier to 1000.

Parameters:
newValue - the new value for multiplier.

setNegativePrefix

public void setNegativePrefix(String newValue)
Sets the negative prefix.

Parameters:
newValue - The new negative prefix.

setNegativeSuffix

public void setNegativeSuffix(String newValue)
Sets the negative suffix.

Parameters:
newValue - The new negative suffix.

setPositivePrefix

public void setPositivePrefix(String newValue)
Sets the positive prefix.

Parameters:
newValue - The new positive prefix.

setPositiveSuffix

public void setPositiveSuffix(String newValue)
Sets the new positive suffix.

Parameters:
newValue - The new positive suffix.

toLocalizedPattern

public String toLocalizedPattern()
This method returns a string with the formatting pattern being used by this object. The string is localized.

Returns:
A localized String with the formatting pattern.
See Also:
toPattern()

toPattern

public String toPattern()
This method returns a string with the formatting pattern being used by this object. The string is not localized.

Returns:
A String with the formatting pattern.
See Also:
toLocalizedPattern()