NumberFormat
is the abstract base class for all number
formats. This class provides the interface for formatting and parsing
numbers.
NumberFormat
also provides methods for determining
which locales have number formats, and what their names are.
This is an enhanced version of NumberFormat
that
is based on the standard version in the JDK. New or changed functionality
is labeled
NEW or
CHANGED.
NumberFormat
helps you to format and parse numbers for any locale.
Your code can be completely independent of the locale conventions for
decimal points, thousands-separators, or even the particular decimal
digits used, or whether the number format is even decimal.
To format a number for the current Locale, use one of the factory
class methods:
myString = NumberFormat.getInstance().format(myNumber);
If you are formatting multiple numbers, it is
more efficient to get the format and use it multiple times so that
the system doesn't have to fetch the information about the local
language and country conventions multiple times.
NumberFormat nf = NumberFormat.getInstance();
for (int i = 0; i <32a.length; ++i) {
output.println(nf.format(myNumber[i]) + "; ");
}
To format a number for a different Locale, specify it in the
call to
getInstance
.
NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
You can also use a
NumberFormat
to parse numbers:
myNumber = nf.parse(myString);
Use
getInstance
or
getNumberInstance
to get the
normal number format. Use
getIntegerInstance
to get an
integer number format. Use
getCurrencyInstance
to get the
currency number format. And use
getPercentInstance
to get a
format for displaying percentages. With this format, a fraction like
0.53 is displayed as 53%.
You can also control the display of numbers with such methods as
setMinimumFractionDigits
.
If you want even more control over the format or parsing,
or want to give your users more control,
you can try casting the
NumberFormat
you get from the factory methods
to a
DecimalFormat
. This will work for the vast majority
of locales; just remember to put it in a
try
block in case you
encounter an unusual one.
NumberFormat is designed such that some controls
work for formatting and others work for parsing. The following is
the detailed description for each these control methods,
setParseIntegerOnly : only affects parsing, e.g.
if true, "3456.78" -> 3456 (and leaves the parse position just after '6')
if false, "3456.78" -> 3456.78 (and leaves the parse position just after '8')
This is independent of formatting. If you want to not show a decimal point
where there might be no digits after the decimal point, use
setDecimalSeparatorAlwaysShown on DecimalFormat.
You can also use forms of the
parse
and
format
methods with
ParsePosition
and
FieldPosition
to
allow you to:
- progressively parse through pieces of a string
- align the decimal point and other areas
For example, you can align numbers in two ways:
- If you are using a monospaced font with spacing for alignment,
you can pass the
FieldPosition
in your format call, with
field
= INTEGER_FIELD
. On output,
getEndIndex
will be set to the offset between the
last character of the integer and the decimal. Add
(desiredSpaceCount - getEndIndex) spaces at the front of the string.
- If you are using proportional fonts,
instead of padding with spaces, measure the width
of the string in pixels from the start to
getEndIndex
.
Then move the pen by
(desiredPixelWidth - widthToAlignmentPoint) before drawing the text.
It also works where there is no decimal, but possibly additional
characters at the end, e.g., with parentheses in negative
numbers: "(12)" for -12.
Synchronization
Number formats are generally not synchronized. It is recommended to create
separate format instances for each thread. If multiple threads access a format
concurrently, it must be synchronized externally.
DecimalFormat
DecimalFormat is the concrete implementation of NumberFormat, and the
NumberFormat API is essentially an abstraction from DecimalFormat's API.
Refer to DecimalFormat for more information about this API.
see DecimalFormat
see java.text.ChoiceFormat
clone
public Object clone()
Overrides Cloneable.
equals
public boolean equals(Object obj)
Overrides equals. Two NumberFormats are equal if they are of the same class
and the settings (groupingUsed, parseIntegerOnly, maximumIntegerDigits, etc.
are equal.
obj
- the object to compare against
- true if the object is equal to this.
format
public final String format(BigInteger number)
NEW
Convenience method to format a BigInteger.
format
public abstract StringBuffer format(BigInteger number,
StringBuffer toAppendTo,
FieldPosition pos)
NEW
Format a BigInteger.
format
public StringBuffer format(Object number,
StringBuffer toAppendTo,
FieldPosition pos)
CHANGED
Format an object. Change: recognizes BigInteger
and BigDecimal
objects.
format
public final String format(BigDecimal number)
NEW
Convenience method to format an ICU BigDecimal.
format
public abstract StringBuffer format(BigDecimal number,
StringBuffer toAppendTo,
FieldPosition pos)
NEW
Format a BigDecimal.
format
public final String format(CurrencyAmount currAmt)
NEW
Convenience method to format a CurrencyAmount.
format
public StringBuffer format(CurrencyAmount currAmt,
StringBuffer toAppendTo,
FieldPosition pos)
NEW
Format a CurrencyAmount.
format
public final String format(double number)
Specialization of format.
format
public abstract StringBuffer format(double number,
StringBuffer toAppendTo,
FieldPosition pos)
Specialization of format.
format
public final String format(BigDecimal number)
NEW
Convenience method to format a BigDecimal.
format
public abstract StringBuffer format(BigDecimal number,
StringBuffer toAppendTo,
FieldPosition pos)
NEW
Format a BigDecimal.
format
public final String format(long number)
Specialization of format.
format
public abstract StringBuffer format(long number,
StringBuffer toAppendTo,
FieldPosition pos)
Specialization of format.
getAvailableLocales
public static Locale[] getAvailableLocales()
Get the list of Locales for which NumberFormats are available.
getAvailableULocales
public static ULocale[] getAvailableULocales()
Get the list of Locales for which NumberFormats are available.
getCurrency
public Currency getCurrency()
Gets the Currency object used to display currency
amounts. This may be null.
getCurrencyInstance
public static final NumberFormat getCurrencyInstance()
Returns a currency format for the current default locale.
- a number format for currency
getCurrencyInstance
public static NumberFormat getCurrencyInstance(Locale inLocale)
Returns a currency format for the specified locale.
- a number format for currency
getCurrencyInstance
public static NumberFormat getCurrencyInstance(ULocale inLocale)
Returns a currency format for the specified locale.
- a number format for currency
getEffectiveCurrency
protected Currency getEffectiveCurrency()
Returns the currency in effect for this formatter. Subclasses
should override this method as needed. Unlike getCurrency(),
this method should never return null.
getInstance
public static final NumberFormat getInstance()
Returns the default number format for the current default locale.
The default format is one of the styles provided by the other
factory methods: getNumberInstance, getIntegerInstance,
getCurrencyInstance or getPercentInstance.
Exactly which one is locale-dependent.
getInstance
public static NumberFormat getInstance(Locale inLocale)
Returns the default number format for the specified locale.
The default format is one of the styles provided by the other
factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance.
Exactly which one is locale-dependent.
getInstance
public static NumberFormat getInstance(ULocale inLocale)
Returns the default number format for the specified locale.
The default format is one of the styles provided by the other
factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance.
Exactly which one is locale-dependent.
getIntegerInstance
public static final NumberFormat getIntegerInstance()
Returns an integer number format for the current default locale. The
returned number format is configured to round floating point numbers
to the nearest integer using IEEE half-even rounding (see
ROUND_HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see
isParseIntegerOnly
).
- a number format for integer values
getIntegerInstance
public static NumberFormat getIntegerInstance(Locale inLocale)
Returns an integer number format for the specified locale. The
returned number format is configured to round floating point numbers
to the nearest integer using IEEE half-even rounding (see
ROUND_HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see
isParseIntegerOnly
).
inLocale
- the locale for which a number format is needed
- a number format for integer values
getIntegerInstance
public static NumberFormat getIntegerInstance(ULocale inLocale)
Returns an integer number format for the specified locale. The
returned number format is configured to round floating point numbers
to the nearest integer using IEEE half-even rounding (see
ROUND_HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see
isParseIntegerOnly
).
inLocale
- the locale for which a number format is needed
- a number format for integer values
getMaximumFractionDigits
public int getMaximumFractionDigits()
Returns the maximum number of digits allowed in the fraction
portion of a number. The default value is 3, which subclasses
can override. When formatting, the exact behavior when this
value is exceeded is subclass-specific. When parsing, this has
no effect.
- the maximum number of fraction digits
getMaximumIntegerDigits
public int getMaximumIntegerDigits()
Returns the maximum number of digits allowed in the integer portion of a
number. The default value is 40, which subclasses can override.
When formatting, the exact behavior when this value is exceeded is
subclass-specific. When parsing, this has no effect.
- the maximum number of integer digits
getMinimumFractionDigits
public int getMinimumFractionDigits()
Returns the minimum number of digits allowed in the fraction portion of a
number. The default value is 0, which subclasses can override.
When formatting, if this value is not reached, numbers are padded on
the right with the locale-specific '0' character to ensure at least
this number of fraction digits. When parsing, this has no effect.
- the minimum number of fraction digits
getMinimumIntegerDigits
public int getMinimumIntegerDigits()
Returns the minimum number of digits allowed in the integer portion of a
number. The default value is 1, which subclasses can override.
When formatting, if this value is not reached, numbers are padded on the
left with the locale-specific '0' character to ensure at least this
number of integer digits. When parsing, this has no effect.
- the minimum number of integer digits
getNumberInstance
public static final NumberFormat getNumberInstance()
Returns a general-purpose number format for the current default locale.
getNumberInstance
public static NumberFormat getNumberInstance(Locale inLocale)
Returns a general-purpose number format for the specified locale.
getNumberInstance
public static NumberFormat getNumberInstance(ULocale inLocale)
Returns a general-purpose number format for the specified locale.
getPattern
protected static String getPattern(Locale forLocale,
int choice)
ICU 3.4 subclassers should override getPattern(ULocale, int) instead of this method.
Returns the pattern for the provided locale and choice.
forLocale
- the locale of the data.choice
- the pattern format.
getPattern
protected static String getPattern(ULocale forLocale,
int choice)
Returns the pattern for the provided locale and choice.
forLocale
- the locale of the data.choice
- the pattern format.
getPercentInstance
public static final NumberFormat getPercentInstance()
Returns a percentage format for the current default locale.
- a number format for percents
getPercentInstance
public static NumberFormat getPercentInstance(Locale inLocale)
Returns a percentage format for the specified locale.
- a number format for percents
getPercentInstance
public static NumberFormat getPercentInstance(ULocale inLocale)
Returns a percentage format for the specified locale.
- a number format for percents
getScientificInstance
public static final NumberFormat getScientificInstance()
NEW
Returns a scientific format for the current default locale.
- a scientific number format
getScientificInstance
public static NumberFormat getScientificInstance(Locale inLocale)
NEW
Returns a scientific format for the specified locale.
- a scientific number format
getScientificInstance
public static NumberFormat getScientificInstance(ULocale inLocale)
NEW
Returns a scientific format for the specified locale.
- a scientific number format
hashCode
public int hashCode()
Overrides hashCode
isGroupingUsed
public boolean isGroupingUsed()
Returns true if grouping is used in this format. For example, in the
en_US locale, with grouping on, the number 1234567 will be formatted
as "1,234,567". The grouping separator as well as the size of each group
is locale-dependent and is determined by subclasses of NumberFormat.
Grouping affects both parsing and formatting.
isParseIntegerOnly
public boolean isParseIntegerOnly()
Returns true if this format will parse numbers as integers only.
For example in the English locale, with ParseIntegerOnly true, the
string "1234." would be parsed as the integer value 1234 and parsing
would stop at the "." character. The decimal separator accepted
by the parse operation is locale-dependent and determined by the
subclass.
- true if this will parse integers only
parse
public Number parse(String text)
throws ParseException
Parses text from the beginning of the given string to produce a number.
The method might not use the entire text of the given string.
text
- A String whose beginning should be parsed.
- A Number parsed from the string.
parse
public abstract Number parse(String text,
ParsePosition parsePosition)
Returns a Long if possible (e.g., within the range [Long.MIN_VALUE,
Long.MAX_VALUE] and with no decimals), otherwise a Double.
If IntegerOnly is set, will stop at a decimal
point (or equivalent; e.g., for rational numbers "1 2/3", will stop
after the 1).
Does not throw an exception; if no object can be parsed, index is
unchanged!
parseObject
public final Object parseObject(String source,
ParsePosition parsePosition)
registerFactory
public static Object registerFactory(NumberFormat.NumberFormatFactory factory)
Registers a new NumberFormatFactory. The factory is adopted by
the service and must not be modified. The returned object is a
key that can be used to unregister this factory.
factory
- the factory to register
- a key with which to unregister the factory
setCurrency
public void setCurrency(Currency theCurrency)
Sets the Currency object used to display currency
amounts. This takes effect immediately, if this format is a
currency format. If this format is not a currency format, then
the currency object is used if and when this object becomes a
currency format.
theCurrency
- new currency object to use. May be null for
some subclasses.
setGroupingUsed
public void setGroupingUsed(boolean newValue)
Sets whether or not grouping will be used in this format. Grouping
affects both parsing and formatting.
newValue
- true to use grouping.
setMaximumFractionDigits
public void setMaximumFractionDigits(int newValue)
Sets the maximum number of digits allowed in the fraction portion of a
number. This must be >= minimumFractionDigits. If the
new value for maximumFractionDigits is less than the current value
of minimumFractionDigits, then minimumFractionDigits will also be set to
the new value.
newValue
- the maximum number of fraction digits to be shown; if
less than zero, then zero is used. The concrete subclass may enforce an
upper limit to this value appropriate to the numeric type being formatted.
setMaximumIntegerDigits
public void setMaximumIntegerDigits(int newValue)
Sets the maximum number of digits allowed in the integer portion of a
number. This must be >= minimumIntegerDigits. If the
new value for maximumIntegerDigits is less than the current value
of minimumIntegerDigits, then minimumIntegerDigits will also be set to
the new value.
newValue
- the maximum number of integer digits to be shown; if
less than zero, then zero is used. Subclasses might enforce an
upper limit to this value appropriate to the numeric type being formatted.
setMinimumFractionDigits
public void setMinimumFractionDigits(int newValue)
Sets the minimum number of digits allowed in the fraction portion of a
number. This must be <= maximumFractionDigits. If the
new value for minimumFractionDigits exceeds the current value
of maximumFractionDigits, then maximumFractionDigits will also be set to
the new value.
newValue
- the minimum number of fraction digits to be shown; if
less than zero, then zero is used. Subclasses might enforce an
upper limit to this value appropriate to the numeric type being formatted.
setMinimumIntegerDigits
public void setMinimumIntegerDigits(int newValue)
Sets the minimum number of digits allowed in the integer portion of a
number. This must be <= maximumIntegerDigits. If the
new value for minimumIntegerDigits is more than the current value
of maximumIntegerDigits, then maximumIntegerDigits will also be set to
the new value.
newValue
- the minimum number of integer digits to be shown; if
less than zero, then zero is used. Subclasses might enforce an
upper limit to this value appropriate to the numeric type being formatted.
setParseIntegerOnly
public void setParseIntegerOnly(boolean value)
Sets whether or not numbers should be parsed as integers only.
value
- true if this should parse integers only
unregister
public static boolean unregister(Object registryKey)
Unregister the factory or instance associated with this key (obtained from
registerInstance or registerFactory).
registryKey
- a key obtained from registerFactory
- true if the object was successfully unregistered