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 default number
format. Use getIntegerInstance()
to get an integer number format,
getCurrencyInstance()
to get the currency number format, and
getPercentInstance()
to get a format for displaying percentages.
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. |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Used by subclasses.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns a new
NumberFormat with the same properties. | |||||||||||
Compares the specified object to this number format and indicates if
they are equal.
| |||||||||||
Formats the specified long value as a string using the pattern of this
number format and appends the string to the specified string buffer.
| |||||||||||
Formats the specified long using the rules of this number format.
| |||||||||||
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 a number into a supplied buffer.
| |||||||||||
Formats the specified double using the rules of this number format.
| |||||||||||
Returns an array of locales for which custom
NumberFormat instances
are available. | |||||||||||
Returns the currency used by this number format.
| |||||||||||
Returns a
NumberFormat for formatting and parsing currency values
for the user's 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
specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing numbers for the
default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing integers for
the specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing integers for the
user's 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
user's default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing numbers for the
specified locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing percentage
values for the user's default locale. | |||||||||||
Returns a
NumberFormat for formatting and parsing percentage
values for the given locale . | |||||||||||
Returns the
RoundingMode used by this NumberFormat . | |||||||||||
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.
| |||||||||||
Sets the
RoundingMode used by this NumberFormat . |
[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.
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 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. |
Formats the specified long using the rules of this number format.
value | the long to format. |
---|
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 a number into a supplied buffer.
The number must be a subclass of Number
. Instances of Byte
, Short
,
Integer
, and Long
have Number.longValue
invoked, as do instances of
BigInteger
where BigInteger.bitLength
returns less than 64. All other
values have Number.doubleValue
invoked instead.
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 using the rules of this number format.
value | the double to format. |
---|
Returns an array of locales for which custom NumberFormat
instances
are available.
Note that Android does not support user-supplied locale service providers.
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 user's default locale.
See "Be wary of 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
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 integers for
the specified locale.
locale | the locale to use. |
---|
NumberFormat
for handling integers.
Returns a NumberFormat
for formatting and parsing integers for the
user's default locale.
See "Be wary of 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
user's default locale.
See "Be wary of 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 percentage
values for the user's default locale.
See "Be wary of the default locale".
The NumberFormat
returned by this method should only be used
to format floating-point numbers typically between 0 and 1 (with 1 being 100%).
A value such as 0.53 will be treated as 53%, but 53.0 (or the integer 53) will be
treated as 5,300%, which is rarely what you intended.
Returns a NumberFormat
for formatting and parsing percentage
values for the given locale
.
The NumberFormat
returned by this method should only be used
to format floating-point numbers typically between 0 and 1 (with 1 being 100%).
A value such as 0.53 will be treated as 53%, but 53.0 (or the integer 53) will be
treated as 5,300%, which is rarely what you intended.
Returns the RoundingMode
used by this NumberFormat
. The default
implementation in NumberFormat
throws UnsupportedOperationException
.
Subclasses for which a rounding mode is meaningful are expected to override this method.
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.
Note that hash values must not change over time unless information used in equals comparisons also changes.
See Writing a correct
hashCode
method
if you intend implementing your own hashCode
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.
|
---|
Sets the RoundingMode
used by this NumberFormat
. The default
implementation in NumberFormat
throws UnsupportedOperationException
.
Subclasses for which a rounding mode is meaningful are expected to override this method.