java.text

Class NumberFormat

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.

UNKNOWN: March 4, 1999

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(long number) This method is a specialization of the format method that performs a simple formatting of the specified `long` number.
StringBuffer	format(Object obj, StringBuffer sbuf, FieldPosition pos)
abstract StringBuffer	format(double number, StringBuffer sbuf, FieldPosition pos) This method formats the specified `double` and appends it to a `StringBuffer`.
abstract StringBuffer	format(long number, StringBuffer sbuf, FieldPosition pos) This method formats the specified `long` and appends it to a `StringBuffer`.
String	format(double number) This method is a specialization of the format method that performs a simple formatting of the specified `double` number.
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.
abstract Number	parse(String sourceStr, ParsePosition pos) This method parses the specified string into a `Number`.
Number	parse(String sourceStr) 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.

Field Detail

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.

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.

Constructor Detail

NumberFormat

public NumberFormat()

This is a default constructor for use by subclasses.

Method Detail

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:

The specified object is not null.
The specified object is an instance of NumberFormat.

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

Parameters: obj The Object to test against equality with this object.

Returns: true if the specified object is equal to this object, false otherwise.

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)

UNKNOWN: this method was final in releases before 1.5

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.

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

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.

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

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.

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

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.

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.

Returns: The hash code.

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)

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.

Parameters: sourceStr The string to parse. pos The desired ParsePosition.

Returns: The parsed Object

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

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.