java.lang.Object | ||
↳ | java.text.Format | |
↳ | java.text.NumberFormat |
Known Direct Subclasses |
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.
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:
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.myString = NumberFormat.getInstance().format(myNumber);
To format a number for a different Locale, specify it in the call toNumberFormat nf = NumberFormat.getInstance(); for (int i = 0; i < myNumber.length; ++i) { output.println(nf.format(myNumber[i]) + "; "); }
getInstance
.
You can also use aNumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
NumberFormat
to parse numbers:
UsemyNumber = nf.parse(myString);
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 and DecimalFormat are 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 index 6) if false, "3456.78" -> 3456.78 (and leaves the parse position just after index 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.
setDecimalSeparatorAlwaysShown : only affects formatting, and only where there might be no digits after the decimal point, such as with a pattern like "#,##0.##", e.g., if true, 3456.00 -> "3,456." if false, 3456.00 -> "3456" This is independent of parsing. If you want parsing to stop at the decimal point, use setParseIntegerOnly.
You can also use forms of the parse
and format
methods with ParsePosition
and FieldPosition
to
allow you to:
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.
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.
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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
NumberFormat.Field | Defines constants that are used as attribute keys in the
AttributedCharacterIterator returned
from NumberFormat.formatToCharacterIterator and as
field identifiers in FieldPosition . |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | FRACTION_FIELD | Field constant used to construct a FieldPosition object. | |||||||||
int | INTEGER_FIELD | Field constant used to construct a FieldPosition object. |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Sole constructor.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Overrides Cloneable
| |||||||||||
Overrides equals
| |||||||||||
Specialization of format.
| |||||||||||
Specialization of format.
| |||||||||||
Specialization of format.
| |||||||||||
Formats a number and appends the resulting text to the given string
buffer.
| |||||||||||
Specialization of format.
| |||||||||||
Returns an array of all locales for which the
get*Instance methods of this class can return
localized instances. | |||||||||||
Gets the currency used by this number format when formatting
currency values.
| |||||||||||
Returns a currency format for the current default locale.
| |||||||||||
Returns a currency format for the specified locale.
| |||||||||||
Returns a general-purpose number format for the specified locale.
| |||||||||||
Returns a general-purpose number format for the current default locale.
| |||||||||||
Returns an integer number format for the specified locale.
| |||||||||||
Returns an integer number format for the current default locale.
| |||||||||||
Returns the maximum number of digits allowed in the fraction portion of a
number.
| |||||||||||
Returns the maximum number of digits allowed in the integer portion of a
number.
| |||||||||||
Returns the minimum number of digits allowed in the fraction portion of a
number.
| |||||||||||
Returns the minimum number of digits allowed in the integer portion of a
number.
| |||||||||||
Returns a general-purpose number format for the current default locale.
| |||||||||||
Returns a general-purpose number format for the specified locale.
| |||||||||||
Returns a percentage format for the current default locale.
| |||||||||||
Returns a percentage format for the specified locale.
| |||||||||||
Gets the
RoundingMode used in this NumberFormat. | |||||||||||
Overrides hashCode
| |||||||||||
Returns true if grouping is used in this format.
| |||||||||||
Returns true if this format will parse numbers as integers only.
| |||||||||||
Parses text from the beginning of the given string to produce a number.
| |||||||||||
Returns a Long if possible (e.g., within the range [Long.MIN_VALUE,
Long.MAX_VALUE] and with no decimals), otherwise a Double.
| |||||||||||
Parses text from a string to produce a
Number . | |||||||||||
Sets the currency used by this number format when formatting
currency values.
| |||||||||||
Set whether or not grouping will be used in this format.
| |||||||||||
Sets the maximum number of digits allowed in the fraction portion of a
number.
| |||||||||||
Sets the maximum number of digits allowed in the integer portion of a
number.
| |||||||||||
Sets the minimum number of digits allowed in the fraction portion of a
number.
| |||||||||||
Sets the minimum number of digits allowed in the integer portion of a
number.
| |||||||||||
Sets whether or not numbers should be parsed as integers only.
| |||||||||||
Sets the
RoundingMode used in this NumberFormat. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.text.Format
| |||||||||||
From class
java.lang.Object
|
Field constant used to construct a FieldPosition object. Signifies that the position of the fraction part of a formatted number should be returned.
Field constant used to construct a FieldPosition object. Signifies that the position of the integer part of a formatted number should be returned.
Sole constructor. (For invocation by subclass constructors, typically implicit.)
Overrides equals
obj | the reference object with which to compare. |
---|
true
if this object is the same as the obj
argument; false
otherwise.Specialization of format.
ArithmeticException | if rounding is needed with rounding mode being set to RoundingMode.UNNECESSARY |
---|
Specialization of format.
ArithmeticException | if rounding is needed with rounding mode being set to RoundingMode.UNNECESSARY |
---|
Specialization of format.
ArithmeticException | if rounding is needed with rounding mode being set to RoundingMode.UNNECESSARY |
---|
Formats a number and appends the resulting text to the given string
buffer.
The number can be of any subclass of Number
.
This implementation extracts the number's value using
longValue()
for all integral type values that
can be converted to long
without loss of information,
including BigInteger
values with a
bit length
of less than 64,
and doubleValue()
for all other types. It
then calls
format(long, java.lang.StringBuffer, java.text.FieldPosition)
or format(double, java.lang.StringBuffer, java.text.FieldPosition)
.
This may result in loss of magnitude information and precision for
BigInteger
and BigDecimal
values.
number | the number to format |
---|---|
toAppendTo | the StringBuffer to which the formatted
text is to be appended |
pos | On input: an alignment field, if desired. On output: the offsets of the alignment field. |
toAppendTo
IllegalArgumentException | if number is
null or not an instance of Number . |
---|---|
NullPointerException | if toAppendTo or
pos is null |
ArithmeticException | if rounding is needed with rounding mode being set to RoundingMode.UNNECESSARY |
Specialization of format.
ArithmeticException | if rounding is needed with rounding mode being set to RoundingMode.UNNECESSARY |
---|
Returns an array of all locales for which the
get*Instance
methods of this class can return
localized instances.
The returned array represents the union of locales supported by the Java
runtime and by installed
NumberFormatProvider
implementations.
It must contain at least a Locale
instance equal to
Locale.US
.
NumberFormat
instances are available.
Gets the currency used by this number format when formatting
currency values. The initial value is derived in a locale dependent
way. The returned value may be null if no valid
currency could be determined and no currency has been set using
setCurrency
.
The default implementation throws
UnsupportedOperationException
.
null
UnsupportedOperationException | if the number format class doesn't implement currency formatting |
---|
Returns a currency format for the current default locale.
Returns a currency format for the specified locale.
Returns a general-purpose number format for the specified locale.
This is the same as calling
getNumberInstance(inLocale)
.
Returns a general-purpose number format for the current default locale.
This is the same as calling
getNumberInstance()
.
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 half-even rounding (see RoundingMode.HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see isParseIntegerOnly
).
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 half-even rounding (see RoundingMode.HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see isParseIntegerOnly
).
Returns the maximum number of digits allowed in the fraction portion of a number.
Returns the maximum number of digits allowed in the integer portion of a number.
Returns the minimum number of digits allowed in the fraction portion of a number.
Returns the minimum number of digits allowed in the integer portion of a number.
Returns a general-purpose number format for the current default locale.
Returns a general-purpose number format for the specified locale.
Returns a percentage format for the current default locale.
Returns a percentage format for the specified locale.
Gets the RoundingMode
used in this NumberFormat.
The default implementation of this method in NumberFormat
always throws UnsupportedOperationException
.
Subclasses which handle different rounding modes should override
this method.
RoundingMode
used for this NumberFormat.UnsupportedOperationException | The default implementation always throws this exception |
---|
Overrides hashCode
Returns true if grouping is used in this format. For example, in the English locale, with grouping on, the number 1234567 might be formatted as "1,234,567". The grouping separator as well as the size of each group is locale dependant and is determined by sub-classes of NumberFormat.
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. Of course, the exact format accepted by the parse operation is locale dependant and determined by sub-classes of NumberFormat.
Parses text from the beginning of the given string to produce a number. The method may not use the entire text of the given string.
See the parse(String, ParsePosition)
method for more information
on number parsing.
source | A String whose beginning should be parsed. |
---|
Number
parsed from the string.ParseException | if the beginning of the specified string cannot be parsed. |
---|
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!
Parses text from a string to produce a Number
.
The method attempts to parse text starting at the index given by
pos
.
If parsing succeeds, then the index of pos
is updated
to the index after the last character used (parsing does not necessarily
use all characters up to the end of the string), and the parsed
number is returned. The updated pos
can be used to
indicate the starting point for the next call to this method.
If an error occurs, then the index of pos
is not
changed, the error index of pos
is set to the index of
the character where the error occurred, and null is returned.
See the parse(String, ParsePosition)
method for more information
on number parsing.
source | A String , part of which should be parsed. |
---|---|
pos | A ParsePosition object with index and error
index information as described above. |
Number
parsed from the string. In case of
error, returns null.NullPointerException | if pos is null.
|
---|
Sets the currency used by this number format when formatting currency values. This does not update the minimum or maximum number of fraction digits used by the number format.
The default implementation throws
UnsupportedOperationException
.
currency | the new currency to be used by this number format |
---|
UnsupportedOperationException | if the number format class doesn't implement currency formatting |
---|---|
NullPointerException | if currency is null |
Set whether or not grouping will be used in this format.
Sets the maximum number of digits allowed in the fraction portion of a number. maximumFractionDigits 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. |
---|
Sets the maximum number of digits allowed in the integer portion of a number. maximumIntegerDigits 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. The concrete subclass may enforce an upper limit to this value appropriate to the numeric type being formatted. |
---|
Sets the minimum number of digits allowed in the fraction portion of a number. minimumFractionDigits must be <= maximumFractionDigits. If the new value for minimumFractionDigits exceeds the current value of maximumFractionDigits, then maximumIntegerDigits 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. The concrete subclass may enforce an upper limit to this value appropriate to the numeric type being formatted. |
---|
Sets the minimum number of digits allowed in the integer portion of a number. minimumIntegerDigits must be <= maximumIntegerDigits. If the new value for minimumIntegerDigits exceeds 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. The concrete subclass may enforce an upper limit to this value appropriate to the numeric type being formatted. |
---|
Sets whether or not numbers should be parsed as integers only.
Sets the RoundingMode
used in this NumberFormat.
The default implementation of this method in NumberFormat always
throws UnsupportedOperationException
.
Subclasses which handle different rounding modes should override
this method.
roundingMode | The RoundingMode to be used |
---|
UnsupportedOperationException | The default implementation always throws this exception |
---|---|
NullPointerException | if roundingMode is null |