| 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.
Developers
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.
| |||||||||||
Returns true if 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.
Non-integer percentages will be rounded according to the rounding mode,
so by default 0.142 will be 14% but 0.148 will be 15%. If you want fractional
percentages, use setMaximumFractionDigits(int).
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.
Non-integer percentages will be rounded according to the rounding mode,
so by default 0.142 will be 14% but 0.148 will be 15%. If you want fractional
percentages, use setMaximumFractionDigits(int).
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.
Returns true if this number format only parses integer numbers. Parsing stops if a decimal separator is encountered.
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.