java.text

Class DecimalFormat

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.

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()
boolean	equals(Object obj) Tests this instance for equality with an arbitrary object.
StringBuffer	format(Object obj, StringBuffer sbuf, FieldPosition pos) Produce a formatted {@link String} representation of this object.
StringBuffer	format(double number, StringBuffer dest, FieldPosition fieldPos) Produce a formatted {@link String} representation of this double.
StringBuffer	format(long number, StringBuffer dest, FieldPosition fieldPos) Produce a formatted {@link String} representation of this long.
AttributedCharacterIterator	formatToCharacterIterator(Object value) Return an `AttributedCharacterIterator` as a result of the formatting of the passed {@link 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 {@link 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.

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

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;

Parameters: obj the object (null permitted).

Returns: A boolean.

format

public StringBuffer format(Object obj, StringBuffer sbuf, FieldPosition pos)

Produce a formatted {@link String} representation of this object. The passed object must be of type number.

Parameters: obj The {@link 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 {@link String} representation of this double.

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 {@link String} representation of this long.

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 {@link Object}.

Returns: An {@link AttributedCharacterIterator}.

Throws: NullPointerException if value is null. IllegalArgumentException if value is not an instance of {@link Number}.

getCurrency

public Currency getCurrency()

Returns the currency corresponding to the currency symbol stored in the instance of DecimalFormatSymbols used by this DecimalFormat.

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 {@link 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.

hashCode

public int hashCode()

Returns a hash code for this object.

Returns: A hash code.

isDecimalSeparatorAlwaysShown

public boolean isDecimalSeparatorAlwaysShown()

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 {@link BigDecimal}, false otherwise.

Since: 1.5

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.

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.

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.

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.

Parameters: newValue The new maximum fraction digits value.

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.

Parameters: newValue The new maximum integer 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.

Parameters: newValue The new minimum fraction 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.

Parameters: newValue The new minimum integer 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.