java.text

Class NumberFormat

Implemented Interfaces:
Cloneable, Serializable
Known Direct 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

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

Format.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.
StringBuffer
format(Object obj, StringBuffer sbuf, FieldPosition pos)
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.
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, format, formatToCharacterIterator, parseObject, parseObject

Methods inherited from class java.lang.Object

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

Field Details

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.
Field Value:
1

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.
Field Value:
0

Constructor Details

NumberFormat

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

Method Details

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.

Overrides:
equals in interface 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.

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

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 StringBuffer format(Object obj,
                           StringBuffer sbuf,
                           FieldPosition pos)
Overrides:
format in interface Format

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 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.

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.
Overrides:
hashCode in interface 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 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.

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

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.
Overrides:
parseObject in interface Format
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.

NumberFormat.java -- Formats and parses numbers Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2007 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.