java.text

Class DecimalFormat

Implemented Interfaces:
Cloneable, Serializable

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

Nested classes/interfaces inherited from class java.text.Format

Format.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()
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(Object obj, StringBuffer sbuf, FieldPosition pos)
Produce a formatted String representation of this object.
StringBuffer
format(long number, StringBuffer dest, FieldPosition fieldPos)
Produce a formatted String representation of this long.
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

equals, format, format, format, format, format, getAvailableLocales, getCurrency, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getPercentInstance, getPercentInstance, hashCode, isGroupingUsed, isParseIntegerOnly, parse, parse, parseObject, setCurrency, setGroupingUsed, setMaximumFractionDigits, setMaximumIntegerDigits, setMinimumFractionDigits, setMinimumIntegerDigits, setParseIntegerOnly

Methods inherited from class java.text.Format

clone, format, format, formatToCharacterIterator, parseObject, parseObject

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

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 Details

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()
Overrides:
clone in interface Format

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 interface NumberFormat
Parameters:
obj - the object (null permitted).
Returns:
A boolean.

format

public StringBuffer format(double number,
                           StringBuffer dest,
                           FieldPosition fieldPos)
Produce a formatted String representation of this double.
Overrides:
format in interface 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(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 interface 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(long number,
                           StringBuffer dest,
                           FieldPosition fieldPos)
Produce a formatted String representation of this long.
Overrides:
format in interface 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 interface Format
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 interface 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.

hashCode

public int hashCode()
Returns a hash code for this object.
Overrides:
hashCode in interface NumberFormat
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 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.
Overrides:
parse in interface 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 interface 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.

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 interface NumberFormat
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.
Overrides:
setMaximumIntegerDigits in interface NumberFormat
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.
Overrides:
setMinimumFractionDigits in interface NumberFormat
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.
Overrides:
setMinimumIntegerDigits in interface NumberFormat
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.

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.

setParseBigDecimal

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

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.

DecimalFormat.java -- Formats and parses numbers Copyright (C) 1999, 2000, 2001, 2003, 2004, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.