* 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.
*
* @author Tom Tromey (tromey@cygnus.com)
* @author Aaron M. Renn (arenn@urbanophile.com)
* @date March 4, 1999
*/
/* Written using "Java Class Libraries", 2nd edition, plus online
* API docs for JDK 1.2 from http://www.javasoft.com.
* Status: Believed complete and correct to 1.2, except getAvailableLocales.
*/
public abstract class NumberFormat extends Format implements Cloneable
{
/**
* This is a constant used to create a FieldPosition object
* that will return the integer portion of a formatted number.
*/
public static final int INTEGER_FIELD = 0;
/**
* This is a constant used to create a FieldPosition object
* that will return the fractional portion of a formatted number.
*/
public static final int FRACTION_FIELD = 1;
public static class Field extends Format.Field
{
static final long serialVersionUID = 7494728892700160890L;
/**
* Attribute set to all characters containing digits of the integer
* part.
*/
public static final NumberFormat.Field INTEGER
= new Field("integer");
/**
* Attribute set to all characters containing digits of the fractional
* part.
*/
public static final NumberFormat.Field FRACTION
= new Field("fraction");
/**
* Attribute set to all characters containing digits of the exponential
* part.
*/
public static final NumberFormat.Field EXPONENT
= new Field("exponent");
/**
* Attribute set to all characters containing a decimal separator.
*/
public static final NumberFormat.Field DECIMAL_SEPARATOR
= new Field("decimal separator");
/**
* Attribute set to all characters containing a sign (plus or minus).
*/
public static final NumberFormat.Field SIGN
= new Field("sign");
/**
* Attribute set to all characters containing a grouping separator (e.g.
* a comma, a white space,...).
*/
public static final NumberFormat.Field GROUPING_SEPARATOR
= new Field("grouping separator");
/**
* Attribute set to all characters containing an exponential symbol (e.g.
* 'E')
*/
public static final NumberFormat.Field EXPONENT_SYMBOL
= new Field("exponent symbol");
/**
* Attribute set to all characters containing a percent symbol (e.g. '%')
*/
public static final NumberFormat.Field PERCENT
= new Field("percent");
/**
* Attribute set to all characters containing a permille symbol.
*/
public static final NumberFormat.Field PERMILLE
= new Field("permille");
/**
* Attribute set to all characters containing the currency unit.
*/
public static final NumberFormat.Field CURRENCY
= new Field("currency");
/**
* Attribute set to all characters containing the exponent sign.
*/
public static final NumberFormat.Field EXPONENT_SIGN
= new Field("exponent sign");
/**
* Private fields to register all fields contained in this descriptor.
*/
private static final NumberFormat.Field[] allFields =
{
INTEGER, FRACTION, EXPONENT, DECIMAL_SEPARATOR, SIGN,
GROUPING_SEPARATOR, EXPONENT_SYMBOL, PERCENT,
PERMILLE, CURRENCY, EXPONENT_SIGN
};
/**
* This constructor is only used by the deserializer. Without it,
* it would fail to construct a valid object.
*/
@SuppressWarnings("unused")
private Field()
{
super("");
}
/**
* Create a Field instance with the specified field name.
*
* @param field_name Field name for the new Field instance.
*/
protected Field(String field_name)
{
super (field_name);
}
/**
* This function is used by the deserializer to know which object
* to use when it encounters an encoded NumberFormat.Field in a
* serialization stream. If the stream is valid it should return
* one of the above field. In the other case we throw an exception.
*
* @return a valid official NumberFormat.Field instance.
*
* @throws InvalidObjectException if the field name is invalid.
*/
protected Object readResolve() throws InvalidObjectException
{
String s = getName();
for (int i = 0; i < allFields.length; i++)
if (s.equals(allFields[i].getName()))
return allFields[i];
throw new InvalidObjectException("no such NumberFormat field called "
+ s);
}
}
/**
* This method is a specialization of the format method that performs
* a simple formatting of the specified long number.
*
* @param number The long to format.
*
* @return The formatted number
*/
public final String format (long number)
{
StringBuffer sbuf = new StringBuffer(50);
format (number, sbuf, new FieldPosition(0));
return sbuf.toString();
}
/**
* @specnote this method was final in releases before 1.5
*/
public StringBuffer format (Object obj, StringBuffer sbuf,
FieldPosition pos)
{
if (obj instanceof Number)
return format(((Number) obj).doubleValue(), sbuf, pos);
throw new
IllegalArgumentException("Cannot format given Object as a Number");
}
/**
* This method formats the specified double and appends it to
* a StringBuffer.
*
* @param number The double to format.
* @param sbuf The StringBuffer to append the formatted number
* to.
* @param pos The desired FieldPosition.
*
* @return The StringBuffer with the appended number.
*/
public abstract StringBuffer format (double number,
StringBuffer sbuf, FieldPosition pos);
/**
* This method formats the specified long and appends it to
* a StringBuffer.
*
* @param number The long to format.
* @param sbuf The StringBuffer to append the formatted number
* to.
* @param pos The desired FieldPosition.
*
* @return The StringBuffer with the appended number.
*/
public abstract StringBuffer format (long number,
StringBuffer sbuf, FieldPosition pos);
/**
* This method tests the specified object for equality against this object.
* This will be true if the following conditions are met:
*
*
null.
* NumberFormat.
*
* Since this method does not test much, it is highly advised that
* concrete subclasses override this method.
*
* @param obj The Object to test against equality with
* this object.
*
* @return true if the specified object is equal to
* this object, false otherwise.
*/
public boolean equals (Object obj)
{
if (! (obj instanceof NumberFormat))
return false;
NumberFormat nf = (NumberFormat) obj;
return (groupingUsed == nf.groupingUsed
&& maximumFractionDigits == nf.maximumFractionDigits
&& maximumIntegerDigits == nf.maximumIntegerDigits
&& minimumFractionDigits == nf.minimumFractionDigits
&& minimumIntegerDigits == nf.minimumIntegerDigits
&& parseIntegerOnly == nf.parseIntegerOnly);
}
/**
* This method returns a list of locales for which concrete instances
* of NumberFormat subclasses may be created.
*
* @return The list of available locales.
*/
public static Locale[] getAvailableLocales ()
{
Locale[] list = new Locale[1];
list[0] = Locale.US;
return list;
}
private static NumberFormat computeInstance(Locale loc, String resource,
String def)
throws MissingResourceException
{
if (loc.equals(Locale.ROOT))
return new DecimalFormat(def, DecimalFormatSymbols.getInstance(loc));
ResourceBundle res =
ResourceBundle.getBundle("gnu.java.locale.LocaleInformation",
loc, ClassLoader.getSystemClassLoader());
String fmt;
try
{
fmt = res == null ? def : res.getString(resource);
}
catch (MissingResourceException x)
{
fmt = def;
}
DecimalFormatSymbols dfs = DecimalFormatSymbols.getInstance(loc);
return new DecimalFormat (fmt, dfs);
}
/**
* This method returns an instance of NumberFormat suitable
* for formatting and parsing currency values in the default locale.
*
* @return An instance of NumberFormat for handling currencies.
*/
public static final NumberFormat getCurrencyInstance ()
{
return getCurrencyInstance (Locale.getDefault());
}
/**
* This method returns an instance of NumberFormat suitable
* for formatting and parsing currency values in the specified locale.
*
* @return An instance of NumberFormat for handling currencies.
*/
public static NumberFormat getCurrencyInstance (Locale loc)
{
try
{
NumberFormat format;
format = computeInstance (loc, "currencyFormat",
"\u00A4#,##0.00;(\u00A4#,##0.00)");
format.setMaximumFractionDigits(format.getCurrency().getDefaultFractionDigits());
return format;
}
catch (MissingResourceException e)
{
for (NumberFormatProvider p :
ServiceLoader.load(NumberFormatProvider.class))
{
for (Locale l : p.getAvailableLocales())
{
if (l.equals(loc))
{
NumberFormat nf = p.getCurrencyInstance(loc);
if (nf != null)
return nf;
break;
}
}
}
return getCurrencyInstance(LocaleHelper.getFallbackLocale(loc));
}
}
/**
* 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.
*
* @return An instance of the default NumberFormat class.
*/
public static final NumberFormat getInstance ()
{
return getInstance (Locale.getDefault());
}
/**
* 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.
*
* @param loc The desired locale.
*
* @return An instance of the default NumberFormat class.
*/
public static NumberFormat getInstance (Locale loc)
{
// For now always return a number instance.
return getNumberInstance (loc);
}
/**
* This method returns the maximum number of digits allowed in the fraction
* portion of a number.
*
* @return The maximum number of digits allowed in the fraction
* portion of a number.
*/
public int getMaximumFractionDigits ()
{
return maximumFractionDigits;
}
/**
* This method returns the maximum number of digits allowed in the integer
* portion of a number.
*
* @return The maximum number of digits allowed in the integer
* portion of a number.
*/
public int getMaximumIntegerDigits ()
{
return maximumIntegerDigits;
}
/**
* This method returns the minimum number of digits allowed in the fraction
* portion of a number.
*
* @return The minimum number of digits allowed in the fraction
* portion of a number.
*/
public int getMinimumFractionDigits ()
{
return minimumFractionDigits;
}
/**
* This method returns the minimum number of digits allowed in the integer
* portion of a number.
*
* @return The minimum number of digits allowed in the integer
* portion of a number.
*/
public int getMinimumIntegerDigits ()
{
return minimumIntegerDigits;
}
/**
* 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.
*
* @return An instance of the default NumberFormat class.
*/
public static final NumberFormat getNumberInstance ()
{
return getNumberInstance (Locale.getDefault());
}
/**
* 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.
*
* @return An instance of a generic number formatter for the default locale.
*/
public static NumberFormat getNumberInstance (Locale loc)
{
try
{
return computeInstance (loc, "numberFormat", "#,##0.###");
}
catch (MissingResourceException e)
{
for (NumberFormatProvider p :
ServiceLoader.load(NumberFormatProvider.class))
{
for (Locale l : p.getAvailableLocales())
{
if (l.equals(loc))
{
NumberFormat nf = p.getNumberInstance(loc);
if (nf != null)
return nf;
break;
}
}
}
return getNumberInstance(LocaleHelper.getFallbackLocale(loc));
}
}
/**
* 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.
*
* @return An instance of an integer number formatter for the default locale.
* @since 1.4
*/
public static final NumberFormat getIntegerInstance()
{
return getIntegerInstance (Locale.getDefault());
}
/**
* 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.
*
* @param locale the desired locale.
*
* @return An instance of an integer number formatter for the desired locale.
* @since 1.4
*/
public static NumberFormat getIntegerInstance(Locale locale)
{
try
{
NumberFormat format = computeInstance (locale,
"integerFormat", "#,##0");
format.setMaximumFractionDigits(0);
format.setParseIntegerOnly (true);
return format;
}
catch (MissingResourceException e)
{
for (NumberFormatProvider p :
ServiceLoader.load(NumberFormatProvider.class))
{
for (Locale l : p.getAvailableLocales())
{
if (l.equals(locale))
{
NumberFormat nf = p.getIntegerInstance(locale);
if (nf != null)
return nf;
break;
}
}
}
return getIntegerInstance(LocaleHelper.getFallbackLocale(locale));
}
}
/**
* This method returns an instance of NumberFormat suitable
* for formatting and parsing percentage values in the default locale.
*
* @return An instance of NumberFormat for handling percentages.
*/
public static final NumberFormat getPercentInstance ()
{
return getPercentInstance (Locale.getDefault());
}
/**
* This method returns an instance of NumberFormat suitable
* for formatting and parsing percentage values in the specified locale.
*
* @param loc The desired locale.
*
* @return An instance of NumberFormat for handling percentages.
*/
public static NumberFormat getPercentInstance (Locale loc)
{
try
{
return computeInstance (loc, "percentFormat", "#,##0%");
}
catch (MissingResourceException e)
{
for (NumberFormatProvider p :
ServiceLoader.load(NumberFormatProvider.class))
{
for (Locale l : p.getAvailableLocales())
{
if (l.equals(loc))
{
NumberFormat nf = p.getPercentInstance(loc);
if (nf != null)
return nf;
break;
}
}
}
return getPercentInstance(LocaleHelper.getFallbackLocale(loc));
}
}
/**
* This method returns a hash value for this object.
*
* @return The hash code.
*/
public int hashCode ()
{
int hash = super.hashCode();
hash ^= (maximumFractionDigits + maximumIntegerDigits
+ minimumFractionDigits + minimumIntegerDigits);
if (groupingUsed)
hash ^= 0xf0f0;
if (parseIntegerOnly)
hash ^= 0x0f0f;
return hash;
}
/**
* 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).
*
* @return true if grouping is enabled,
* false otherwise.
*/
public boolean isGroupingUsed ()
{
return groupingUsed;
}
/**
* 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.
*
* @return true if only integers are parsed,
* false otherwise.
*/
public boolean isParseIntegerOnly ()
{
return parseIntegerOnly;
}
/**
* This is a default constructor for use by subclasses.
*/
protected NumberFormat ()
{
}
/**
* 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.
*
* @param sourceStr The string to parse.
* @param pos The desired ParsePosition.
*
* @return The parsed Number
*/
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, an exception will be
* thrown.
*
* @param sourceStr The string to parse.
*
* @return The parsed Number
*
* @exception ParseException If no number can be parsed.
*/
public Number parse (String sourceStr) throws ParseException
{
ParsePosition pp = new ParsePosition (0);
Number r = parse (sourceStr, pp);
if (r == null)
{
int index = pp.getErrorIndex();
if (index < 0)
index = pp.getIndex();
throw new ParseException ("couldn't parse number", index);
}
return r;
}
/**
* 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.
*
* @param sourceStr The string to parse.
* @param pos The desired ParsePosition.
*
* @return The parsed Object
*/
public final Object parseObject (String sourceStr, ParsePosition pos)
{
return parse (sourceStr, pos);
}
/**
* 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).
*
* @param newValue true to enable grouping,
* false to disable it.
*/
public void setGroupingUsed (boolean newValue)
{
groupingUsed = newValue;
}
/**
* 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.
*
* @param digits The new maximum fraction digits value.
*/
public void setMaximumFractionDigits (int digits)
{
maximumFractionDigits = digits;
if (getMinimumFractionDigits () > maximumFractionDigits)
setMinimumFractionDigits (maximumFractionDigits);
}
/**
* 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.
*
* @param digits The new maximum integer digits value.
*/
public void setMaximumIntegerDigits (int digits)
{
maximumIntegerDigits = digits;
if (getMinimumIntegerDigits () > maximumIntegerDigits)
setMinimumIntegerDigits (maximumIntegerDigits);
}
/**
* 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.
*
* @param digits The new minimum fraction digits value.
*/
public void setMinimumFractionDigits (int digits)
{
minimumFractionDigits = digits;
if (getMaximumFractionDigits () < minimumFractionDigits)
setMaximumFractionDigits (minimumFractionDigits);
}
/**
* 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.
*
* @param digits The new minimum integer digits value.
*/
public void setMinimumIntegerDigits (int digits)
{
minimumIntegerDigits = digits;
if (getMaximumIntegerDigits () < minimumIntegerDigits)
setMaximumIntegerDigits (minimumIntegerDigits);
}
/**
* This method sets the parsing behavior of this object to parse only
* integers or not.
*
* @param value true to parse only integers,
* false otherwise.
*/
public void setParseIntegerOnly (boolean value)
{
parseIntegerOnly = value;
}
/**
* This method is a specialization of the format method that performs
* a simple formatting of the specified double number.
*
* @param number The double to format.
*
* @return The formatted number
*/
public final String format (double number)
{
StringBuffer sbuf = new StringBuffer(50);
FieldPosition position = new FieldPosition(0);
format (number, sbuf, position);
return sbuf.toString();
}
// These field names are fixed by the serialization spec.
boolean groupingUsed;
int maximumFractionDigits;
private byte maxFractionDigits;
int maximumIntegerDigits;
private byte maxIntegerDigits;
int minimumFractionDigits;
private byte minFractionDigits;
int minimumIntegerDigits;
private byte minIntegerDigits;
boolean parseIntegerOnly;
private int serialVersionOnStream;
private static final long serialVersionUID = -2308460125733713944L;
private void readObject(ObjectInputStream stream)
throws IOException, ClassNotFoundException
{
stream.defaultReadObject();
if (serialVersionOnStream < 1)
{
maximumFractionDigits = maxFractionDigits;
maximumIntegerDigits = maxIntegerDigits;
minimumFractionDigits = minFractionDigits;
minimumIntegerDigits = minIntegerDigits;
serialVersionOnStream = 1;
}
}
private void writeObject(ObjectOutputStream stream) throws IOException
{
maxFractionDigits = maximumFractionDigits < Byte.MAX_VALUE ?
(byte) maximumFractionDigits : Byte.MAX_VALUE;
maxIntegerDigits = maximumIntegerDigits < Byte.MAX_VALUE ?
(byte) maximumIntegerDigits : Byte.MAX_VALUE;
minFractionDigits = minimumFractionDigits < Byte.MAX_VALUE ?
(byte) minimumFractionDigits : Byte.MAX_VALUE;
minIntegerDigits = minimumIntegerDigits < Byte.MAX_VALUE ?
(byte) minimumIntegerDigits : Byte.MAX_VALUE;
serialVersionOnStream = 1;
stream.defaultWriteObject();
}
/**
* Returns the currency used by this number format when formatting currency
* values.
*
* The default implementation throws UnsupportedOperationException.
*
* @return The used currency object, or null.
*
* @throws UnsupportedOperationException If the number format class doesn't
* implement currency formatting.
*
* @since 1.4
*/
public Currency getCurrency()
{
throw new UnsupportedOperationException();
}
/**
* Sets the currency used by this number format when formatting currency
* values.
*
* The default implementation throws UnsupportedOperationException.
*
* @param currency The new currency to be used by this number format.
*
* @throws NullPointerException If currenc is null.
* @throws UnsupportedOperationException If the number format class doesn't
* implement currency formatting.
*
* @since 1.4
*/
public void setCurrency(Currency currency)
{
if (currency == null)
throw new NullPointerException("currency may not be null");
throw new UnsupportedOperationException();
}
}