java.lang.Object | ||
↳ | java.text.Format | |
↳ | java.text.NumberFormat |
Known Direct Subclasses |
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:
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 < a.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 methods such 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. For example, setParseIntegerOnly
only
affects parsing: If set to true
, "3456.78" is parsed as 3456 (and
leaves the parse position just after '6'); if set to false
,
"3456.78" is parsed as 3456.78 (and leaves the parse position just after
'8'). This is independent of formatting.
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 to the front of the string.getEndIndex
. Then move the pen by (desiredPixelWidth -
widthToAlignmentPoint) before drawing the text. This also works where there
is no decimal but possibly additional characters before or after the number,
for example 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.
DecimalFormat
is the concrete implementation of NumberFormat
,
and the NumberFormat
API is essentially an abstraction of
DecimalFormat's
API. Refer to DecimalFormat
for more
information about this API.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
NumberFormat.Field | The instances of this inner class are used as attribute keys and values
in AttributedCharacterIterator that the
formatToCharacterIterator(Object) method returns. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | FRACTION_FIELD | Field constant identifying the fractional part of a number. | |||||||||
int | INTEGER_FIELD | Field constant identifying the integer part of a number. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a new instance of
NumberFormat . |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns a new
NumberFormat with the same properties as this
NumberFormat . | |||||||||||
Compares the specified object to this number format and indicates if
they are equal.
| |||||||||||
Formats the specified long using the rules of this number format.
| |||||||||||
Formats the specified double using the rules of this number format.
| |||||||||||
Formats the specified object as a string using the pattern of this number
format and appends the string to the specified string buffer.
| |||||||||||
Formats the specified double value as a string using the pattern of this
number format and appends the string to the specified string buffer.
| |||||||||||
Formats the specified long value as a string using the pattern of this
number format and appends the string to the specified string buffer.
| |||||||||||
Gets the list of installed locales which support
NumberFormat . | |||||||||||
Returns the currency used by this number format.
| |||||||||||
Returns a
NumberFormat for formatting and parsing currency values
for the default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing currency values
for the specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing numbers for the
default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing numbers for the
specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing integers for
the specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing integers for the
default locale. | |||||||||||
Returns the maximum number of fraction digits that are printed when
formatting.
| |||||||||||
Returns the maximum number of integer digits that are printed when
formatting.
| |||||||||||
Returns the minimum number of fraction digits that are printed when
formatting.
| |||||||||||
Returns the minimum number of integer digits that are printed when
formatting.
| |||||||||||
Returns a
NumberFormat for formatting and parsing numbers for the
specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing numbers for the
default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing percentage
values for the default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing percentage
values for the specified locale. | |||||||||||
Returns an integer hash code for this object.
| |||||||||||
Indicates whether this number format formats and parses numbers using a
grouping separator.
| |||||||||||
Indicates whether this number format only parses integer numbers.
| |||||||||||
Parses a
Number from the specified string using the rules of this
number format. | |||||||||||
Parses a
Number from the specified string starting at the index
specified by position . | |||||||||||
Parses the specified string starting at the index specified by
position . | |||||||||||
Sets the currency used by this number format when formatting currency
values.
| |||||||||||
Sets whether this number format formats and parses numbers using a
grouping separator.
| |||||||||||
Sets the maximum number of fraction digits that are printed when
formatting.
| |||||||||||
Sets the new maximum count of integer digits that are printed when
formatting.
| |||||||||||
Sets the minimum number of fraction digits that are printed when
formatting.
| |||||||||||
Sets the minimum number of integer digits that are printed when
formatting.
| |||||||||||
Specifies if this number format should parse numbers only as integers or
else as any kind of number.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class java.text.Format
| |||||||||||
From class java.lang.Object
|
Field constant identifying the fractional part of a number.
Field constant identifying the integer part of a number.
Returns a new NumberFormat
with the same properties as this
NumberFormat
.
NumberFormat
.Compares the specified object to this number format and indicates if
they are equal. In order to be equal, object
must be an instance
of NumberFormat
with the same pattern and properties.
object | the object to compare with this object. |
---|
true
if the specified object is equal to this number
format; false
otherwise.Formats the specified long using the rules of this number format.
value | the long to format. |
---|
Formats the specified double using the rules of this number format.
value | the double to format. |
---|
Formats the specified object as a string using the pattern of this number format and appends the string to the specified string buffer.
If the field
member of field
contains a value specifying
a format field, then its beginIndex
and endIndex
members
will be updated with the position of the first occurrence of this field
in the formatted text.
object | the object to format, must be a Number . |
---|---|
buffer | the target string buffer to append the formatted number to. |
field | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
IllegalArgumentException | if object is not an instance of Number .
|
---|
Formats the specified double value as a string using the pattern of this number format and appends the string to the specified string buffer.
If the field
member of position
contains a value
specifying a format field, then its beginIndex
and
endIndex
members will be updated with the position of the first
occurrence of this field in the formatted text.
value | the double to format. |
---|---|
buffer | the target string buffer to append the formatted double value to. |
field | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
Formats the specified long value as a string using the pattern of this number format and appends the string to the specified string buffer.
If the field
member of position
contains a value
specifying a format field, then its beginIndex
and
endIndex
members will be updated with the position of the first
occurrence of this field in the formatted text.
value | the long to format. |
---|---|
buffer | the target string buffer to append the formatted long value to. |
field | on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text. |
Gets the list of installed locales which support NumberFormat
.
Returns the currency used by this number format.
This implementation throws UnsupportedOperationException
,
concrete subclasses should override this method if they support currency
formatting.
null
.Returns a NumberFormat
for formatting and parsing currency values
for the default locale.
NumberFormat
for handling currency values.
Returns a NumberFormat
for formatting and parsing currency values
for the specified locale.
locale | the locale to use. |
---|
NumberFormat
for handling currency values.
Returns a NumberFormat
for formatting and parsing numbers for the
default locale.
NumberFormat
for handling Number
objects.
Returns a NumberFormat
for formatting and parsing numbers for the
specified locale.
locale | the locale to use. |
---|
NumberFormat
for handling Number
objects.
Returns a NumberFormat
for formatting and parsing integers for
the specified locale.
locale | the locale to use. |
---|
NumberFormat
for handling integers.
Returns a NumberFormat
for formatting and parsing integers for the
default locale.
NumberFormat
for handling integers.
Returns the maximum number of fraction digits that are printed when formatting. If the maximum is less than the number of fraction digits, the least significant digits are truncated.
Returns the maximum number of integer digits that are printed when formatting. If the maximum is less than the number of integer digits, the most significant digits are truncated.
Returns the minimum number of fraction digits that are printed when formatting.
Returns the minimum number of integer digits that are printed when formatting.
Returns a NumberFormat
for formatting and parsing numbers for the
specified locale.
locale | the locale to use. |
---|
NumberFormat
for handling Number
objects.
Returns a NumberFormat
for formatting and parsing numbers for the
default locale.
NumberFormat
for handling Number
objects.
Returns a NumberFormat
for formatting and parsing percentage
values for the default locale.
NumberFormat
for handling percentage values.
Returns a NumberFormat
for formatting and parsing percentage
values for the specified locale.
locale | the locale to use. |
---|
NumberFormat
for handling percentage values.
Returns an integer hash code for this object. By contract, any two
objects for which equals(Object)
returns true
must return
the same hash code value. This means that subclasses of Object
usually override both methods or neither method.
Indicates whether this number format formats and parses numbers using a grouping separator.
true
if a grouping separator is used; false
otherwise.
Indicates whether this number format only parses integer numbers. Parsing stops if a decimal separator is encountered.
true
if this number format only parses integers,
false
if if parsese integers as well as fractions.
Parses a Number
from the specified string using the rules of this
number format.
string | the string to parse. |
---|
Number
resulting from the parsing.ParseException | if an error occurs during parsing. |
---|
Parses a Number
from the specified string starting at the index
specified by position
. If the string is successfully parsed then
the index of the ParsePosition
is updated to the index following
the parsed text. On error, the index is unchanged and the error index of
ParsePosition
is set to the index where the error occurred.
string | the string to parse. |
---|---|
position | input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred. |
Number
resulting from the parse or null
if
there is an error.
Parses the specified string starting at the index specified by
position
. If the string is successfully parsed then the index of
the ParsePosition
is updated to the index following the parsed
text. On error, the index is unchanged and the error index of
ParsePosition
is set to the index where the error occurred.
string | the string to parse. |
---|---|
position | input/output parameter, specifies the start index in
string from where to start parsing. If parsing is
successful, it is updated with the index following the parsed
text; on error, the index is unchanged and the error index is
set to the index where the error occurred. |
null
if there is
an error.
Sets the currency used by this number format when formatting currency values. The min and max fraction digits remain the same.
This implementation throws UnsupportedOperationException
,
concrete subclasses should override this method if they support currency
formatting.
currency | the new currency. |
---|
Sets whether this number format formats and parses numbers using a grouping separator.
value | true if a grouping separator is used; false
otherwise.
|
---|
Sets the maximum number of fraction digits that are printed when formatting. If the maximum is less than the number of fraction digits, the least significant digits are truncated.
value | the maximum number of fraction digits. |
---|
Sets the new maximum count of integer digits that are printed when formatting. If the maximum is less than the number of integer digits, the most significant digits are truncated.
value | the new maximum number of integer numerals for display. |
---|
Sets the minimum number of fraction digits that are printed when formatting.
value | the minimum number of fraction digits. |
---|
Sets the minimum number of integer digits that are printed when formatting.
value | the minimum number of integer digits. |
---|
Specifies if this number format should parse numbers only as integers or
else as any kind of number. If this method is called with a true
value then subsequent parsing attempts will stop if a decimal separator
is encountered.
value | true to only parse integers, false to parse
integers as well as fractions.
|
---|