public class DecimalFormat extends NumberFormat
DecimalFormat is a concrete subclass of NumberFormat that formats
decimal numbers. It has a variety of features designed to make it possible to parse and
format numbers in any locale, including support for Western, Arabic, or Indic digits.
It also supports different flavors of numbers, including integers ("123"), fixed-point
numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency
amounts ("$123.00", "USD123.00", "123.00 US dollars"). All of these flavors can be
easily localized.
To obtain a NumberFormat for a specific locale (including the default
locale) call one of NumberFormat's factory methods such as NumberFormat.getInstance(). Do not call the DecimalFormat constructors
directly, unless you know what you are doing, since the NumberFormat factory
methods may return subclasses other than DecimalFormat. If you need to
customize the format object, do something like this:
NumberFormat f = NumberFormat.getInstance(loc);
if (f instanceof DecimalFormat) {
((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true);
}Example Usage Print out a number using the localized number, currency, and percent format for each locale.
Locale[] locales = NumberFormat.getAvailableLocales();
double myNumber = -1234.56;
NumberFormat format;
for (int j=0; j<3; ++j) {
System.out.println("FORMAT");
for (int i = 0; i < locales.length; ++i) {
if (locales[i].getCountry().length() == 0) {
// Skip language-only locales
continue;
}
System.out.print(locales[i].getDisplayName());
switch (j) {
case 0:
format = NumberFormat.getInstance(locales[i]); break;
case 1:
format = NumberFormat.getCurrencyInstance(locales[i]); break;
default:
format = NumberFormat.getPercentInstance(locales[i]); break;
}
try {
// Assume format is a DecimalFormat
System.out.print(": " + ((DecimalFormat) format).toPattern()
+ " -> " + form.format(myNumber));
} catch (Exception e) {}
try {
System.out.println(" -> " + format.parse(form.format(myNumber)));
} catch (ParseException e) {}
}
}Another example use getInstance(style).
Print out a number using the localized number, currency, percent,
scientific, integer, iso currency, and plural currency format for each locale.
ULocale locale = new ULocale("en_US");
double myNumber = 1234.56;
for (int j=NumberFormat.NUMBERSTYLE; j<=NumberFormat.PLURALCURRENCYSTYLE; ++j) {
NumberFormat format = NumberFormat.getInstance(locale, j);
try {
// Assume format is a DecimalFormat
System.out.print(": " + ((DecimalFormat) format).toPattern()
+ " -> " + form.format(myNumber));
} catch (Exception e) {}
try {
System.out.println(" -> " + format.parse(form.format(myNumber)));
} catch (ParseException e) {}
}A DecimalFormat consists of a pattern and a set of
symbols. The pattern may be set directly using applyPattern(java.lang.String), or
indirectly using other API methods which manipulate aspects of the pattern, such as the
minimum number of integer digits. The symbols are stored in a DecimalFormatSymbols object. When using the NumberFormat factory methods, the
pattern and symbols are read from ICU's locale data.
Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed.
To insert a special character in a pattern as a literal, that is, without any special meaning, the character must be quoted. There are some exceptions to this which are noted below.
The characters listed here are used in non-localized patterns. Localized patterns
use the corresponding characters taken from this formatter's DecimalFormatSymbols object instead, and these characters lose their special status.
Two exceptions are the currency sign and quote, which are not localized.
Symbol Location Localized? Meaning 0Number Yes Digit 1-9Number Yes '1' through '9' indicate rounding. @Number No Significant digit #Number Yes Digit, zero shows as absent .Number Yes Decimal separator or monetary decimal separator -Number Yes Minus sign ,Number Yes Grouping separator ENumber Yes Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix. +Exponent Yes Prefix positive exponents with localized plus sign. Need not be quoted in prefix or suffix. ;Subpattern boundary Yes Separates positive and negative subpatterns %Prefix or suffix Yes Multiply by 100 and show as percentage \u2030Prefix or suffix Yes Multiply by 1000 and show as per mille ¤(\u00A4)Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If tripled, replaced by currency plural names, for example, "US dollar" or "US dollars" for America. If present in a pattern, the monetary decimal separator is used instead of the decimal separator. 'Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#"formats 123 to"#123". To create a single quote itself, use two in a row:"# o''clock".*Prefix or suffix boundary Yes Pad escape, precedes pad character
A DecimalFormat pattern contains a postive and negative subpattern, for
example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part, and a
suffix. If there is no explicit negative subpattern, the negative subpattern is the
localized minus sign prefixed to the positive subpattern. That is, "0.00" alone is
equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves
only to specify the negative prefix and suffix; the number of digits, minimal digits,
and other characteristics are ignored in the negative subpattern. That means that
"#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)".
The prefixes, suffixes, and various symbols used for infinity, digits, thousands
separators, decimal separators, etc. may be set to arbitrary values, and they will
appear properly during formatting. However, care must be taken that the symbols and
strings do not conflict, or parsing will be unreliable. For example, either the
positive and negative prefixes or the suffixes must be distinct for parse(java.lang.String, java.text.ParsePosition) to
be able to distinguish positive from negative values. Another example is that the
decimal separator and thousands separator should be distinct characters, or parsing
will be impossible.
The grouping separator is a character that separates clusters of integer digits to make large numbers more legible. It commonly used for thousands, but in some locales it separates ten-thousands. The grouping size is the number of digits between the grouping separators, such as 3 for "100,000,000" or 4 for "1 0000 0000". There are actually two different grouping sizes: One used for the least significant integer digits, the primary grouping size, and one used for all others, the secondary grouping size. In most locales these are the same, but sometimes they are different. For example, if the primary grouping interval is 3, and the secondary is 2, then this corresponds to the pattern "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a pattern contains multiple grouping separators, the interval between the last one and the end of the integer defines the primary grouping size, and the interval between the last two defines the secondary grouping size. All others are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####".
Illegal patterns, such as "#.#.#" or "#.###,###", will cause
DecimalFormat to throw an IllegalArgumentException with a message
that describes the problem.
pattern := subpattern (';' subpattern)?
subpattern := prefix? number exponent? suffix?
number := (integer ('.' fraction)?) | sigDigits
prefix := '\u0000'..'\uFFFD' - specialCharacters
suffix := '\u0000'..'\uFFFD' - specialCharacters
integer := '#'* '0'* '0'
fraction := '0'* '#'*
sigDigits := '#'* '@' '@'* '#'*
exponent := 'E' '+'? '0'* '0'
padSpec := '*' padChar
padChar := '\u0000'..'\uFFFD' - quote
Notation:
X* 0 or more instances of X
X? 0 or 1 instances of X
X|Y either X or Y
C..D any character from C up to D, inclusive
S-T characters in S, except those in T
The first subpattern is for positive numbers. The second (optional)
subpattern is for negative numbers.
Not indicated in the BNF syntax above:
padSpec may appear before the prefix, after the
prefix, before the suffix, after the suffix, or not at all.
DecimalFormat parses all Unicode characters that represent decimal
digits, as defined by UCharacter.digit(int, int). In addition,
DecimalFormat also recognizes as digits the ten consecutive characters
starting with the localized zero digit defined in the DecimalFormatSymbols
object. During formatting, the DecimalFormatSymbols-based digits are output.
During parsing, grouping separators are ignored.
For currency parsing, the formatter is able to parse every currency style formats no matter which style the formatter is constructed with. For example, a formatter instance gotten from NumberFormat.getInstance(ULocale, NumberFormat.CURRENCYSTYLE) can parse formats such as "USD1.00" and "3.00 US dollars".
If parse(String, ParsePosition) fails to parse a string, it returns
null and leaves the parse position unchanged. The convenience method
NumberFormat.parse(String) indicates parse failure by throwing a ParseException.
Parsing an extremely large or small absolute value (such as 1.0E10000 or 1.0E-10000)
requires huge memory allocation for representing the parsed number. Such input may expose
a risk of DoS attacks. To prevent huge memory allocation triggered by such inputs,
DecimalFormat internally limits of maximum decimal digits to be 1000. Thus,
an input string resulting more than 1000 digits in plain decimal representation (non-exponent)
will be treated as either overflow (positive/negative infinite) or underflow (+0.0/-0.0).
Formatting is guided by several parameters, all of which can be specified either using a pattern or using the API. The following description applies to formats that do not use scientific notation or significant digits.
Special Values
NaN is represented as a single character, typically
\uFFFD. This character is determined by the DecimalFormatSymbols object. This is the only value for which the prefixes and
suffixes are not used.
Infinity is represented as a single character, typically \u221E,
with the positive or negative prefixes and suffixes applied. The infinity character is
determined by the DecimalFormatSymbols object.
Scientific Notation
Numbers in scientific notation are expressed as the product of a mantissa and a
power of ten, for example, 1234 can be expressed as 1.234 x 103. The
mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0),
but it need not be. DecimalFormat supports arbitrary mantissas.
DecimalFormat can be instructed to use scientific notation through the API
or through the pattern. In a pattern, the exponent character immediately followed by
one or more digit characters indicates scientific notation. Example: "0.###E0" formats
the number 1234 as "1.234E3".
DecimalFormat has two ways of controlling how many digits are shows: (a)
significant digits counts, or (b) integer and fraction digit counts. Integer and
fraction digit counts are described above. When a formatter is using significant
digits counts, the number of integer and fraction digits is not specified directly, and
the formatter settings for these counts are ignored. Instead, the formatter uses
however many integer and fraction digits are required to display the specified number
of significant digits. Examples:
Pattern Minimum significant digits Maximum significant digits Number Output of format() @@@3 3 12345 12300@@@3 3 0.12345 0.123@@##2 4 3.14159 3.142@@##2 4 1.23004 1.23
'@' and
'#' characters. The minimum number of significant digits is the number of
'@' characters. The maximum number of significant digits is the number of
'@' characters plus the number of '#' characters following on
the right. For example, the pattern "@@@" indicates exactly 3 significant
digits. The pattern "@##" indicates from 1 to 3 significant digits.
Trailing zero digits to the right of the decimal separator are suppressed after the
minimum number of significant digits have been shown. For example, the pattern
"@##" formats the number 0.1203 as "0.12".
'0' pattern character. Patterns such as "@00" or
"@.###" are disallowed.
'#' characters may be prepended to the left of the
leftmost '@' character. These have no effect on the minimum and maximum
significant digits counts, but may be used to position grouping separators. For
example, "#,#@#" indicates a minimum of one significant digits, a maximum
of two significant digits, and a grouping size of three.
'@' pattern character. Alternatively, call setSignificantDigitsUsed(true).
'@' pattern character. Alternatively, call setSignificantDigitsUsed(false).
getMinimumSignificantDigits() -
1, and a maximum fraction digit count of getMaximumSignificantDigits() -
1. For example, the pattern "@@###E0" is equivalent to
"0.0###E0".
DecimalFormat supports padding the result of format(double, java.lang.StringBuffer, java.text.FieldPosition) to a
specific width. Padding may be specified either through the API or through the pattern
syntax. In a pattern the pad escape character, followed by a single pad character,
causes padding to be parsed and formatted. The pad escape character is '*' in
unlocalized patterns, and can be localized using DecimalFormatSymbols.setPadEscape(char). For example, "$*x#,##0.00" formats
123 to "$xx123.00", and 1234 to "$1,234.00".
"* #0
o''clock", the format width is 10.
chars).
applyPattern(java.lang.String) throws an IllegalArgumentException. If there
is no prefix, before the prefix and after the prefix are equivalent, likewise for the
suffix.
char immediately following the
pad escape is the pad character. This may be any character, including a special pattern
character. That is, the pad escape escapes the following character. If there
is no character after the pad escape, then the pattern is illegal.
Rounding
DecimalFormat supports rounding to a specific increment. For example,
1230 rounded to the nearest 50 is 1250. 1.234 rounded to the nearest 0.65 is 1.3. The
rounding increment may be specified through the API or in a pattern. To specify a
rounding increment in a pattern, include the increment in the pattern itself. "#,#50"
specifies a rounding increment of 50. "#,##0.05" specifies a rounding increment of
0.05.
BigDecimal documentation for a description of the modes. Rounding
increments specified in patterns use the default mode, BigDecimal.ROUND_HALF_EVEN.
DecimalFormat objects are not synchronized. Multiple threads should
not access one formatter concurrently.
Format,
NumberFormat,
Serialized FormNumberFormat.Field, NumberFormat.NumberFormatFactory, NumberFormat.SimpleNumberFormatFactory| Modifier and Type | Field and Description |
|---|---|
static int |
PAD_AFTER_PREFIX
Constant for
getPadPosition() and setPadPosition(int) to
specify pad characters inserted after the prefix. |
static int |
PAD_AFTER_SUFFIX
Constant for
getPadPosition() and setPadPosition(int) to
specify pad characters inserted after the suffix. |
static int |
PAD_BEFORE_PREFIX
Constant for
getPadPosition() and setPadPosition(int) to
specify pad characters inserted before the prefix. |
static int |
PAD_BEFORE_SUFFIX
Constant for
getPadPosition() and setPadPosition(int) to
specify pad characters inserted before the suffix. |
ACCOUNTINGCURRENCYSTYLE, CASHCURRENCYSTYLE, CURRENCYSTYLE, FRACTION_FIELD, INTEGER_FIELD, INTEGERSTYLE, ISOCURRENCYSTYLE, NUMBERSTYLE, PERCENTSTYLE, PLURALCURRENCYSTYLE, SCIENTIFICSTYLE, STANDARDCURRENCYSTYLE| Constructor and Description |
|---|
DecimalFormat()
Creates a DecimalFormat using the default pattern and symbols for the default
FORMAT locale. |
DecimalFormat(String pattern)
Creates a DecimalFormat from the given pattern and the symbols for the default
FORMAT locale. |
DecimalFormat(String pattern,
DecimalFormatSymbols symbols)
Creates a DecimalFormat from the given pattern and symbols.
|
DecimalFormat(String pattern,
DecimalFormatSymbols symbols,
CurrencyPluralInfo infoInput,
int style)
Creates a DecimalFormat from the given pattern, symbols, information used for
currency plural format, and format style.
|
| Modifier and Type | Method and Description |
|---|---|
void |
applyLocalizedPattern(String pattern)
Applies the given pattern to this Format object.
|
void |
applyPattern(String pattern)
Applies the given pattern to this Format object.
|
boolean |
areSignificantDigitsUsed()
Returns true if significant digits are in use or false if integer and
fraction digit counts are in use.
|
Object |
clone()
Overrides clone.
|
boolean |
equals(Object obj)
Overrides equals.
|
StringBuffer |
format(BigDecimal number,
StringBuffer result,
FieldPosition fieldPosition)
Formats a BigDecimal number.
|
StringBuffer |
format(BigDecimal number,
StringBuffer result,
FieldPosition fieldPosition)
Formats a BigDecimal number.
|
StringBuffer |
format(BigInteger number,
StringBuffer result,
FieldPosition fieldPosition)
Formats a BigInteger number.
|
StringBuffer |
format(double number,
StringBuffer result,
FieldPosition fieldPosition)
Specialization of format.
|
StringBuffer |
format(long number,
StringBuffer result,
FieldPosition fieldPosition)
Specialization of format.
|
AttributedCharacterIterator |
formatToCharacterIterator(Object obj)
Formats the object to an attributed string, and return the corresponding iterator.
|
CurrencyPluralInfo |
getCurrencyPluralInfo()
Returns a copy of the CurrencyPluralInfo used by this format.
|
Currency.CurrencyUsage |
getCurrencyUsage()
Returns the Currency Usage object used to display currency
|
DecimalFormatSymbols |
getDecimalFormatSymbols()
Returns a copy of the decimal format symbols used by this format.
|
protected Currency |
getEffectiveCurrency()
Deprecated.
This API is ICU internal only.
|
int |
getFormatWidth()
Returns the width to which the output of
format() is padded. |
int |
getGroupingSize()
Returns the grouping size.
|
MathContext |
getMathContext()
Returns the MathContext used by this format.
|
MathContext |
getMathContextICU()
Returns the MathContext used by this format.
|
int |
getMaximumSignificantDigits()
Returns the maximum number of significant digits that will be
displayed.
|
byte |
getMinimumExponentDigits()
Returns the minimum exponent digits that will be shown.
|
int |
getMinimumSignificantDigits()
Returns the minimum number of significant digits that will be
displayed.
|
int |
getMultiplier()
Returns the multiplier for use in percent, permill, etc.
|
String |
getNegativePrefix()
Returns the negative prefix.
|
String |
getNegativeSuffix()
Returns the negative suffix.
|
char |
getPadCharacter()
Returns the character used to pad to the format width.
|
int |
getPadPosition()
Returns the position at which padding will take place.
|
int |
getParseMaxDigits()
Get the current maximum number of exponent digits when parsing a
number.
|
String |
getPositivePrefix()
Returns the positive prefix.
|
String |
getPositiveSuffix()
Returns the positive suffix.
|
BigDecimal |
getRoundingIncrement()
Returns the rounding increment.
|
int |
getRoundingMode()
Returns the rounding mode.
|
int |
getSecondaryGroupingSize()
Returns the secondary grouping size.
|
int |
hashCode()
Overrides hashCode.
|
boolean |
isDecimalPatternMatchRequired()
Returns whether the input to parsing must contain a decimal mark if there
is a decimal mark in the pattern.
|
boolean |
isDecimalSeparatorAlwaysShown()
Returns the behavior of the decimal separator with integers.
|
boolean |
isExponentSignAlwaysShown()
Returns whether the exponent sign is always shown.
|
boolean |
isParseBigDecimal()
Returns whether
parse(String, ParsePosition) returns BigDecimal. |
boolean |
isScientificNotation()
Returns whether or not scientific notation is used.
|
Number |
parse(String text,
ParsePosition parsePosition)
Parses the given string, returning a
Number object to represent the
parsed value. |
CurrencyAmount |
parseCurrency(CharSequence text,
ParsePosition pos)
Parses text from the given string as a CurrencyAmount.
|
void |
setCurrency(Currency theCurrency)
Sets the Currency object used to display currency amounts.
|
void |
setCurrencyPluralInfo(CurrencyPluralInfo newInfo)
Sets the CurrencyPluralInfo used by this format.
|
void |
setCurrencyUsage(Currency.CurrencyUsage newUsage)
Sets the Currency Usage object used to display currency.
|
void |
setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
Sets the decimal format symbols used by this format.
|
void |
setDecimalPatternMatchRequired(boolean value)
When decimal match is not required, the input does not have to
contain a decimal mark when there is a decimal mark specified in the
pattern.
|
void |
setDecimalSeparatorAlwaysShown(boolean newValue)
Sets the behavior of the decimal separator with integers.
|
void |
setExponentSignAlwaysShown(boolean expSignAlways)
Sets whether the exponent sign is always shown.
|
void |
setFormatWidth(int width)
Sets the width to which the output of
format() is
padded. |
void |
setGroupingSize(int newValue)
Sets the grouping size.
|
void |
setMathContext(MathContext newValue)
Sets the MathContext used by this format.
|
void |
setMathContextICU(MathContext newValue)
Sets the MathContext used by 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 |
setMaximumSignificantDigits(int max)
Sets the maximum number of significant digits that will be displayed.
|
void |
setMinimumExponentDigits(byte minExpDig)
Sets the minimum exponent digits that will be shown.
|
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 |
setMinimumSignificantDigits(int min)
Sets the minimum number of significant digits that will be displayed.
|
void |
setMultiplier(int newValue)
Sets the multiplier for use in percent, permill, etc.
|
void |
setNegativePrefix(String newValue)
Sets the negative prefix.
|
void |
setNegativeSuffix(String newValue)
Sets the positive suffix.
|
void |
setPadCharacter(char padChar)
Sets the character used to pad to the format width.
|
void |
setPadPosition(int padPos)
Sets the position at which padding will take place.
|
void |
setParseBigDecimal(boolean value)
Sets whether
parse(String, ParsePosition) returns BigDecimal. |
void |
setParseMaxDigits(int newValue)
Set the maximum number of exponent digits when parsing a number.
|
void |
setPositivePrefix(String newValue)
Sets the positive prefix.
|
void |
setPositiveSuffix(String newValue)
Sets the positive suffix.
|
void |
setRoundingIncrement(BigDecimal newValue)
Sets the rounding increment.
|
void |
setRoundingIncrement(BigDecimal newValue)
Sets the rounding increment.
|
void |
setRoundingIncrement(double newValue)
Sets the rounding increment.
|
void |
setRoundingMode(int roundingMode)
Sets the rounding mode.
|
void |
setScientificNotation(boolean useScientific)
Sets whether or not scientific notation is used.
|
void |
setSecondaryGroupingSize(int newValue)
Sets the secondary grouping size.
|
void |
setSignificantDigitsUsed(boolean useSignificantDigits)
Sets whether significant digits are in use, or integer and fraction digit
counts are in use.
|
String |
toLocalizedPattern()
Synthesizes a localized pattern string that represents the current state of this
Format object.
|
String |
toPattern()
Synthesizes a pattern string that represents the current state of this Format
object.
|
format, format, format, format, format, format, format, format, getAvailableLocales, getAvailableULocales, getContext, getCurrency, getCurrencyInstance, getCurrencyInstance, getCurrencyInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getIntegerInstance, getMaximumFractionDigits, getMaximumIntegerDigits, getMinimumFractionDigits, getMinimumIntegerDigits, getNumberInstance, getNumberInstance, getNumberInstance, getPattern, getPattern, getPercentInstance, getPercentInstance, getPercentInstance, getScientificInstance, getScientificInstance, getScientificInstance, isGroupingUsed, isParseIntegerOnly, isParseStrict, parse, parseObject, registerFactory, setContext, setGroupingUsed, setParseIntegerOnly, setParseStrict, unregisterformat, parseObjectpublic static final int PAD_BEFORE_PREFIX
getPadPosition() and setPadPosition(int) to
specify pad characters inserted before the prefix.public static final int PAD_AFTER_PREFIX
getPadPosition() and setPadPosition(int) to
specify pad characters inserted after the prefix.public static final int PAD_BEFORE_SUFFIX
getPadPosition() and setPadPosition(int) to
specify pad characters inserted before the suffix.public static final int PAD_AFTER_SUFFIX
getPadPosition() and setPadPosition(int) to
specify pad characters inserted after the suffix.public DecimalFormat()
FORMAT locale. This is a convenient way to obtain a DecimalFormat when
internationalization is not the main concern.
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.
public DecimalFormat(String pattern)
FORMAT locale. This is a convenient way to obtain a DecimalFormat when
internationalization is not the main concern.
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.
pattern - A non-localized pattern string.IllegalArgumentException - if the given pattern is invalid.NumberFormat.getInstance(),
NumberFormat.getNumberInstance(),
NumberFormat.getCurrencyInstance(),
NumberFormat.getPercentInstance(),
ULocale.Category.FORMATpublic DecimalFormat(String pattern, DecimalFormatSymbols symbols)
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance. If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method.
pattern - a non-localized pattern stringsymbols - the set of symbols to be usedIllegalArgumentException - if the given pattern is invalidNumberFormat.getInstance(),
NumberFormat.getNumberInstance(),
NumberFormat.getCurrencyInstance(),
NumberFormat.getPercentInstance(),
DecimalFormatSymbolspublic DecimalFormat(String pattern, DecimalFormatSymbols symbols, CurrencyPluralInfo infoInput, int style)
To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance.
If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method using the setters.
If you want to completely customize a decimal format, using your own DecimalFormatSymbols (such as group separators) and your own information for currency plural formatting (such as plural rule and currency plural patterns), you can use this constructor.
pattern - a non-localized pattern stringsymbols - the set of symbols to be usedinfoInput - the information used for currency plural format, including
currency plural patterns and plural rules.style - the decimal formatting style, it is one of the following values:
NumberFormat.NUMBERSTYLE; NumberFormat.CURRENCYSTYLE; NumberFormat.PERCENTSTYLE;
NumberFormat.SCIENTIFICSTYLE; NumberFormat.INTEGERSTYLE;
NumberFormat.ISOCURRENCYSTYLE; NumberFormat.PLURALCURRENCYSTYLE;public StringBuffer format(double number, StringBuffer result, FieldPosition fieldPosition)
format in class NumberFormatFormat.format(Object, StringBuffer, FieldPosition)public StringBuffer format(long number, StringBuffer result, FieldPosition fieldPosition)
NumberFormatformat in class NumberFormatFormat.format(Object, StringBuffer, FieldPosition)public StringBuffer format(BigInteger number, StringBuffer result, FieldPosition fieldPosition)
format in class NumberFormatFormat.format(Object, StringBuffer, FieldPosition)public StringBuffer format(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)
format in class NumberFormatFormat.format(Object, StringBuffer, FieldPosition)public StringBuffer format(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)
format in class NumberFormatFormat.format(Object, StringBuffer, FieldPosition)public Number parse(String text, ParsePosition parsePosition)
Number object to represent the
parsed value. Double objects are returned to represent non-integral
values which cannot be stored in a BigDecimal. These are
NaN, infinity, -infinity, and -0.0. If isParseBigDecimal() is
false (the default), all other values are returned as Long,
BigInteger, or BigDecimal values, in that order of
preference. If isParseBigDecimal() is true, all other values are returned
as BigDecimal valuse. If the parse fails, null is returned.parse in class NumberFormattext - the string to be parsedparsePosition - defines the position where parsing is to begin, and upon
return, the position where parsing left off. If the position has not changed upon
return, then parsing failed.Number object with the parsed value or
null if the parse failedNumberFormat.isParseIntegerOnly(),
Format.parseObject(String, ParsePosition)public CurrencyAmount parseCurrency(CharSequence text, ParsePosition pos)
parseCurrency in class NumberFormattext - the text to parsepos - input-output position; on input, the position within text to match; must
have 0 <= pos.getIndex() < text.length(); on output, the position after the last
matched character. If the parse fails, the position in unchanged upon output.public DecimalFormatSymbols getDecimalFormatSymbols()
DecimalFormatSymbolspublic void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
newSymbols - desired DecimalFormatSymbolsDecimalFormatSymbolspublic String getPositivePrefix()
Examples: +123, $123, sFr123
public void setPositivePrefix(String newValue)
Examples: +123, $123, sFr123
newValue - the prefixpublic String getNegativePrefix()
Examples: -123, ($123) (with negative suffix), sFr-123
public void setNegativePrefix(String newValue)
Examples: -123, ($123) (with negative suffix), sFr-123
newValue - the prefixpublic String getPositiveSuffix()
Example: 123%
public void setPositiveSuffix(String newValue)
Example: 123%
newValue - the suffixpublic String getNegativeSuffix()
Examples: -123%, ($123) (with positive suffixes)
public void setNegativeSuffix(String newValue)
Examples: 123%
newValue - the suffixpublic int getMultiplier()
Examples: with 100, 1.23 -> "123", and "123" -> 1.23
public void setMultiplier(int newValue)
Examples: with 100, 1.23 -> "123", and "123" -> 1.23
newValue - the multiplierpublic BigDecimal getRoundingIncrement()
null if a custom rounding
increment is not in effect.setRoundingIncrement(java.math.BigDecimal),
getRoundingMode(),
setRoundingMode(int)public void setRoundingIncrement(BigDecimal newValue)
newValue - A positive rounding increment, or null or
BigDecimal(0.0) to use the default rounding increment.IllegalArgumentException - if newValue is < 0.0getRoundingIncrement(),
getRoundingMode(),
setRoundingMode(int)public void setRoundingIncrement(BigDecimal newValue)
newValue - A positive rounding increment, or null or
BigDecimal(0.0) to use the default rounding increment.IllegalArgumentException - if newValue is < 0.0getRoundingIncrement(),
getRoundingMode(),
setRoundingMode(int)public void setRoundingIncrement(double newValue)
newValue - A positive rounding increment, or 0.0 to use the default
rounding increment.IllegalArgumentException - if newValue is < 0.0getRoundingIncrement(),
getRoundingMode(),
setRoundingMode(int)public int getRoundingMode()
getRoundingMode in class NumberFormatBigDecimal.ROUND_UP and
BigDecimal.ROUND_UNNECESSARY.setRoundingIncrement(java.math.BigDecimal),
getRoundingIncrement(),
setRoundingMode(int),
BigDecimalpublic void setRoundingMode(int roundingMode)
setRoundingMode in class NumberFormatroundingMode - A rounding mode, between BigDecimal.ROUND_UP and
BigDecimal.ROUND_UNNECESSARY.IllegalArgumentException - if roundingMode is unrecognized.setRoundingIncrement(java.math.BigDecimal),
getRoundingIncrement(),
getRoundingMode(),
BigDecimalpublic int getFormatWidth()
format() is padded. The width is
counted in 16-bit code units.setFormatWidth(int),
getPadCharacter(),
setPadCharacter(char),
getPadPosition(),
setPadPosition(int)public void setFormatWidth(int width)
format() is
padded. The width is counted in 16-bit code units. This method
also controls whether padding is enabled.width - the width to which to pad the result of
format(), or zero to disable paddingIllegalArgumentException - if width is < 0getFormatWidth(),
getPadCharacter(),
setPadCharacter(char),
getPadPosition(),
setPadPosition(int)public char getPadCharacter()
setFormatWidth(int),
getFormatWidth(),
setPadCharacter(char),
getPadPosition(),
setPadPosition(int)public void setPadCharacter(char padChar)
padChar - the pad charactersetFormatWidth(int),
getFormatWidth(),
getPadCharacter(),
getPadPosition(),
setPadPosition(int)public int getPadPosition()
format() is shorter
than the format width.PAD_BEFORE_PREFIX,
PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, or
PAD_AFTER_SUFFIX.setFormatWidth(int),
getFormatWidth(),
setPadCharacter(char),
getPadCharacter(),
setPadPosition(int),
PAD_BEFORE_PREFIX,
PAD_AFTER_PREFIX,
PAD_BEFORE_SUFFIX,
PAD_AFTER_SUFFIXpublic void setPadPosition(int padPos)
format() is shorter
than the format width. This has no effect unless padding is enabled.padPos - the pad position, one of PAD_BEFORE_PREFIX,
PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, or
PAD_AFTER_SUFFIX.IllegalArgumentException - if the pad position in unrecognizedsetFormatWidth(int),
getFormatWidth(),
setPadCharacter(char),
getPadCharacter(),
getPadPosition(),
PAD_BEFORE_PREFIX,
PAD_AFTER_PREFIX,
PAD_BEFORE_SUFFIX,
PAD_AFTER_SUFFIXpublic boolean isScientificNotation()
setScientificNotation(boolean),
getMinimumExponentDigits(),
setMinimumExponentDigits(byte),
isExponentSignAlwaysShown(),
setExponentSignAlwaysShown(boolean)public void setScientificNotation(boolean useScientific)
useScientific - true if this object formats and parses scientific notationisScientificNotation(),
getMinimumExponentDigits(),
setMinimumExponentDigits(byte),
isExponentSignAlwaysShown(),
setExponentSignAlwaysShown(boolean)public byte getMinimumExponentDigits()
setScientificNotation(boolean),
isScientificNotation(),
setMinimumExponentDigits(byte),
isExponentSignAlwaysShown(),
setExponentSignAlwaysShown(boolean)public void setMinimumExponentDigits(byte minExpDig)
minExpDig - a value >= 1 indicating the fewest exponent
digits that will be shownIllegalArgumentException - if minExpDig < 1setScientificNotation(boolean),
isScientificNotation(),
getMinimumExponentDigits(),
isExponentSignAlwaysShown(),
setExponentSignAlwaysShown(boolean)public boolean isExponentSignAlwaysShown()
setScientificNotation(boolean),
isScientificNotation(),
setMinimumExponentDigits(byte),
getMinimumExponentDigits(),
setExponentSignAlwaysShown(boolean)public void setExponentSignAlwaysShown(boolean expSignAlways)
expSignAlways - true if the exponent is always prefixed with either the
localized minus sign or the localized plus sign, false if only negative exponents
are prefixed with the localized minus sign.setScientificNotation(boolean),
isScientificNotation(),
setMinimumExponentDigits(byte),
getMinimumExponentDigits(),
isExponentSignAlwaysShown()public int getGroupingSize()
public void setGroupingSize(int newValue)
public int getSecondaryGroupingSize()
getGroupingSize(). For example, if
the primary grouping size is 4, and the secondary grouping size is 2, then the
number 123456789 formats as "1,23,45,6789", and the pattern appears as "#,##,###0".setSecondaryGroupingSize(int),
NumberFormat.isGroupingUsed(),
DecimalFormatSymbols.getGroupingSeparator()public void setSecondaryGroupingSize(int newValue)
public MathContext getMathContextICU()
getMathContext()public MathContext getMathContext()
getMathContext()public void setMathContextICU(MathContext newValue)
newValue - desired MathContextgetMathContext()public void setMathContext(MathContext newValue)
newValue - desired MathContextgetMathContext()public boolean isDecimalSeparatorAlwaysShown()
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
public void setDecimalPatternMatchRequired(boolean value)
value - true if input must contain a match to decimal mark in pattern
Default is false.public boolean isDecimalPatternMatchRequired()
public void setDecimalSeparatorAlwaysShown(boolean newValue)
This only affects formatting, and only where there might be no digits after the decimal point, e.g., if true, 3456.00 -> "3,456." if false, 3456.00 -> "3456" This is independent of parsing. If you want parsing to stop at the decimal point, use setParseIntegerOnly.
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
public CurrencyPluralInfo getCurrencyPluralInfo()
CurrencyPluralInfopublic void setCurrencyPluralInfo(CurrencyPluralInfo newInfo)
newInfo - desired CurrencyPluralInfoCurrencyPluralInfopublic Object clone()
clone in class NumberFormatCloneablepublic boolean equals(Object obj)
equals in class NumberFormatobj - the object to compare againstObject.hashCode()public int hashCode()
hashCode in class NumberFormatObject.equals(java.lang.Object)public String toPattern()
applyPattern(java.lang.String)public String toLocalizedPattern()
applyPattern(java.lang.String)public AttributedCharacterIterator formatToCharacterIterator(Object obj)
formatToCharacterIterator in class Formatobj - the object to format.AttributedCharacterIterator with the formatted object
and attributes.public void applyPattern(String pattern)
There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon
Example "#,#00.0#" -> 1,234.56
This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.
Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses.
In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.
public void applyLocalizedPattern(String pattern)
There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon
Example "#,#00.0#" -> 1,234.56
This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.
Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses.
In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.
public void setMaximumIntegerDigits(int newValue)
setMaximumIntegerDigits in class NumberFormatnewValue - 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.NumberFormat.setMaximumIntegerDigits(int)public void setMinimumIntegerDigits(int newValue)
setMinimumIntegerDigits in class NumberFormatnewValue - 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.NumberFormat.setMinimumIntegerDigits(int)public int getMinimumSignificantDigits()
areSignificantDigitsUsed()
returns true.public int getMaximumSignificantDigits()
areSignificantDigitsUsed()
returns true.public void setMinimumSignificantDigits(int min)
min is less than one then it is set to one. If the maximum significant
digits count is less than min, then it is set to min.
This function also enables the use of significant digits by this formatter -
areSignificantDigitsUsed() will return true.min - the fewest significant digits to be shownpublic void setMaximumSignificantDigits(int max)
max is less than one then it is set to one. If the minimum significant
digits count is greater than max, then it is set to max.
This function also enables the use of significant digits by this formatter -
areSignificantDigitsUsed() will return true.max - the most significant digits to be shownpublic boolean areSignificantDigitsUsed()
public void setSignificantDigitsUsed(boolean useSignificantDigits)
useSignificantDigits - true to use significant digits, or false to use integer
and fraction digit countspublic void setCurrency(Currency theCurrency)
setCurrency in class NumberFormattheCurrency - new currency object to use. Must not be null.public void setCurrencyUsage(Currency.CurrencyUsage newUsage)
newUsage - new currency context object to use.public Currency.CurrencyUsage getCurrencyUsage()
@Deprecated protected Currency getEffectiveCurrency()
getEffectiveCurrency in class NumberFormatpublic void setMaximumFractionDigits(int newValue)
setMaximumFractionDigits in class NumberFormatnewValue - 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.NumberFormat.setMaximumFractionDigits(int)public void setMinimumFractionDigits(int newValue)
setMinimumFractionDigits in class NumberFormatnewValue - 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.NumberFormat.setMinimumFractionDigits(int)public void setParseBigDecimal(boolean value)
parse(String, ParsePosition) returns BigDecimal. The
default value is false.value - true if parse(String, ParsePosition)
returns BigDecimal.public boolean isParseBigDecimal()
parse(String, ParsePosition) returns BigDecimal.parse(String, ParsePosition) returns BigDecimal.public void setParseMaxDigits(int newValue)
newValue - the new limitpublic int getParseMaxDigits()