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"). All of these flavors can be easily
localized.
This is an enhanced version of DecimalFormat
that
is based on the standard version in the JDK. New or changed functionality
is labeled
NEW or
CHANGED.
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 <32locales.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) {}
}
}
Patterns
A
DecimalFormat
consists of a
pattern and a set of
symbols. The pattern may be set directly using
applyPattern(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.
Special Pattern Characters
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
|
---|
0
| Number
| Yes
| Digit
|
1-9
| Number
| Yes
| NEW
'1' through '9' indicate rounding.
|
@
| Number
| No
| NEW
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
|
E
| Number
| Yes
| Separates mantissa and exponent in scientific notation.
Need not be quoted in prefix or suffix.
|
+
| Exponent
| Yes
| NEW
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
|
\u2030
| Prefix 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 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
| NEW
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(String,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 BNF
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:
- The grouping separator ',' can occur inside the integer and
sigDigits elements, between any two pattern characters of that
element, as long as the integer or sigDigits element is not
followed by the exponent element.
- NEW
Two grouping intervals are recognized: That between the
decimal point and the first grouping symbol, and that
between the first and second grouping symbols. These
intervals are identical in most locales, but in some
locales they differ. For example, the pattern
"#,##,###" formats the number 123456789 as
"12,34,56,789".
-
NEW
The pad specifier
padSpec
may appear before the prefix,
after the prefix, before the suffix, after the suffix, or not at all.
-
NEW
In place of '0', the digits '1' through '9' may be used to
indicate a rounding increment.
Parsing
DecimalFormat
parses all Unicode characters that represent
decimal digits, as defined by
UCharacter.digit
. 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.
If
parse(String,ParsePosition)
fails to parse
a string, it returns
null
and leaves the parse position
unchanged. The convenience method
parse(String)
indicates parse failure by throwing a
ParseException
.
Formatting
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.
- If the number of actual integer digits exceeds the
maximum integer digits, then only the least significant
digits are shown. For example, 1997 is formatted as "97" if the
maximum integer digits is set to 2.
- If the number of actual integer digits is less than the
minimum integer digits, then leading zeros are added. For
example, 1997 is formatted as "01997" if the minimum integer digits
is set to 5.
- If the number of actual fraction digits exceeds the maximum
fraction digits, then half-even rounding it performed to the
maximum fraction digits. For example, 0.125 is formatted as "0.12"
if the maximum fraction digits is 2. This behavior can be changed
by specifying a rounding increment and a rounding mode.
- If the number of actual fraction digits is less than the
minimum fraction digits, then trailing zeros are added.
For example, 0.125 is formatted as "0.1250" if the mimimum fraction
digits is set to 4.
- Trailing fractional zeros are not displayed if they occur
j positions after the decimal, where j is less
than the maximum fraction digits. For example, 0.10004 is
formatted as "0.1" if the maximum fraction digits is four or less.
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 10
3. 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".
- The number of digit characters after the exponent character gives the
minimum exponent digit count. There is no maximum. Negative exponents are
formatted using the localized minus sign, not the prefix and suffix
from the pattern. This allows patterns such as "0.###E0 m/s". To prefix
positive exponents with a localized plus sign, specify '+' between the
exponent and the digits: "0.###E+0" will produce formats "1E+1", "1E+0",
"1E-1", etc. (In localized patterns, use the localized plus sign rather than
'+'.)
- The minimum number of integer digits is achieved by adjusting the
exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". This
only happens if there is no maximum number of integer digits. If there is a
maximum, then the minimum number of integer digits is fixed at one.
- The maximum number of integer digits, if present, specifies the exponent
grouping. The most common use of this is to generate engineering
notation, in which the exponent is a multiple of three, e.g.,
"##0.###E0". The number 12345 is formatted using "##0.####E0" as "12.345E3".
- When using scientific notation, the formatter controls the
digit counts using significant digits logic. The maximum number of
significant digits limits the total number of integer and fraction
digits that will be shown in the mantissa; it does not affect
parsing. For example, 12345 formatted with "##0.##E0" is "12.3E3".
See the section on significant digits for more details.
- The number of significant digits shown is determined as
follows: If areSignificantDigitsUsed() returns false, then the
minimum number of significant digits shown is one, and the maximum
number of significant digits shown is the sum of the minimum
integer and maximum fraction digits, and is
unaffected by the maximum integer digits. If this sum is zero,
then all significant digits are shown. If
areSignificantDigitsUsed() returns true, then the significant digit
counts are specified by getMinimumSignificantDigits() and
getMaximumSignificantDigits(). In this case, the number of
integer digits is fixed at one, and there is no exponent grouping.
- Exponential patterns may not contain grouping separators.
NEW
Significant Digits
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
|
- Significant digit counts may be expressed using patterns that
specify a minimum and maximum number of significant digits. These
are indicated by the
'@'
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"
.
- If a pattern uses significant digits, it may not contain a
decimal separator, nor the
'0'
pattern character.
Patterns such as "@00"
or "@.###"
are
disallowed.
- Any number of
'#'
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.
- In order to enable significant digits formatting, use a pattern
containing the
'@'
pattern character. Alternatively,
call setSignificantDigitsUsed(true)
.
- In order to disable significant digits formatting, use a
pattern that does not contain the
'@'
pattern
character. Alternatively, call setSignificantDigitsUsed(false)
.
- The number of significant digits has no effect on parsing.
- Significant digits may be used together with exponential notation. Such
patterns are equivalent to a normal exponential pattern with a minimum and
maximum integer digit count of one, a minimum fraction digit count of
getMinimumSignificantDigits() - 1
, and a maximum fraction digit
count of getMaximumSignificantDigits() - 1
. For example, the
pattern "@@###E0"
is equivalent to "0.0###E0"
.
- If signficant digits are in use, then the integer and fraction
digit counts, as set via the API, are ignored. If significant
digits are not in use, then the signficant digit counts, as set via
the API, are ignored.
NEW
Padding
DecimalFormat
supports padding the result of
format
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"
.
- When padding is in effect, the width of the positive subpattern,
including prefix and suffix, determines the format width. For example, in
the pattern
"* #0 o''clock"
, the format width is 10.
- The width is counted in 16-bit code units (Java
char
s).
- Some parameters which usually do not matter have meaning when padding is
used, because the pattern width is significant with padding. In the pattern
"* ##,##,#,##0.##", the format width is 14. The initial characters "##,##,"
do not affect the grouping size or maximum integer digits, but they do affect
the format width.
- Padding may be inserted at one of four locations: before the prefix,
after the prefix, before the suffix, or after the suffix. If padding is
specified in any other location,
applyPattern(String)
throws an IllegalArgumentException
. If there is no prefix, before the
prefix and after the prefix are equivalent, likewise for the suffix.
- When specified in a pattern, the 16-bit
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.
NEW
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.
- Rounding only affects the string produced by formatting. It does
not affect parsing or change any numerical values.
- A rounding mode determines how values are rounded; see the
BigDecimal
documentation for a description of the
modes. Rounding increments specified in patterns use the default mode,
BigDecimal.ROUND_HALF_EVEN
.
- Some locales use rounding in their currency formats to reflect the
smallest currency denomination.
- In a pattern, digits '1' through '9' specify rounding, but otherwise
behave identically to digit '0'.
Synchronization
DecimalFormat
objects are not synchronized. Multiple
threads should not access one formatter concurrently.
applyLocalizedPattern
public void applyLocalizedPattern(String pattern)
Apply the given pattern to this Format object. The pattern
is assumed to be in a localized notation. A pattern is a
short-hand specification for the various formatting properties.
These properties can also be changed individually through the
various setter methods.
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.
applyPattern
public void applyPattern(String pattern)
Apply the given pattern to this Format object. A pattern is a
short-hand specification for the various formatting properties.
These properties can also be changed individually through the
various setter methods.
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.
areSignificantDigitsUsed
public boolean areSignificantDigitsUsed()
This is a draft API and might change in a future release of ICU.
Returns true if significant digits are in use or false if
integer and fraction digit counts are in use.
- true if significant digits are in use
clone
public Object clone()
Standard override; no change in semantics.
- clone in interface NumberFormat
format
public StringBuffer format(BigInteger number,
StringBuffer result,
FieldPosition fieldPosition)
NEW
Format a BigInteger number.
- format in interface NumberFormat
format
public StringBuffer format(BigDecimal number,
StringBuffer result,
FieldPosition fieldPosition)
NEW
Format a BigDecimal number.
- format in interface NumberFormat
format
public StringBuffer format(double number,
StringBuffer result,
FieldPosition fieldPosition)
- format in interface NumberFormat
format
public StringBuffer format(BigDecimal number,
StringBuffer result,
FieldPosition fieldPosition)
NEW
Format a BigDecimal number.
- format in interface NumberFormat
format
public StringBuffer format(long number,
StringBuffer result,
FieldPosition fieldPosition)
- format in interface NumberFormat
getDecimalFormatSymbols
public DecimalFormatSymbols getDecimalFormatSymbols()
Returns a copy of the decimal format symbols used by this format.
- desired DecimalFormatSymbols
getEffectiveCurrency
protected Currency getEffectiveCurrency()
Returns the currency in effect for this formatter. Subclasses
should override this method as needed. Unlike getCurrency(),
this method should never return null.
- getEffectiveCurrency in interface NumberFormat
getFormatWidth
public int getFormatWidth()
NEW
Get the width to which the output of format()
is padded.
The width is counted in 16-bit code units.
- the format width, or zero if no padding is in effect
getGroupingSize
public int getGroupingSize()
Return the grouping size. Grouping size is the number of digits between
grouping separators in the integer portion of a number. For example,
in the number "123,456.78", the grouping size is 3.
getMaximumSignificantDigits
public int getMaximumSignificantDigits()
This is a draft API and might change in a future release of ICU.
Returns the maximum number of significant digits that will be
displayed. This value has no effect unless areSignificantDigitsUsed()
returns true.
- the most significant digits that will be shown
getMinimumExponentDigits
public byte getMinimumExponentDigits()
NEW
Return the minimum exponent digits that will be shown.
- the minimum exponent digits that will be shown
getMinimumSignificantDigits
public int getMinimumSignificantDigits()
This is a draft API and might change in a future release of ICU.
Returns the minimum number of significant digits that will be
displayed. This value has no effect unless areSignificantDigitsUsed()
returns true.
- the fewest significant digits that will be shown
getMultiplier
public int getMultiplier()
Get the multiplier for use in percent, permill, etc.
For a percentage, set the suffixes to have "%" and the multiplier to be 100.
(For Arabic, use arabic percent symbol).
For a permill, set the suffixes to have "\u2031" and the multiplier to be 1000.
Examples: with 100, 1.23 -> "123", and "123" -> 1.23
getNegativePrefix
public String getNegativePrefix()
Get the negative prefix.
Examples: -123, ($123) (with negative suffix), sFr-123
getNegativeSuffix
public String getNegativeSuffix()
Get the negative suffix.
Examples: -123%, ($123) (with positive suffixes)
getPadCharacter
public char getPadCharacter()
NEW
Get the character used to pad to the format width. The default is ' '.
getPadPosition
public int getPadPosition()
NEW
Get the position at which padding will take place. This is the location
at which padding will be inserted if the result of format()
is shorter than the format width.
- the pad position, one of
PAD_BEFORE_PREFIX
,
PAD_AFTER_PREFIX
, PAD_BEFORE_SUFFIX
, or
PAD_AFTER_SUFFIX
.
getPositivePrefix
public String getPositivePrefix()
Get the positive prefix.
Examples: +123, $123, sFr123
getPositiveSuffix
public String getPositiveSuffix()
Get the positive suffix.
Example: 123%
getRoundingIncrement
public BigDecimal getRoundingIncrement()
NEW
Get the rounding increment.
- A positive rounding increment, or
null
if rounding
is not in effect.
getRoundingMode
public int getRoundingMode()
NEW
Get the rounding mode.
- A rounding mode, between
BigDecimal.ROUND_UP
and BigDecimal.ROUND_UNNECESSARY
.
getSecondaryGroupingSize
public int getSecondaryGroupingSize()
Return the secondary grouping size. In some locales one
grouping interval is used for the least significant integer
digits (the primary grouping size), and another is used for all
others (the secondary grouping size). A formatter supporting a
secondary grouping size will return a positive integer unequal
to the primary grouping size returned by
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".
[NEW]
- the secondary grouping size, or a value less than
one if there is none
isDecimalSeparatorAlwaysShown
public boolean isDecimalSeparatorAlwaysShown()
Allows you to get the behavior of the decimal separator with integers.
(The decimal separator will always appear with decimals.)
Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345
isExponentSignAlwaysShown
public boolean isExponentSignAlwaysShown()
NEW
Return whether the exponent sign is always shown.
- 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.
isScientificNotation
public boolean isScientificNotation()
NEW
Return whether or not scientific notation is used.
- true if this object formats and parses scientific notation
parse
public Number parse(String text,
ParsePosition parsePosition)
CHANGED
Parse the given string, returning a 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. All other values are returned as Long
,
BigInteger
, or BigDecimal
values, in that order
of preference. If the parse fails, null is returned.
- parse in interface NumberFormat
text
- 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.
- a
Number
object with the parsed value or
null
if the parse failed
setCurrency
public void setCurrency(Currency theCurrency)
Sets the Currency object used to display currency
amounts. This takes effect immediately, if this format is a
currency format. If this format is not a currency format, then
the currency object is used if and when this object becomes a
currency format through the application of a new pattern.
- setCurrency in interface NumberFormat
theCurrency
- new currency object to use. Must not be
null.
setDecimalFormatSymbols
public void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)
Sets the decimal format symbols used by this format. The
format uses a copy of the provided symbols.
newSymbols
- desired DecimalFormatSymbols
setDecimalSeparatorAlwaysShown
public void setDecimalSeparatorAlwaysShown(boolean newValue)
Allows you to set the behavior of the decimal separator with integers.
(The decimal separator will always appear with decimals.)
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
setExponentSignAlwaysShown
public void setExponentSignAlwaysShown(boolean expSignAlways)
NEW
Set whether the exponent sign is always shown. This has no effect
unless scientific notation is in use.
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.
setFormatWidth
public void setFormatWidth(int width)
NEW
Set the width to which the output of 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 padding
setGroupingSize
public void setGroupingSize(int newValue)
Set the grouping size. Grouping size is the number of digits between
grouping separators in the integer portion of a number. For example,
in the number "123,456.78", the grouping size is 3.
setMaximumFractionDigits
public void setMaximumFractionDigits(int newValue)
Sets the maximum number of digits allowed in the fraction portion of a
number. This override limits the fraction digit count to 340.
- setMaximumFractionDigits in interface NumberFormat
setMaximumIntegerDigits
public void setMaximumIntegerDigits(int newValue)
Sets the maximum number of digits allowed in the integer portion of a
number. This override limits the integer digit count to 309.
- setMaximumIntegerDigits in interface NumberFormat
setMaximumSignificantDigits
public void setMaximumSignificantDigits(int max)
This is a draft API and might change in a future release of ICU.
Sets the maximum number of significant digits that will be
displayed. If 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
value has no effect unless areSignificantDigitsUsed() returns true.
max
- the most significant digits to be shown
setMinimumExponentDigits
public void setMinimumExponentDigits(byte minExpDig)
NEW
Set the minimum exponent digits that will be shown. This has no
effect unless scientific notation is in use.
minExpDig
- a value >= 1 indicating the fewest exponent digits
that will be shown
setMinimumFractionDigits
public void setMinimumFractionDigits(int newValue)
Sets the minimum number of digits allowed in the fraction portion of a
number. This override limits the fraction digit count to 340.
- setMinimumFractionDigits in interface NumberFormat
setMinimumIntegerDigits
public void setMinimumIntegerDigits(int newValue)
Sets the minimum number of digits allowed in the integer portion of a
number. This override limits the integer digit count to 309.
- setMinimumIntegerDigits in interface NumberFormat
setMinimumSignificantDigits
public void setMinimumSignificantDigits(int min)
This is a draft API and might change in a future release of ICU.
Sets the minimum number of significant digits that will be
displayed. If 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
value has no effect unless areSignificantDigitsUsed() returns true.
min
- the fewest significant digits to be shown
setMultiplier
public void setMultiplier(int newValue)
Set the multiplier for use in percent, permill, etc.
For a percentage, set the suffixes to have "%" and the multiplier to be 100.
(For Arabic, use arabic percent symbol).
For a permill, set the suffixes to have "\u2031" and the multiplier to be 1000.
Examples: with 100, 1.23 -> "123", and "123" -> 1.23
setNegativePrefix
public void setNegativePrefix(String newValue)
Set the negative prefix.
Examples: -123, ($123) (with negative suffix), sFr-123
setNegativeSuffix
public void setNegativeSuffix(String newValue)
Set the positive suffix.
Examples: 123%
setPadCharacter
public void setPadCharacter(char padChar)
NEW
Set the character used to pad to the format width. If padding
is not enabled, then this will take effect if padding is later
enabled.
padChar
- the pad character
setPadPosition
public void setPadPosition(int padPos)
NEW
Set the position at which padding will take place. This is the location
at which padding will be inserted if the result of 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
.
setPositivePrefix
public void setPositivePrefix(String newValue)
Set the positive prefix.
Examples: +123, $123, sFr123
setPositiveSuffix
public void setPositiveSuffix(String newValue)
Set the positive suffix.
Example: 123%
setRoundingIncrement
public void setRoundingIncrement(BigDecimal newValue)
This is a draft API and might change in a future release of ICU.
Set the rounding increment. This method also controls whether
rounding is enabled.
newValue
- A positive rounding increment, or null
or
BigDecimal(0.0)
to disable rounding.
setRoundingIncrement
public void setRoundingIncrement(double newValue)
NEW
Set the rounding increment. This method also controls whether
rounding is enabled.
newValue
- A positive rounding increment, or 0.0 to disable
rounding.
setRoundingIncrement
public void setRoundingIncrement(BigDecimal newValue)
NEW
Set the rounding increment. This method also controls whether
rounding is enabled.
newValue
- A positive rounding increment, or null
or
BigDecimal(0.0)
to disable rounding.
setRoundingMode
public void setRoundingMode(int roundingMode)
NEW
Set the rounding mode. This has no effect unless the rounding
increment is greater than zero.
roundingMode
- A rounding mode, between
BigDecimal.ROUND_UP
and
BigDecimal.ROUND_UNNECESSARY
.
setScientificNotation
public void setScientificNotation(boolean useScientific)
NEW
Set whether or not scientific notation is used. When scientific notation
is used, the effective maximum number of integer digits is <= 8. If the
maximum number of integer digits is set to more than 8, the effective
maximum will be 1. This allows this call to generate a 'default' scientific
number format without additional changes.
useScientific
- true if this object formats and parses scientific
notation
setSecondaryGroupingSize
public void setSecondaryGroupingSize(int newValue)
Set the secondary grouping size. If set to a value less than 1,
then secondary grouping is turned off, and the primary grouping
size is used for all intervals, not just the least significant.
[NEW]
setSignificantDigitsUsed
public void setSignificantDigitsUsed(boolean useSignificantDigits)
This is a draft API and might change in a future release of ICU.
Sets whether significant digits are in use, or integer and
fraction digit counts are in use.
useSignificantDigits
- true to use significant digits, or
false to use integer and fraction digit counts
toLocalizedPattern
public String toLocalizedPattern()
Synthesizes a localized pattern string that represents the current
state of this Format object.
toPattern
public String toPattern()
Synthesizes a pattern string that represents the current state
of this Format object.