java.text
Class NumberFormat

java.lang.Object
  extended by java.text.Format
      extended by java.text.NumberFormat
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
ChoiceFormat, DecimalFormat

public abstract class NumberFormat
extends Format
implements Cloneable

This is the abstract superclass of all classes which format and parse numeric values such as decimal numbers, integers, currency values, and percentages. These classes perform their parsing and formatting in a locale specific manner, accounting for such items as differing currency symbols and thousands separators.

To create an instance of a concrete subclass of NumberFormat, do not call a class constructor directly. Instead, use one of the static factory methods in this class such as getCurrencyInstance.

See Also:
Serialized Form

Nested Class Summary
static class NumberFormat.Field
           
 
Field Summary
static int FRACTION_FIELD
          This is a constant used to create a FieldPosition object that will return the fractional portion of a formatted number.
static int INTEGER_FIELD
          This is a constant used to create a FieldPosition object that will return the integer portion of a formatted number.
 
Constructor Summary
NumberFormat()
          This is a default constructor for use by subclasses.
 
Method Summary
 boolean equals(Object obj)
          This method tests the specified object for equality against this object.
 String format(double number)
          This method is a specialization of the format method that performs a simple formatting of the specified double number.
abstract  StringBuffer format(double number, StringBuffer sbuf, FieldPosition pos)
          This method formats the specified double and appends it to a StringBuffer.
 String format(long number)
          This method is a specialization of the format method that performs a simple formatting of the specified long number.
abstract  StringBuffer format(long number, StringBuffer sbuf, FieldPosition pos)
          This method formats the specified long and appends it to a StringBuffer.
 StringBuffer format(Object obj, StringBuffer sbuf, FieldPosition pos)
          This method formats an Object into a String and appends the String to a StringBuffer.
static Locale[] getAvailableLocales()
          This method returns a list of locales for which concrete instances of NumberFormat subclasses may be created.
 Currency getCurrency()
          Returns the currency used by this number format when formatting currency values.
static NumberFormat getCurrencyInstance()
          This method returns an instance of NumberFormat suitable for formatting and parsing currency values in the default locale.
static NumberFormat getCurrencyInstance(Locale loc)
          This method returns an instance of NumberFormat suitable for formatting and parsing currency values in the specified locale.
static NumberFormat getInstance()
          This method returns a default instance for the default locale.
static NumberFormat getInstance(Locale loc)
          This method returns a default instance for the specified locale.
static NumberFormat getIntegerInstance()
          This method returns an integer formatting and parsing class for the default locale.
static NumberFormat getIntegerInstance(Locale locale)
          This method returns an integer formatting and parsing class for the default locale.
 int getMaximumFractionDigits()
          This method returns the maximum number of digits allowed in the fraction portion of a number.
 int getMaximumIntegerDigits()
          This method returns the maximum number of digits allowed in the integer portion of a number.
 int getMinimumFractionDigits()
          This method returns the minimum number of digits allowed in the fraction portion of a number.
 int getMinimumIntegerDigits()
          This method returns the minimum number of digits allowed in the integer portion of a number.
static NumberFormat getNumberInstance()
          This method returns a default instance for the specified locale.
static NumberFormat getNumberInstance(Locale loc)
          This method returns a general purpose number formatting and parsing class for the default locale.
static NumberFormat getPercentInstance()
          This method returns an instance of NumberFormat suitable for formatting and parsing percentage values in the default locale.
static NumberFormat getPercentInstance(Locale loc)
          This method returns an instance of NumberFormat suitable for formatting and parsing percentage values in the specified locale.
 int hashCode()
          This method returns a hash value for this object.
 boolean isGroupingUsed()
          This method tests whether or not grouping is in use.
 boolean isParseIntegerOnly()
          This method tests whether or not only integer values should be parsed.
 Number parse(String sourceStr)
          This method parses the specified string into a Number.
abstract  Number parse(String sourceStr, ParsePosition pos)
          This method parses the specified string into a Number.
 Object parseObject(String sourceStr, ParsePosition pos)
          This method parses the specified string into an Object.
 void setCurrency(Currency currency)
          Sets the currency used by this number format when formatting currency values.
 void setGroupingUsed(boolean newValue)
          This method sets the grouping behavior of this formatter.
 void setMaximumFractionDigits(int digits)
          This method sets the maximum number of digits allowed in the fraction portion of a number to the specified value.
 void setMaximumIntegerDigits(int digits)
          This method sets the maximum number of digits allowed in the integer portion of a number to the specified value.
 void setMinimumFractionDigits(int digits)
          This method sets the minimum number of digits allowed in the fraction portion of a number to the specified value.
 void setMinimumIntegerDigits(int digits)
          This method sets the minimum number of digits allowed in the integer portion of a number to the specified value.
 void setParseIntegerOnly(boolean value)
          This method sets the parsing behavior of this object to parse only integers or not.
 
Methods inherited from class java.text.Format
clone, format, formatToCharacterIterator, parseObject
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INTEGER_FIELD

public static final int INTEGER_FIELD
This is a constant used to create a FieldPosition object that will return the integer portion of a formatted number.

See Also:
Constant Field Values

FRACTION_FIELD

public static final int FRACTION_FIELD
This is a constant used to create a FieldPosition object that will return the fractional portion of a formatted number.

See Also:
Constant Field Values
Constructor Detail

NumberFormat

public NumberFormat()
This is a default constructor for use by subclasses.

Method Detail

format

public final String format(long number)
This method is a specialization of the format method that performs a simple formatting of the specified long number.

Parameters:
number - The long to format.
Returns:
The formatted number

format

public StringBuffer format(Object obj,
                           StringBuffer sbuf,
                           FieldPosition pos)
Description copied from class: Format
This method formats an Object into a String and appends the String to a StringBuffer.

Specified by:
format in class Format
Parameters:
obj - The Object to format.
sbuf - The StringBuffer to append to.
pos - The desired FieldPosition, which is also updated by this call.
Returns:
The updated StringBuffer.

format

public abstract StringBuffer format(double number,
                                    StringBuffer sbuf,
                                    FieldPosition pos)
This method formats the specified double and appends it to a StringBuffer.

Parameters:
number - The double to format.
sbuf - The StringBuffer to append the formatted number to.
pos - The desired FieldPosition.
Returns:
The StringBuffer with the appended number.

format

public abstract StringBuffer format(long number,
                                    StringBuffer sbuf,
                                    FieldPosition pos)
This method formats the specified long and appends it to a StringBuffer.

Parameters:
number - The long to format.
sbuf - The StringBuffer to append the formatted number to.
pos - The desired FieldPosition.
Returns:
The StringBuffer with the appended number.

equals

public boolean equals(Object obj)
This method tests the specified object for equality against this object. This will be true if the following conditions are met:

Since this method does not test much, it is highly advised that concrete subclasses override this method.

Overrides:
equals in class Object
Parameters:
obj - The Object to test against equality with this object.
Returns:
true if the specified object is equal to this object, false otherwise.
See Also:
Object.hashCode()

getAvailableLocales

public static Locale[] getAvailableLocales()
This method returns a list of locales for which concrete instances of NumberFormat subclasses may be created.

Returns:
The list of available locales.

getCurrencyInstance

public static final NumberFormat getCurrencyInstance()
This method returns an instance of NumberFormat suitable for formatting and parsing currency values in the default locale.

Returns:
An instance of NumberFormat for handling currencies.

getCurrencyInstance

public static NumberFormat getCurrencyInstance(Locale loc)
This method returns an instance of NumberFormat suitable for formatting and parsing currency values in the specified locale.

Returns:
An instance of NumberFormat for handling currencies.

getInstance

public static final NumberFormat getInstance()
This method returns a default instance for the default locale. This will be a concrete subclass of NumberFormat, but the actual class returned is dependent on the locale.

Returns:
An instance of the default NumberFormat class.

getInstance

public static NumberFormat getInstance(Locale loc)
This method returns a default instance for the specified locale. This will be a concrete subclass of NumberFormat, but the actual class returned is dependent on the locale.

Parameters:
loc - The desired locale.
Returns:
An instance of the default NumberFormat class.

getMaximumFractionDigits

public int getMaximumFractionDigits()
This method returns the maximum number of digits allowed in the fraction portion of a number.

Returns:
The maximum number of digits allowed in the fraction portion of a number.

getMaximumIntegerDigits

public int getMaximumIntegerDigits()
This method returns the maximum number of digits allowed in the integer portion of a number.

Returns:
The maximum number of digits allowed in the integer portion of a number.

getMinimumFractionDigits

public int getMinimumFractionDigits()
This method returns the minimum number of digits allowed in the fraction portion of a number.

Returns:
The minimum number of digits allowed in the fraction portion of a number.

getMinimumIntegerDigits

public int getMinimumIntegerDigits()
This method returns the minimum number of digits allowed in the integer portion of a number.

Returns:
The minimum number of digits allowed in the integer portion of a number.

getNumberInstance

public static final NumberFormat getNumberInstance()
This method returns a default instance for the specified locale. This will be a concrete subclass of NumberFormat, but the actual class returned is dependent on the locale.

Returns:
An instance of the default NumberFormat class.

getNumberInstance

public static NumberFormat getNumberInstance(Locale loc)
This method returns a general purpose number formatting and parsing class for the default locale. This will be a concrete subclass of NumberFormat, but the actual class returned is dependent on the locale.

Returns:
An instance of a generic number formatter for the default locale.

getIntegerInstance

public static final NumberFormat getIntegerInstance()
This method returns an integer formatting and parsing class for the default locale. This will be a concrete subclass of NumberFormat, but the actual class returned is dependent on the locale.

Returns:
An instance of an integer number formatter for the default locale.
Since:
1.4

getIntegerInstance

public static NumberFormat getIntegerInstance(Locale locale)
This method returns an integer formatting and parsing class for the default locale. This will be a concrete subclass of NumberFormat, but the actual class returned is dependent on the locale.

Parameters:
locale - the desired locale.
Returns:
An instance of an integer number formatter for the desired locale.
Since:
1.4

getPercentInstance

public static final NumberFormat getPercentInstance()
This method returns an instance of NumberFormat suitable for formatting and parsing percentage values in the default locale.

Returns:
An instance of NumberFormat for handling percentages.

getPercentInstance

public static NumberFormat getPercentInstance(Locale loc)
This method returns an instance of NumberFormat suitable for formatting and parsing percentage values in the specified locale.

Parameters:
loc - The desired locale.
Returns:
An instance of NumberFormat for handling percentages.

hashCode

public int hashCode()
This method returns a hash value for this object.

Overrides:
hashCode in class Object
Returns:
The hash code.
See Also:
Object.equals(Object), System.identityHashCode(Object)

isGroupingUsed

public boolean isGroupingUsed()
This method tests whether or not grouping is in use. Grouping is a method of marking separations in numbers, such as thousand separators in the US English locale. The grouping positions and symbols are all locale specific. As an example, with grouping disabled, the number one million would appear as "1000000". With grouping enabled, this number might appear as "1,000,000". (Both of these assume the US English locale).

Returns:
true if grouping is enabled, false otherwise.

isParseIntegerOnly

public boolean isParseIntegerOnly()
This method tests whether or not only integer values should be parsed. If this class is parsing only integers, parsing stops at the decimal point.

Returns:
true if only integers are parsed, false otherwise.

parse

public abstract Number parse(String sourceStr,
                             ParsePosition pos)
This method parses the specified string into a Number. This will be a Long if possible, otherwise it will be a Double. If no number can be parsed, no exception is thrown. Instead, the parse position remains at its initial index.

Parameters:
sourceStr - The string to parse.
pos - The desired ParsePosition.
Returns:
The parsed Number

parse

public Number parse(String sourceStr)
             throws ParseException
This method parses the specified string into a Number. This will be a Long if possible, otherwise it will be a Double. If no number can be parsed, an exception will be thrown.

Parameters:
sourceStr - The string to parse.
Returns:
The parsed Number
Throws:
ParseException - If no number can be parsed.

parseObject

public final Object parseObject(String sourceStr,
                                ParsePosition pos)
This method parses the specified string into an Object. This will be a Long if possible, otherwise it will be a Double. If no number can be parsed, no exception is thrown. Instead, the parse position remains at its initial index.

Specified by:
parseObject in class Format
Parameters:
sourceStr - The string to parse.
pos - The desired ParsePosition.
Returns:
The parsed Object

setGroupingUsed

public void setGroupingUsed(boolean newValue)
This method sets the grouping behavior of this formatter. Grouping is a method of marking separations in numbers, such as thousand separators in the US English locale. The grouping positions and symbols are all locale specific. As an example, with grouping disabled, the number one million would appear as "1000000". With grouping enabled, this number might appear as "1,000,000". (Both of these assume the US English locale).

Parameters:
newValue - true to enable grouping, false to disable it.

setMaximumFractionDigits

public void setMaximumFractionDigits(int digits)
This method sets the maximum number of digits allowed in the fraction portion of a number to the specified value. If this is less than the current minimum allowed digits, the minimum allowed digits value will be lowered to be equal to the new maximum allowed digits value.

Parameters:
digits - The new maximum fraction digits value.

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int digits)
This method sets the maximum number of digits allowed in the integer portion of a number to the specified value. If this is less than the current minimum allowed digits, the minimum allowed digits value will be lowered to be equal to the new maximum allowed digits value.

Parameters:
digits - The new maximum integer digits value.

setMinimumFractionDigits

public void setMinimumFractionDigits(int digits)
This method sets the minimum number of digits allowed in the fraction portion of a number to the specified value. If this is greater than the current maximum allowed digits, the maximum allowed digits value will be raised to be equal to the new minimum allowed digits value.

Parameters:
digits - The new minimum fraction digits value.

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int digits)
This method sets the minimum number of digits allowed in the integer portion of a number to the specified value. If this is greater than the current maximum allowed digits, the maximum allowed digits value will be raised to be equal to the new minimum allowed digits value.

Parameters:
digits - The new minimum integer digits value.

setParseIntegerOnly

public void setParseIntegerOnly(boolean value)
This method sets the parsing behavior of this object to parse only integers or not.

Parameters:
value - true to parse only integers, false otherwise.

format

public final String format(double number)
This method is a specialization of the format method that performs a simple formatting of the specified double number.

Parameters:
number - The double to format.
Returns:
The formatted number

getCurrency

public Currency getCurrency()
Returns the currency used by this number format when formatting currency values. The default implementation throws UnsupportedOperationException.

Returns:
The used currency object, or null.
Throws:
UnsupportedOperationException - If the number format class doesn't implement currency formatting.
Since:
1.4

setCurrency

public void setCurrency(Currency currency)
Sets the currency used by this number format when formatting currency values. The default implementation throws UnsupportedOperationException.

Parameters:
currency - The new currency to be used by this number format.
Throws:
NullPointerException - If currenc is null.
UnsupportedOperationException - If the number format class doesn't implement currency formatting.
Since:
1.4