java.text

Class DecimalFormat

java.lang.Object

java.text.Format

java.text.NumberFormat

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

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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:

• obj is not null;
• obj is an instance of DecimalFormat;
• this instance and obj have the same attributes;

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()