Chapter 16
The java.text Package

DecimalFormat

Name

DecimalFormat

Synopsis

Class Name:

java.text.DecimalFormat

Superclass:

java.text.NumberFormat

Immediate Subclasses:

None

Interfaces Implemented:

None

Availability:

New as of JDK 1.1

The DecimalFormat class is a concrete subclass of NumberFormat that formats and parses numbers using a formatting pattern. Typically, you do not need to instantiate DecimalFormat yourself. Instead, the factory methods of NumberFormat return instances of DecimalFormat that are appropriate for particular locales.

However, if you need a specialized number format, you can instantiate your own DecimalFormat using a pattern string. You can also modify the formatting pattern of an existing DecimalFormat object using the applyPattern() method. A pattern string has the following form:

positive-pattern[;negative-pattern]

If the negative pattern is omitted, negative numbers are formatted using the positive pattern with a - character prepended to the result. Each pattern has the following form:

[prefix]integer[.fraction][suffix]

The following symbols are significant in the pattern string.

Symbol	Description
`0`	A digit
`#`	A digit where 0 is not shown
`.`	A placeholder for a decimal separator
`,`	A placeholder for a grouping separator
`;`	The format separator
`-`	The default negative prefix
`%`	Divides value by 100 and shows as a percentage

Any characters other than these special characters can appear in the prefix or the suffix. A single quote can be used to escape a special character, if you need to use one of these symbols in a prefix or a suffix.

For example, the pattern string for U.S. currency values is:

$#,##0.00;($#,##0.00)

This indicates that a $ character is prepended to all formatted values. The grouping separator character , is inserted every three digits. Exactly two digits after the decimal place are always shown. Negative values are shown in parentheses. Thus, the value -1234.56 produces output like:

($1,234.56)

Internally, the DecimalFormat class uses a DecimalFormatSymbols object to get the numerical strings that are appropriate for a particular locale. If you want to modify these strings, you can get the DecimalFormatSymbols object by calling getDecimalFormatSymbols().

Class Summary

public class java.text.DecimalFormat extends java.text.NumberFormat {
  // Constructors
  public DecimalFormat();
  public DecimalFormat(String pattern);
  public DecimalFormat(String pattern, DecimalFormatSymbols symbols);
  // Instance Methods
  public void applyLocalizedPattern(String pattern);
  public void applyPattern(String pattern);
  public Object clone();
  public boolean equals(Object obj); 
  public StringBuffer format(double number, StringBuffer result, 
                      FieldPosition fieldPosition); 
  public StringBuffer format(long number, StringBuffer result, 
                      FieldPosition fieldPosition); 
  public DecimalFormatSymbols getDecimalFormatSymbols();
  public int getGroupingSize();
  public int getMultiplier();
  public String getNegativePrefix();
  public String getNegativeSuffix();
  public String getPositivePrefix();
  public String getPositiveSuffix();
  public int hashCode();
  public boolean isDecimalSeparatorAlwaysShown();
  public Number parse(String text, ParsePosition status); 
  public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols);
  public void setDecimalSeparatorAlwaysShown(boolean newValue);
  public void setGroupingSize(int newValue);
  public void setMultiplier(int newValue);
  public void setNegativePrefix(String newValue);
  public void setNegativeSuffix(String newValue);
  public void setPositivePrefix(String newValue);
  public void setPositiveSuffix(String newValue);
  public String toLocalizedPattern();
  public String toPattern();
}

Constructors

DecimalFormat

public DecimalFormat()

Description: This constructor creates a DecimalFormat that uses the default formatting pattern and DecimalFormatSymbols that are appropriate for the default locale.

public DecimalFormat(String pattern)

Parameters

pattern: The pattern string.

Description

This constructor creates a DecimalFormat that uses the given formatting pattern and a DecimalFormatSymbols that is appropriate for the default locale.

public DecimalFormat(String pattern, DecimalFormatSymbols symbols)

Parameters

pattern

The pattern string.

symbols

The DecimalFormatSymbols to use.

Description

This constructor creates a DecimalFormat that uses the given formatting pattern and DecimalFormatSymbols object.

Instance Methods

applyLocalizedPattern

public void applyLocalizedPattern(String pattern)

Parameters

pattern: The pattern string.

Description

This method tells this DecimalFormat to use the given formatting pattern to format and parse numbers. The pattern string is assumed to have been localized to the DecimalFormatSymbols object this DecimalFormat uses.

applyPattern

public void applyPattern(String pattern)

Parameters

pattern: The pattern string.

Description

This method tells this DecimalFormat to use the given formatting pattern to format and parse numbers. The pattern string is localized to the DecimalFormatSymbols object this DecimalFormat uses.

clone

public Object clone()

Returns

A copy of this DecimalFormat.

Overrides

NumberFormat.clone()

Description

This method creates a copy of this DecimalFormat and then returns it.

equals

public boolean equals(Object obj)

Parameters

obj: The object to be compared with this object.

Returns

true if the objects are equal; false if they are not.

Overrides

NumberFormat.equals()

Description

This method returns true if obj is an instance of DecimalFormat and is equivalent to this DecimalFormat.

format

 public StringBuffer format(double number, StringBuffer result, FieldPosition fieldPosition)

Parameters

number

The double value to be formatted.

result

A StringBuffer on which to append the formatted information.

fieldPosition

A number field.

Returns

The given buffer result with the formatted representation of the number appended to it.

Overrides

NumberFormat.format(double, StringBuffer, FieldPosition)

Description

This method formats the given number and appends the result to the given StringBuffer. If fieldPosition refers to one of the number fields, its beginning and ending indices are filled with the beginning and ending positions of the given field in the resulting formatted string.

 public StringBuffer format(long number, StringBuffer result, FieldPosition fieldPosition)

Parameters

number

The long value to be formatted.

result

A StringBuffer on which to append the formatted information.

fieldPosition

A number field.

Returns

Returns

A hashcode for this object.

Overrides

NumberFormat.hashCode()

Description

This method returns a hashcode for this DecimalFormat.

isDecimalSeparatorAlwaysShown

public boolean isDecimalSeparatorAlwaysShown()

Returns

A boolean value that indicates whether or not the decimal separator symbol is always shown.

Description

This method returns true if this DecimalFormat always shows the decimal separator. The method returns false if the decimal separator is only shown if there is a fractional portion of the number being formatted.

parse

public Number parse(String text, ParsePosition status)

Parameters

text

The string to be parsed.

status

A ParsePosition object that specifies a position in the string.

Returns

The Number object represented by the text starting at the given position.

Overrides

NumberFormat.parse(String, ParsePosition)

Description

This method parses a number from the given string, starting from the given position. After the string has been parsed, the given ParsePosition object is updated so that its index is after the parsed text.

setDecimalFormatSymbols

 public void setDecimalFormatSymbols( DecimalFormatSymbols newSymbols)

Parameters

newSymbols: The new DecimalFormatSymbols object to use.

Description

This method sets the DecimalFormatSymbols object that this DecimalFormat uses internally.

setDecimalSeparatorAlwaysShown

public void setDecimalSeparatorAlwaysShown(boolean newValue)

Parameters

newValue: The new decimal separator value.

Description

This method specifies whether or not the decimal separator symbol is always shown in formatted numbers. If newValue is false, the separator is only shown for numbers that have a fractional part. Otherwise, the separator is always shown.

setGroupingSize

public void setGroupingSize(int newValue)

Parameters

newValue: The new grouping size.

Description

This method sets the grouping size of this DecimalFormat. The grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number 1,234.56, the grouping size is 3 (and the grouping symbol is ",").

setMultiplier

public void setMultiplier(int newValue)

Parameters

newValue: The new multiplier.

Description

This method sets the multiplier of this DecimalFormat. The multiplier is used to adjust a number before it is formatted or after it is parsed. For example, a percent format has a multiplier of 100 and a suffix of %. Thus, a value of .42 could be formatted as 42%.

setNegativePrefix

public void setNegativePrefix(String newValue)

Parameters

newValue: The new prefix.

Description

This method sets the prefix string for negative values.

setNegativeSuffix

public void setNegativeSuffix(String newValue)

Parameters

newValue: The new suffix.

Description

This method sets the suffix string for negative values.

setPositivePrefix

public void setPositivePrefix(String newValue)

Parameters

newValue: The new prefix.

Description

This method sets the prefix string for positive values.

setPositiveSuffix

public void setPositiveSuffix(String newValue)

Parameters

newValue: The new suffix.

Description

This method sets the suffix string for positive values.

toLocalizedPattern

public String toLocalizedPattern()

Returns

The pattern string of this DecimalFormat.

Description

This method returns the pattern string of this DecimalFormat, localized with the DecimalFormatSymbols object of this DecimalFormat.

toPattern

public String toPattern()

Returns

The pattern string of this DecimalFormat.

Description

This method returns the pattern string of this DecimalFormat.

Inherited Methods

Method	Inherited From	Method	Inherited From
`finalize()`	`Object`	`format(double)`	`NumberFormat`
`format(long)`	`NumberFormat`	`format(Object, StringBuffer, FieldPosition)`	`NumberFormat`
`getClass()`	`Object`	`getMaximumFractionDigits()`	`NumberFormat`
`getMaximumIntegerDigits()`	`NumberFormat`	`getMinimumFractionDigits()`	`NumberFormat`
`getMinimumIntegerDigits()`	`NumberFormat`	`isGroupingUsed()`	`NumberFormat`
`isParseIntegerOnly()`	`NumberFormat`	`notify()`	`Object`
`notifyAll()`	`Object`	`parse(String)`	`NumberFormat`
`parseObject(String)`	`Format`	`parseObject(String, ParsePosition)`	`NumberFormat`
`setGroupingUsed(boolean)`	`NumberFormat`	`setMaximumFractionDigits(int)`	`NumberFormat`
`setMaximumIntegerDigits(int)`	`NumberFormat`	`setMinimumFractionDigits(int)`	`NumberFormat`
`setMinimumIntegerDigits(int)`	`NumberFormat`	`setParseIntegerOnly(boolean)`	`NumberFormat`
`toString()`	`Object`	`wait()`	`Object`
`wait(long)`	`Object`	`wait(long, int)`	`Object`