com.ibm.icu.text
public abstract class NumberFormat extends UFormat
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:
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 < a.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 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:
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.
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.ChoiceFormatUNKNOWN: ICU 2.0
Nested Class Summary | |
---|---|
static class | NumberFormat.Field
[Spark/CDL] The instances of this inner class are used as attribute keys and values
in AttributedCharacterIterator that
NumberFormat.formatToCharacterIterator() method returns.
|
abstract static class | NumberFormat.NumberFormatFactory
A NumberFormatFactory is used to register new number formats. |
abstract static class | NumberFormat.SimpleNumberFormatFactory
A NumberFormatFactory that supports a single locale. |
Field Summary | |
---|---|
static int | FRACTION_FIELD
Field constant used to construct a FieldPosition object. |
static int | INTEGER_FIELD
Field constant used to construct a FieldPosition object. |
Constructor Summary | |
---|---|
NumberFormat()
Empty constructor. |
Method Summary | |
---|---|
Object | clone()
Overrides Cloneable. |
boolean | equals(Object obj)
Overrides equals. |
StringBuffer | format(Object number, StringBuffer toAppendTo, FieldPosition pos)
CHANGED
Format an object. |
String | format(double number)
Specialization of format. |
String | format(long number)
Specialization of format. |
String | format(BigInteger number)
NEW
Convenience method to format a BigInteger. |
String | format(BigDecimal number)
NEW
Convenience method to format a BigDecimal. |
String | format(BigDecimal number)
NEW
Convenience method to format an ICU BigDecimal. |
String | format(CurrencyAmount currAmt)
NEW
Convenience method to format a CurrencyAmount. |
abstract StringBuffer | format(double number, StringBuffer toAppendTo, FieldPosition pos)
Specialization of format. |
abstract StringBuffer | format(long number, StringBuffer toAppendTo, FieldPosition pos)
Specialization of format. |
abstract StringBuffer | format(BigInteger number, StringBuffer toAppendTo, FieldPosition pos)
NEW
Format a BigInteger. |
abstract StringBuffer | format(BigDecimal number, StringBuffer toAppendTo, FieldPosition pos)
NEW
Format a BigDecimal. |
abstract StringBuffer | format(BigDecimal number, StringBuffer toAppendTo, FieldPosition pos)
NEW
Format a BigDecimal. |
StringBuffer | format(CurrencyAmount currAmt, StringBuffer toAppendTo, FieldPosition pos)
NEW
Format a CurrencyAmount. |
static Locale[] | getAvailableLocales()
Get the list of Locales for which NumberFormats are available. |
static ULocale[] | getAvailableULocales()
Get the list of Locales for which NumberFormats are available. |
Currency | getCurrency()
Gets the Currency object used to display currency
amounts. |
static NumberFormat | getCurrencyInstance()
Returns a currency format for the current default locale. |
static NumberFormat | getCurrencyInstance(Locale inLocale)
Returns a currency format for the specified locale. |
static NumberFormat | getCurrencyInstance(ULocale inLocale)
Returns a currency format for the specified locale. |
protected Currency | getEffectiveCurrency()
Returns the currency in effect for this formatter. |
static NumberFormat | getInstance()
Returns the default number format for the current default locale.
|
static NumberFormat | getInstance(Locale inLocale)
Returns the default number format for the specified locale.
|
static NumberFormat | getInstance(ULocale inLocale)
Returns the default number format for the specified locale.
|
static NumberFormat | getIntegerInstance()
Returns an integer number format for the current default locale. |
static NumberFormat | getIntegerInstance(Locale inLocale)
Returns an integer number format for the specified locale. |
static NumberFormat | getIntegerInstance(ULocale inLocale)
Returns an integer number format for the specified locale. |
int | getMaximumFractionDigits()
Returns the maximum number of digits allowed in the fraction
portion of a number. |
int | getMaximumIntegerDigits()
Returns the maximum number of digits allowed in the integer portion of a
number. |
int | getMinimumFractionDigits()
Returns the minimum number of digits allowed in the fraction portion of a
number. |
int | getMinimumIntegerDigits()
Returns the minimum number of digits allowed in the integer portion of a
number. |
static NumberFormat | getNumberInstance()
Returns a general-purpose number format for the current default locale. |
static NumberFormat | getNumberInstance(Locale inLocale)
Returns a general-purpose number format for the specified locale. |
static NumberFormat | getNumberInstance(ULocale inLocale)
Returns a general-purpose number format for the specified locale. |
protected static String | getPattern(Locale forLocale, int choice)
Returns the pattern for the provided locale and choice. |
protected static String | getPattern(ULocale forLocale, int choice)
Returns the pattern for the provided locale and choice. |
static NumberFormat | getPercentInstance()
Returns a percentage format for the current default locale. |
static NumberFormat | getPercentInstance(Locale inLocale)
Returns a percentage format for the specified locale. |
static NumberFormat | getPercentInstance(ULocale inLocale)
Returns a percentage format for the specified locale. |
static NumberFormat | getScientificInstance()
NEW
Returns a scientific format for the current default locale. |
static NumberFormat | getScientificInstance(Locale inLocale)
NEW
Returns a scientific format for the specified locale. |
static NumberFormat | getScientificInstance(ULocale inLocale)
NEW
Returns a scientific format for the specified locale. |
int | hashCode()
Overrides hashCode |
boolean | isGroupingUsed()
Returns true if grouping is used in this format. |
boolean | isParseIntegerOnly()
Returns true if this format will parse numbers as integers only.
|
boolean | isParseStrict()
Return whether strict parsing is in effect. |
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.
|
Number | parse(String text)
Parses text from the beginning of the given string to produce a number.
|
Object | parseObject(String source, ParsePosition parsePosition) |
static Object | registerFactory(NumberFormat.NumberFormatFactory factory)
Registers a new NumberFormatFactory. |
void | setCurrency(Currency theCurrency)
Sets the Currency object used to display currency
amounts. |
void | setGroupingUsed(boolean newValue)
Sets whether or not grouping will be used in this format. |
void | setMaximumFractionDigits(int newValue)
Sets the maximum number of digits allowed in the fraction portion of a
number. |
void | setMaximumIntegerDigits(int newValue)
Sets the maximum number of digits allowed in the integer portion of a
number. |
void | setMinimumFractionDigits(int newValue)
Sets the minimum number of digits allowed in the fraction portion of a
number. |
void | setMinimumIntegerDigits(int newValue)
Sets the minimum number of digits allowed in the integer portion of a
number. |
void | setParseIntegerOnly(boolean value)
Sets whether or not numbers should be parsed as integers only. |
void | setParseStrict(boolean value)
Sets whether strict parsing is in effect. |
static boolean | unregister(Object registryKey)
Unregister the factory or instance associated with this key (obtained from
registerInstance or registerFactory). |
See Also: java.text.FieldPosition
UNKNOWN: ICU 2.0
See Also: java.text.FieldPosition
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.6
UNKNOWN: ICU 2.0
Parameters: obj the object to compare against
Returns: true if the object is equal to this.
UNKNOWN: ICU 2.0
BigInteger
and BigDecimal
objects.UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object)
UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object)
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
UNKNOWN: ICU 3.0
See Also: java.text.Format#format(Object, StringBuffer, FieldPosition)
UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object, StringBuffer, FieldPosition)
UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object, StringBuffer, FieldPosition)
UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object, StringBuffer, FieldPosition)
UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object, StringBuffer, FieldPosition)
UNKNOWN: ICU 2.0
See Also: java.text.Format#format(Object, StringBuffer, FieldPosition)
UNKNOWN: ICU 3.0
Returns: the available locales
UNKNOWN: ICU 2.0
Returns: the available locales
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
UNKNOWN: ICU 2.6
Returns: a number format for currency
UNKNOWN: ICU 2.0
Returns: a number format for currency
UNKNOWN: ICU 2.0
Returns: a number format for currency
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
Deprecated: This API is ICU internal only.
Returns the currency in effect for this formatter. Subclasses should override this method as needed. Unlike getCurrency(), this method should never return null.Returns: a non-null Currency
UNKNOWN:
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
Returns: a number format for integer values
UNKNOWN: ICU 2.0
Parameters: inLocale the locale for which a number format is needed
Returns: a number format for integer values
UNKNOWN: ICU 2.0
Parameters: inLocale the locale for which a number format is needed
Returns: a number format for integer values
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
Returns: the maximum number of fraction digits
See Also: NumberFormat
UNKNOWN: ICU 2.0
Returns: the maximum number of integer digits
See Also: NumberFormat
UNKNOWN: ICU 2.0
Returns: the minimum number of fraction digits
See Also: NumberFormat
UNKNOWN: ICU 2.0
Returns: the minimum number of integer digits
See Also: NumberFormat
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
Deprecated: ICU 3.4 subclassers should override getPattern(ULocale, int) instead of this method.
Returns the pattern for the provided locale and choice.Parameters: forLocale the locale of the data. choice the pattern format.
Returns: the pattern
Parameters: forLocale the locale of the data. choice the pattern format.
Returns: the pattern
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
Returns: a number format for percents
UNKNOWN: ICU 2.0
Returns: a number format for percents
UNKNOWN: ICU 2.0
Returns: a number format for percents
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
Returns: a scientific number format
UNKNOWN: ICU 2.0
Returns: a scientific number format
UNKNOWN: ICU 2.0
Returns: a scientific number format
UNKNOWN: ICU 3.2 This API might change or be removed in a future release.
UNKNOWN: ICU 2.0
Returns: true if grouping is used
See Also: NumberFormat
UNKNOWN: ICU 2.0
Returns: true if this will parse integers only
UNKNOWN: ICU 2.0
Returns: true if strict parsing is in effect
See Also: NumberFormat
UNKNOWN: ICU 3.6 This API might change or be removed in a future release.
See Also: NumberFormat java.text.Format#parseObject(String, ParsePosition)
UNKNOWN: ICU 2.0
Parameters: text A String whose beginning should be parsed.
Returns: A Number parsed from the string.
Throws: ParseException if the beginning of the specified string cannot be parsed.
See Also: NumberFormat
UNKNOWN: ICU 2.0
UNKNOWN: ICU 2.0
Parameters: factory the factory to register
Returns: a key with which to unregister the factory
UNKNOWN: ICU 2.6
Parameters: theCurrency new currency object to use. May be null for some subclasses.
UNKNOWN: ICU 2.6
Parameters: newValue true to use grouping.
See Also: NumberFormat
UNKNOWN: ICU 2.0
Parameters: 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.
See Also: NumberFormat
UNKNOWN: ICU 2.0
Parameters: 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.
See Also: NumberFormat
UNKNOWN: ICU 2.0
Parameters: 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.
See Also: NumberFormat
UNKNOWN: ICU 2.0
Parameters: 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.
See Also: NumberFormat
UNKNOWN: ICU 2.0
Parameters: value true if this should parse integers only
See Also: NumberFormat
UNKNOWN: ICU 2.0
Parameters: value True to enable strict parsing. Default is false.
See Also: NumberFormat
UNKNOWN: ICU 3.6 This API might change or be removed in a future release.
Parameters: registryKey a key obtained from registerFactory
Returns: true if the object was successfully unregistered
UNKNOWN: ICU 2.6