|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object java.text.Format com.ibm.icu.text.UFormat com.ibm.icu.text.NumberFormat
public abstract class NumberFormat
[icu enhancement] ICU's replacement for java.text.NumberFormat
. Methods, fields, and other functionality specific to ICU are labeled '[icu]'.
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 < 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%.
Starting from ICU 4.2, you can use getInstance() by passing in a 'style' as parameter to get the correct instance. For example, use getInstance(...NUMBERSTYLE) to get the normal number format, getInstance(...PERCENTSTYLE) to get a format for displaying percentage, getInstance(...SCIENTIFICSTYLE) to get a format for displaying scientific number, getInstance(...INTEGERSTYLE) to get an integer number format, getInstance(...CURRENCYSTYLE) to get the currency number format, in which the currency is represented by its symbol, for example, "$3.00". getInstance(...ISOCURRENCYSTYLE) to get the currency number format, in which the currency is represented by its ISO code, for example "USD3.00". getInstance(...PLURALCURRENCYSTYLE) to get the currency number format, in which the currency is represented by its full name in plural format, for example, "3.00 US dollars" or "1.00 US dollar".
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.ChoiceFormat
Nested Class Summary | |
---|---|
static class |
NumberFormat.Field
The instances of this inner class are used as attribute keys and values in AttributedCharacterIterator that NumberFormat.formatToCharacterIterator() method returns. |
static class |
NumberFormat.NumberFormatFactory
A NumberFormatFactory is used to register new number formats. |
static class |
NumberFormat.SimpleNumberFormatFactory
A NumberFormatFactory that supports a single locale. |
Field Summary | |
---|---|
static int |
CURRENCYSTYLE
[icu] Constant to specify currency style of format which uses currency symbol to represent currency, for example: "$3.00". |
static int |
FRACTION_FIELD
Field constant used to construct a FieldPosition object. |
static int |
INTEGER_FIELD
Field constant used to construct a FieldPosition object. |
static int |
INTEGERSTYLE
[icu] Constant to specify a integer number style format. |
static int |
ISOCURRENCYSTYLE
[icu] Constant to specify currency style of format which uses currency ISO code to represent currency, for example: "USD3.00". |
static int |
NUMBERSTYLE
[icu] Constant to specify normal number style of format. |
static int |
PERCENTSTYLE
[icu] Constant to specify a style of format to display percent. |
static int |
PLURALCURRENCYSTYLE
[icu] Constant to specify currency style of format which uses currency long name with plural format to represent currency, for example, "3.00 US Dollars". |
static int |
SCIENTIFICSTYLE
[icu] Constant to specify a style of format to display scientific number. |
Constructor Summary | |
---|---|
NumberFormat()
Empty constructor. |
Method Summary | |
---|---|
Object |
clone()
Overrides clone. |
boolean |
equals(Object obj)
Overrides equals. |
String |
format(BigDecimal number)
Convenience method to format a BigDecimal. |
String |
format(BigDecimal number)
[icu] Convenience method to format an ICU BigDecimal. |
abstract StringBuffer |
format(BigDecimal number,
StringBuffer toAppendTo,
FieldPosition pos)
[icu] Formats a BigDecimal. |
abstract StringBuffer |
format(BigDecimal number,
StringBuffer toAppendTo,
FieldPosition pos)
[icu] Formats an ICU BigDecimal. |
String |
format(BigInteger number)
[icu] Convenience method to format a BigInteger. |
abstract StringBuffer |
format(BigInteger number,
StringBuffer toAppendTo,
FieldPosition pos)
[icu] Formats a BigInteger. |
String |
format(CurrencyAmount currAmt)
[icu] Convenience method to format a CurrencyAmount. |
StringBuffer |
format(CurrencyAmount currAmt,
StringBuffer toAppendTo,
FieldPosition pos)
[icu] Formats a CurrencyAmount. |
String |
format(double number)
Specialization of format. |
abstract StringBuffer |
format(double number,
StringBuffer toAppendTo,
FieldPosition pos)
Specialization of format. |
String |
format(long number)
Specialization of format. |
abstract StringBuffer |
format(long number,
StringBuffer toAppendTo,
FieldPosition pos)
Specialization of format. |
StringBuffer |
format(Object number,
StringBuffer toAppendTo,
FieldPosition pos)
Formats a number and appends the resulting text to the given string buffer. |
static Locale[] |
getAvailableLocales()
Returns the list of Locales for which NumberFormats are available. |
static ULocale[] |
getAvailableULocales()
[icu] Returns the list of Locales for which NumberFormats are available. |
Currency |
getCurrency()
Returns 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)
[icu] Returns a currency format for the specified locale. |
protected Currency |
getEffectiveCurrency()
Deprecated. This API is ICU internal only. |
static NumberFormat |
getInstance()
Returns the default number format for the current default locale. |
static NumberFormat |
getInstance(int style)
[icu] Returns a specific style number format for default locale. |
static NumberFormat |
getInstance(Locale inLocale)
Returns the default number format for the specified locale. |
static NumberFormat |
getInstance(Locale inLocale,
int style)
[icu] Returns a specific style number format for a specific locale. |
static NumberFormat |
getInstance(ULocale inLocale)
[icu] Returns the default number format for the specified locale. |
static NumberFormat |
getInstance(ULocale desiredLocale,
int choice)
Returns a specific style number format for a specific 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)
[icu] 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)
[icu] Returns a general-purpose number format for the specified locale. |
protected static String |
getPattern(Locale forLocale,
int choice)
Deprecated. ICU 3.4 subclassers should override getPattern(ULocale, int) instead of this method. |
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)
[icu] Returns a percentage format for the specified locale. |
int |
getRoundingMode()
Returns the rounding mode used in this NumberFormat. |
static NumberFormat |
getScientificInstance()
[icu] Returns a scientific format for the current default locale. |
static NumberFormat |
getScientificInstance(Locale inLocale)
[icu] Returns a scientific format for the specified locale. |
static NumberFormat |
getScientificInstance(ULocale inLocale)
[icu] 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()
[icu] Returns whether strict parsing is in effect. |
Number |
parse(String text)
Parses text from the beginning of the given string to produce a number. |
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. |
Object |
parseObject(String source,
ParsePosition parsePosition)
Parses text from a string to produce a number. |
static Object |
registerFactory(NumberFormat.NumberFormatFactory factory)
[icu] 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)
[icu] Sets whether strict parsing is in effect. |
void |
setRoundingMode(int roundingMode)
Set the rounding mode used in this NumberFormat. |
static boolean |
unregister(Object registryKey)
[icu] Unregisters the factory or instance associated with this key (obtained from registerInstance or registerFactory). |
Methods inherited from class com.ibm.icu.text.UFormat |
---|
getLocale |
Methods inherited from class java.text.Format |
---|
format, formatToCharacterIterator, parseObject |
Methods inherited from class java.lang.Object |
---|
finalize, getClass, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int NUMBERSTYLE
public static final int CURRENCYSTYLE
public static final int PERCENTSTYLE
public static final int SCIENTIFICSTYLE
public static final int INTEGERSTYLE
public static final int ISOCURRENCYSTYLE
public static final int PLURALCURRENCYSTYLE
public static final int INTEGER_FIELD
FieldPosition
,
Constant Field Valuespublic static final int FRACTION_FIELD
FieldPosition
,
Constant Field ValuesConstructor Detail |
---|
public NumberFormat()
Method Detail |
---|
public StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)
[icu] Note: recognizes BigInteger
and BigDecimal
objects.
format
in class Format
Format.format(Object, StringBuffer, FieldPosition)
public final Object parseObject(String source, ParsePosition parsePosition)
parseObject
in class Format
source
- the String to parseparsePosition
- the position at which to start the parse
NumberFormat.parseObject(String, ParsePosition)
public final String format(double number)
Format.format(Object)
public final String format(long number)
Format.format(Object)
public final String format(BigInteger number)
public final String format(BigDecimal number)
public final String format(BigDecimal number)
public final String format(CurrencyAmount currAmt)
public abstract StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition pos)
Format.format(Object, StringBuffer, FieldPosition)
public abstract StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition pos)
Format.format(Object, StringBuffer, FieldPosition)
public abstract StringBuffer format(BigInteger number, StringBuffer toAppendTo, FieldPosition pos)
Format.format(Object, StringBuffer, FieldPosition)
public abstract StringBuffer format(BigDecimal number, StringBuffer toAppendTo, FieldPosition pos)
Format.format(Object, StringBuffer, FieldPosition)
public abstract StringBuffer format(BigDecimal number, StringBuffer toAppendTo, FieldPosition pos)
Format.format(Object, StringBuffer, FieldPosition)
public StringBuffer format(CurrencyAmount currAmt, StringBuffer toAppendTo, FieldPosition pos)
Format.format(Object, StringBuffer, FieldPosition)
public abstract Number parse(String text, ParsePosition parsePosition)
isParseIntegerOnly()
,
Format.parseObject(String, ParsePosition)
public Number parse(String text) throws ParseException
text
- A String whose beginning should be parsed.
ParseException
- if the beginning of the specified string
cannot be parsed.format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)
public boolean isParseIntegerOnly()
public void setParseIntegerOnly(boolean value)
value
- true if this should parse integers onlyisParseIntegerOnly()
public void setParseStrict(boolean value)
value
- True to enable strict parsing. Default is false.isParseStrict()
public boolean isParseStrict()
setParseStrict(boolean)
public static final NumberFormat getInstance()
public static NumberFormat getInstance(Locale inLocale)
public static NumberFormat getInstance(ULocale inLocale)
public static final NumberFormat getInstance(int style)
style
- number format stylepublic static NumberFormat getInstance(Locale inLocale, int style)
inLocale
- the specific locale.style
- number format stylepublic static final NumberFormat getNumberInstance()
public static NumberFormat getNumberInstance(Locale inLocale)
public static NumberFormat getNumberInstance(ULocale inLocale)
public static final NumberFormat getIntegerInstance()
ROUND_HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see isParseIntegerOnly
).
public static NumberFormat getIntegerInstance(Locale inLocale)
ROUND_HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see isParseIntegerOnly
).
inLocale
- the locale for which a number format is needed
public static NumberFormat getIntegerInstance(ULocale inLocale)
ROUND_HALF_EVEN
) for formatting,
and to parse only the integer part of an input string (see isParseIntegerOnly
).
inLocale
- the locale for which a number format is needed
public static final NumberFormat getCurrencyInstance()
public static NumberFormat getCurrencyInstance(Locale inLocale)
public static NumberFormat getCurrencyInstance(ULocale inLocale)
public static final NumberFormat getPercentInstance()
public static NumberFormat getPercentInstance(Locale inLocale)
public static NumberFormat getPercentInstance(ULocale inLocale)
public static final NumberFormat getScientificInstance()
public static NumberFormat getScientificInstance(Locale inLocale)
public static NumberFormat getScientificInstance(ULocale inLocale)
public static Locale[] getAvailableLocales()
public static ULocale[] getAvailableULocales()
public static Object registerFactory(NumberFormat.NumberFormatFactory factory)
factory
- the factory to register
public static boolean unregister(Object registryKey)
registryKey
- a key obtained from registerFactory
public int hashCode()
hashCode
in class Object
public boolean equals(Object obj)
equals
in class Object
obj
- the object to compare against
public Object clone()
clone
in class Format
public boolean isGroupingUsed()
setGroupingUsed(boolean)
public void setGroupingUsed(boolean newValue)
newValue
- true to use grouping.isGroupingUsed()
public int getMaximumIntegerDigits()
setMaximumIntegerDigits(int)
public void setMaximumIntegerDigits(int newValue)
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.getMaximumIntegerDigits()
public int getMinimumIntegerDigits()
setMinimumIntegerDigits(int)
public void setMinimumIntegerDigits(int newValue)
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.getMinimumIntegerDigits()
public int getMaximumFractionDigits()
setMaximumFractionDigits(int)
public void setMaximumFractionDigits(int newValue)
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.getMaximumFractionDigits()
public int getMinimumFractionDigits()
setMinimumFractionDigits(int)
public void setMinimumFractionDigits(int newValue)
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.getMinimumFractionDigits()
public void setCurrency(Currency theCurrency)
theCurrency
- new currency object to use. May be null for
some subclasses.public Currency getCurrency()
protected Currency getEffectiveCurrency()
public int getRoundingMode()
UnsupportedOperationException
.
BigDecimal.ROUND_UP
and BigDecimal.ROUND_UNNECESSARY
.setRoundingMode(int)
public void setRoundingMode(int roundingMode)
UnsupportedOperationException
.
roundingMode
- A rounding mode, between
BigDecimal.ROUND_UP
and
BigDecimal.ROUND_UNNECESSARY
.getRoundingMode()
public static NumberFormat getInstance(ULocale desiredLocale, int choice)
desiredLocale
- the specific locale.choice
- number format style
IllegalArgumentException
- if choice is not one of
NUMBERSTYLE, CURRENCYSTYLE,
PERCENTSTYLE, SCIENTIFICSTYLE,
INTEGERSTYLE,
ISOCURRENCYSTYLE, PLURALCURRENCYSTYLE,protected static String getPattern(Locale forLocale, int choice)
forLocale
- the locale of the data.choice
- the pattern format.
protected static String getPattern(ULocale forLocale, int choice)
forLocale
- the locale of the data.choice
- the pattern format.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |