Java Fundamental Classes Reference

Previous Chapter 16
The java.text Package
Next
 

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

Description

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

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.

getDecimalFormatSymbols

public DecimalFormatSymbols getDecimalFormatSymbols()

Returns

The DecimalFormatSymbols object used by this DecimalFormat.

Description

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

getGroupingSize

public int getGroupingSize()

Returns

The grouping size of this DecimalFormat.

Description

This method returns 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 ",").

getMultiplier

public int getMultiplier()

Returns

The multiplier of this DecimalFormat.

Description

This method returns 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%.

getNegativePrefix

public String getNegativePrefix()

Returns

The string that is prepended to negative values.

Description

This method returns the prefix string for negative numbers.

getNegativeSuffix

public String getNegativeSuffix()

Returns

The string that is appended to negative values.

Description

This method returns the suffix string for negative numbers.

getPositivePrefix

public String getPositivePrefix()

Returns

The string that is prepended to positive values.

Description

This method returns the prefix string for positive numbers.

getPositiveSuffix

public String getPositiveSuffix()

Returns

The string that is appended to positive values.

Description

This method returns the suffix string for positive numbers.

hashCode

public int hashCode()

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

See Also

DecimalFormatSymbols, FieldPosition, Number, NumberFormat, ParsePosition, String, StringBuffer


Previous Home Next
DateFormatSymbols Book Index DecimalFormatSymbols

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java