Class DecimalFormat
- All Implemented Interfaces:
Serializable
,Cloneable
- Direct Known Subclasses:
CompactDecimalFormat
IMPORTANT: New users are strongly encouraged to see if
NumberFormatter
fits their use case. Although not deprecated, this
class, DecimalFormat, is only provided for java.text.DecimalFormat compatibility.
DecimalFormat
is the primary
concrete subclass of NumberFormat
. 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 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 number formatter for a specific locale (including the default locale), call one of
NumberFormat's factory methods such as NumberFormat.getInstance()
. Do not call
DecimalFormat constructors directly unless you know what you are doing.
DecimalFormat aims to comply with the specification UTS #35. Read the specification for more information on how all the properties in DecimalFormat fit together.
NOTE: Starting in ICU 60, there is a new set of APIs for localized number formatting that are designed to be an improvement over DecimalFormat. New users are discouraged from using DecimalFormat. For more information, see the package com.ibm.icu.number.
Example Usage
Customize settings on a DecimalFormat instance from the NumberFormat factory:
NumberFormat f = NumberFormat.getInstance(loc); if (f instanceof DecimalFormat) { ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true); ((DecimalFormat) f).setMinimumGroupingDigits(2); }
Quick and dirty print out a number using the localized number, currency, and percent format for each locale:
for (ULocale uloc : ULocale.getAvailableLocales()) { System.out.print(uloc + ":\t"); System.out.print(NumberFormat.getInstance(uloc).format(1.23)); System.out.print("\t"); System.out.print(NumberFormat.getCurrencyInstance(uloc).format(1.23)); System.out.print("\t"); System.out.print(NumberFormat.getPercentInstance(uloc).format(1.23)); System.out.println(); }
Properties and Symbols
A DecimalFormat object encapsulates a set of properties and a set of symbols. Grouping size, rounding mode, and affixes are examples of properties. Locale digits and the characters used for grouping and decimal separators are examples of symbols.
To set a custom set of symbols, use setDecimalFormatSymbols(com.ibm.icu.text.DecimalFormatSymbols)
. Use the various other
setters in this class to set custom values for the properties.
Rounding
DecimalFormat provides three main strategies to specify the position at which numbers should be rounded:
- Magnitude: Display a fixed number of fraction digits; this is the most common form.
- Increment: Round numbers to the closest multiple of a certain increment, such as 0.05. This is common in currencies.
- Significant Digits: Round numbers such that a fixed number of nonzero digits are shown. This is most common in scientific notation.
It is not possible to specify more than one rounding strategy. For example, setting a rounding increment in conjunction with significant digits results in undefined behavior.
It is also possible to specify the rounding mode to use. The default rounding mode is
"half even", which rounds numbers to their closest increment, with ties broken in favor of
trailing numbers being even. For more information, see setRoundingMode(int)
and the ICU
User Guide.
Pattern Strings
A pattern string is a way to serialize some of the available properties for decimal
formatting. However, not all properties are capable of being serialized into a pattern string;
see applyPattern(java.lang.String)
for more information.
Most users should not need to interface with pattern strings directly.
ICU DecimalFormat aims to follow the specification for pattern strings in UTS #35. Refer to that specification for more information on pattern string syntax.
Pattern String BNF
The following BNF is used when parsing the pattern string into property values: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.
- 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".
- The pad specifier
padSpec
may appear before the prefix, after the prefix, before the suffix, after the suffix, or not at all. - In place of '0', the digits '1' through '9' may be used to indicate a rounding increment.
Parsing
DecimalFormat aims to be able to parse anything that it can output as a formatted string.
There are two primary parse modes: lenient and strict. Lenient mode should
be used if the goal is to parse user input to a number; strict mode should be used if the goal is
validation. The default is lenient mode. For more information, see setParseStrict(boolean)
.
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.
Grouping separators are ignored in lenient mode (default). In strict mode, grouping separators must match the locale-specified grouping sizes.
When using parseCurrency(java.lang.CharSequence, java.text.ParsePosition)
, all currencies are accepted, not just the currency
currently set in the formatter. In addition, the formatter is able to parse every currency style
format for a particular locale no matter which style the formatter is constructed with. For
example, a formatter instance gotten from NumberFormat.getInstance(ULocale,
NumberFormat.CURRENCYSTYLE) can parse both "USD1.00" and "3.00 US dollars".
Whitespace characters (lenient mode) and control characters (lenient and strict mode), collectively called "ignorables", do not need to match in identity or quantity between the pattern string and the input string. For example, the pattern "# %" matches "35 %" (with a single space), "35%" (with no space), "35 %" (with a non-breaking space), and "35 %" (with multiple spaces). Arbitrary ignorables are also allowed at boundaries between the parts of the number: prefix, number, exponent separator, and suffix. Ignorable whitespace characters are those having the Unicode "blank" property for regular expressions, defined in UTS #18 Annex C, which is "horizontal" whitespace, like spaces and tabs, but not "vertical" whitespace, like line breaks. Ignorable control characters are those in the Unicode set [:Default_Ignorable_Code_Point:].
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
.
Under the hood, a state table parsing engine is used. To debug a parsing failure during development, use the following pattern to print details about the state table transitions:
com.ibm.icu.impl.number.Parse.DEBUGGING = true; df.parse("123.45", ppos); com.ibm.icu.impl.number.Parse.DEBUGGING = false;
Thread Safety and Best Practices
Starting with ICU 59, instances of DecimalFormat are thread-safe.
Under the hood, DecimalFormat maintains an immutable formatter object that is rebuilt whenever any of the property setters are called. It is therefore best practice to call property setters only during construction and not when formatting numbers online.
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Deprecated.This API is ICU internal only.Nested classes/interfaces inherited from class com.ibm.icu.text.NumberFormat
NumberFormat.Field, NumberFormat.NumberFormatFactory, NumberFormat.SimpleNumberFormatFactory
Nested classes/interfaces inherited from class com.ibm.icu.text.UFormat
UFormat.SpanField
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Constant forsetMinimumGroupingDigits(int)
to specify display grouping using the default strategy for all locales.static final int
Constant forsetMinimumGroupingDigits(int)
to specify display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).static final int
Constant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted after the prefix.static final int
Constant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted after the suffix.static final int
Constant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted before the prefix.static final int
Constant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted before the suffix.Fields inherited from class com.ibm.icu.text.NumberFormat
ACCOUNTINGCURRENCYSTYLE, CASHCURRENCYSTYLE, CURRENCYSTYLE, FRACTION_FIELD, INTEGER_FIELD, INTEGERSTYLE, ISOCURRENCYSTYLE, NUMBERSTYLE, PERCENTSTYLE, PLURALCURRENCYSTYLE, SCIENTIFICSTYLE, STANDARDCURRENCYSTYLE
-
Constructor Summary
ConstructorsConstructorDescriptionCreates a DecimalFormat based on the number pattern and symbols for the default locale.DecimalFormat
(String pattern) Creates a DecimalFormat based on the given pattern, using symbols for the default locale.DecimalFormat
(String pattern, DecimalFormatSymbols symbols) Creates a DecimalFormat based on the given pattern and symbols.DecimalFormat
(String pattern, DecimalFormatSymbols symbols, CurrencyPluralInfo infoInput, int style) Creates a DecimalFormat based on the given pattern and symbols, with additional control over the behavior of currency. -
Method Summary
Modifier and TypeMethodDescriptionvoid
applyLocalizedPattern
(String localizedPattern) Converts the given string to standard notation and then parses it usingapplyPattern(java.lang.String)
.void
applyPattern
(String pattern) Parses the given pattern string and overwrites the settings specified in the pattern string.boolean
Returns whether significant digits are being used in rounding.clone()
Overrides clone.boolean
Tests for equality between this formatter and another formatter.format
(double number, StringBuffer result, FieldPosition fieldPosition) Specialization of format.format
(long number, StringBuffer result, FieldPosition fieldPosition) Specialization of format.format
(BigDecimal number, StringBuffer result, FieldPosition fieldPosition) Formats an ICU BigDecimal.format
(CurrencyAmount currAmt, StringBuffer result, FieldPosition fieldPosition) Formats a CurrencyAmount.format
(BigDecimal number, StringBuffer result, FieldPosition fieldPosition) Formats a BigDecimal.format
(BigInteger number, StringBuffer result, FieldPosition fieldPosition) Formats a BigInteger.Returns the currency used to display currency amounts.Returns the current instance of CurrencyPluralInfo.Returns the strategy for rounding currency amounts.Returns a copy of the decimal format symbols used by this formatter.getFixedDecimal
(double number) Deprecated.This API is ICU internal only.int
Returns the minimum number of characters in formatted output.int
Returns the primary grouping size in use.Returns theMathContext
being used to round numbers.Returns theMathContext
being used to round numbers.int
Returns the effective maximum number of integer digits after the decimal separator.int
Returns the effective maximum number of digits before the decimal separator.int
Returns the effective maximum number of significant digits displayed.byte
Returns the minimum number of digits printed in the exponent in scientific notation.int
Returns the effective minimum number of integer digits after the decimal separator.int
Returns the minimum number of digits before grouping is triggered.int
Returns the effective minimum number of digits before the decimal separator.int
Returns the effective minimum number of significant digits displayed.int
Returns the multiplier being applied to numbers before they are formatted.Affixes: Gets the negative prefix string currently being used to format numbers.Affixes: Gets the negative suffix string currently being used to format numbers.char
Returns the character used for padding.int
Returns the position used for padding.int
Deprecated.Setting max parse digits has no effect since ICU4J 59.Affixes: Gets the positive prefix string currently being used to format numbers.Affixes: Gets the positive suffix string currently being used to format numbers.Returns the increment to which numbers are being rounded.int
Returns the rounding mode being used to round numbers.int
Returns the secondary grouping size in use.int
hashCode()
boolean
Returns whether the presence of a decimal point must match the pattern.boolean
Returns whether the decimal separator is shown on integers.boolean
Returns whether the sign (plus or minus) is always printed in scientific notation.boolean
Returns whether or not grouping separators are being printed in the output.boolean
Returns whetherparse(java.lang.String, java.text.ParsePosition)
will always return a BigDecimal.boolean
Returns whether to force case (uppercase/lowercase) to match when parsing.boolean
Returns true if this format will parse numbers as integers only.boolean
Returns whether to ignore exponents when parsing.boolean
Returns whether strict parsing is in effect.boolean
Returns whether scientific (exponential) notation is enabled on this formatter.boolean
Returns whether the sign is being shown on positive numbers.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, returns another type, such as a BigDecimal, BigInteger, or Double.parseCurrency
(CharSequence text, ParsePosition parsePosition) Parses text from the given string as a CurrencyAmount.void
setCurrency
(Currency currency) Sets the currency to be used when formatting numbers.void
setCurrencyPluralInfo
(CurrencyPluralInfo newInfo) Sets a custom instance of CurrencyPluralInfo.void
Sets the currency-dependent strategy to use when rounding numbers.void
setDecimalFormatSymbols
(DecimalFormatSymbols newSymbols) Sets the decimal format symbols used by this formatter.void
setDecimalPatternMatchRequired
(boolean value) Parsing: This method is used to either require or forbid the presence of a decimal point in the string being parsed (disabled by default).void
setDecimalSeparatorAlwaysShown
(boolean value) Separators: Sets whether the decimal separator (a period in en-US) is shown on integers.void
setExponentSignAlwaysShown
(boolean expSignAlways) Scientific Notation: Sets whether the sign (plus or minus) is always to be shown in the exponent in scientific notation.void
setFormatWidth
(int width) Padding: Sets the minimum width of the string output by the formatting pipeline.void
setGroupingSize
(int width) Grouping: Sets the primary grouping size (distance between grouping separators) used when formatting large numbers.void
setGroupingUsed
(boolean enabled) Grouping: Sets whether grouping is to be used when formatting numbers.void
setMathContext
(MathContext mathContext) Rounding and Digit Limits: Sets theMathContext
used to round numbers.void
setMathContextICU
(MathContext mathContextICU) Rounding and Digit Limits: Overload ofsetMathContext(java.math.MathContext)
forMathContext
.void
setMaximumFractionDigits
(int value) Rounding and Digit Limits: Sets the maximum number of digits to display after the decimal separator.void
setMaximumIntegerDigits
(int value) Rounding and Digit Limits: Sets the maximum number of digits to display before the decimal separator.void
setMaximumSignificantDigits
(int value) Rounding and Digit Limits: Sets the maximum number of significant digits to be displayed.void
setMinimumExponentDigits
(byte minExpDig) Scientific Notation: Sets the minimum number of digits to be printed in the exponent.void
setMinimumFractionDigits
(int value) Rounding and Digit Limits: Sets the minimum number of digits to display after the decimal separator.void
setMinimumGroupingDigits
(int number) Sets the minimum number of digits that must be before the first grouping separator in order for the grouping separator to be printed.void
setMinimumIntegerDigits
(int value) Rounding and Digit Limits: Sets the minimum number of digits to display before the decimal separator.void
setMinimumSignificantDigits
(int value) Rounding and Digit Limits: Sets the minimum number of significant digits to be displayed.void
setMultiplier
(int multiplier) Sets a number that will be used to multiply all numbers prior to formatting.void
setNegativePrefix
(String prefix) Affixes: Sets the string to prepend to negative numbers.void
setNegativeSuffix
(String suffix) Affixes: Sets the string to append to negative numbers.void
setPadCharacter
(char padChar) Padding: Sets the character used to pad numbers that are narrower than the width specified insetFormatWidth(int)
.void
setPadPosition
(int padPos) Padding: Sets the position where to insert the pad character when narrower than the width specified insetFormatWidth(int)
.void
setParseBigDecimal
(boolean value) Whether to makeparse(java.lang.String, java.text.ParsePosition)
prefer returning aBigDecimal
when possible.void
setParseCaseSensitive
(boolean value) Specifies whether parsing should require cases to match in affixes, exponent separators, and currency codes.void
setParseIntegerOnly
(boolean parseIntegerOnly) Parsing: Sets whether to ignore the fraction part of a number when parsing (defaults to false).void
setParseMaxDigits
(int maxDigits) Deprecated.Setting max parse digits has no effect since ICU4J 59.void
setParseNoExponent
(boolean value) Specifies whether to stop parsing when an exponent separator is encountered.void
setParseStrict
(boolean parseStrict) Sets whether strict parsing is in effect.void
setParseStrictMode
(com.ibm.icu.impl.number.DecimalFormatProperties.ParseMode parseMode) Deprecated.This API is ICU internal only.void
setPositivePrefix
(String prefix) Affixes: Sets the string to prepend to positive numbers.void
setPositiveSuffix
(String suffix) Affixes: Sets the string to append to positive numbers.void
Deprecated.This API is ICU internal only.void
setRoundingIncrement
(double increment) Rounding and Digit Limits: Overload ofsetRoundingIncrement(java.math.BigDecimal)
.void
setRoundingIncrement
(BigDecimal increment) Rounding and Digit Limits: Overload ofsetRoundingIncrement(java.math.BigDecimal)
.void
setRoundingIncrement
(BigDecimal increment) Rounding and Digit Limits: Sets an increment, or interval, to which numbers are rounded.void
setRoundingMode
(int roundingMode) Rounding and Digit Limits: Sets theRoundingMode
used to round numbers.void
setScientificNotation
(boolean useScientific) Scientific Notation: Sets whether this formatter should print in scientific (exponential) notation.void
setSecondaryGroupingSize
(int width) Grouping: Sets the secondary grouping size (distance between grouping separators after the first separator) used when formatting large numbers.void
setSignAlwaysShown
(boolean value) Sets whether to always shown the plus sign ('+' in en) on positive numbers.void
setSignificantDigitsUsed
(boolean useSignificantDigits) Rounding and Digit Limits: Sets whether significant digits are to be used in rounding.CallstoPattern()
and converts the string to localized notation.Converts this DecimalFormat to a NumberFormatter.Serializes this formatter object to a decimal format pattern string.toString()
Returns the default value of toString() with extra DecimalFormat-specific information appended to the end of the string.Methods inherited from class com.ibm.icu.text.NumberFormat
format, format, format, format, format, format, format, getAvailableLocales, getAvailableULocales, getContext, getCurrencyInstance, getCurrencyInstance, getCurrencyInstance, getEffectiveCurrency, getInstance, getInstance, getInstance, getInstance, getInstance, getInstance, getIntegerInstance, getIntegerInstance, getIntegerInstance, getNumberInstance, getNumberInstance, getNumberInstance, getPattern, getPattern, getPatternForStyle, getPatternForStyleAndNumberingSystem, getPercentInstance, getPercentInstance, getPercentInstance, getScientificInstance, getScientificInstance, getScientificInstance, parse, parseObject, registerFactory, setContext, unregister
Methods inherited from class java.text.Format
format, parseObject
-
Field Details
-
MINIMUM_GROUPING_DIGITS_AUTO
public static final int MINIMUM_GROUPING_DIGITS_AUTOConstant forsetMinimumGroupingDigits(int)
to specify display grouping using the default strategy for all locales.- See Also:
-
MINIMUM_GROUPING_DIGITS_MIN2
public static final int MINIMUM_GROUPING_DIGITS_MIN2Constant forsetMinimumGroupingDigits(int)
to specify display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).- See Also:
-
PAD_BEFORE_PREFIX
public static final int PAD_BEFORE_PREFIXConstant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted before the prefix.- See Also:
-
PAD_AFTER_PREFIX
public static final int PAD_AFTER_PREFIXConstant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted after the prefix.- See Also:
-
PAD_BEFORE_SUFFIX
public static final int PAD_BEFORE_SUFFIXConstant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted before the suffix.- See Also:
-
PAD_AFTER_SUFFIX
public static final int PAD_AFTER_SUFFIXConstant forgetPadPosition()
andsetPadPosition(int)
to specify pad characters inserted after the suffix.- See Also:
-
-
Constructor Details
-
DecimalFormat
public DecimalFormat()Creates a DecimalFormat based on the number pattern and symbols for the default locale. This is a convenient way to obtain a DecimalFormat instance when internationalization is not the main concern.Most users should call the factory methods on NumberFormat, such as
NumberFormat.getNumberInstance()
, which return localized formatter objects, instead of the DecimalFormat constructors.- See Also:
-
DecimalFormat
Creates a DecimalFormat based on the given pattern, using symbols for the default locale. This is a convenient way to obtain a DecimalFormat instance when internationalization is not the main concern.Most users should call the factory methods on NumberFormat, such as
NumberFormat.getNumberInstance()
, which return localized formatter objects, instead of the DecimalFormat constructors.- Parameters:
pattern
- A pattern string such as "#,##0.00" conforming to UTS #35.- Throws:
IllegalArgumentException
- if the given pattern is invalid.- See Also:
-
DecimalFormat
Creates a DecimalFormat based on the given pattern and symbols. Use this constructor if you want complete control over the behavior of the formatter.Most users should call the factory methods on NumberFormat, such as
NumberFormat.getNumberInstance()
, which return localized formatter objects, instead of the DecimalFormat constructors.- Parameters:
pattern
- A pattern string such as "#,##0.00" conforming to UTS #35.symbols
- The set of symbols to be used.- Throws:
IllegalArgumentException
- if the given pattern is invalid- See Also:
-
DecimalFormat
public DecimalFormat(String pattern, DecimalFormatSymbols symbols, CurrencyPluralInfo infoInput, int style) Creates a DecimalFormat based on the given pattern and symbols, with additional control over the behavior of currency. The style argument determines whether currency rounding rules should override the pattern, and theCurrencyPluralInfo
object is used for customizing the plural forms used for currency long names.Most users should call the factory methods on NumberFormat, such as
NumberFormat.getNumberInstance()
, which return localized formatter objects, instead of the DecimalFormat constructors.- Parameters:
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;
-
-
Method Details
-
applyPattern
Parses the given pattern string and overwrites the settings specified in the pattern string. The properties corresponding to the following setters are overwritten, either with their default values or with the value specified in the pattern string:setDecimalSeparatorAlwaysShown(boolean)
setExponentSignAlwaysShown(boolean)
setFormatWidth(int)
setGroupingSize(int)
setMultiplier(int)
(percent/permille)setMaximumFractionDigits(int)
setMaximumIntegerDigits(int)
setMaximumSignificantDigits(int)
setMinimumExponentDigits(byte)
setMinimumFractionDigits(int)
setMinimumIntegerDigits(int)
setMinimumSignificantDigits(int)
setPadPosition(int)
setPadCharacter(char)
setRoundingIncrement(java.math.BigDecimal)
setSecondaryGroupingSize(int)
For more information on pattern strings, see UTS #35.
-
applyLocalizedPattern
Converts the given string to standard notation and then parses it usingapplyPattern(java.lang.String)
. This method is provided for backwards compatibility and should not be used in new projects.Localized notation means that instead of using generic placeholders in the pattern, you use the corresponding locale-specific characters instead. For example, in locale fr-FR, the period in the pattern "0.000" means "decimal" in standard notation (as it does in every other locale), but it means "grouping" in localized notation.
- Parameters:
localizedPattern
- The pattern string in localized notation.
-
clone
Description copied from class:NumberFormat
Overrides clone.- Overrides:
clone
in classNumberFormat
-
format
Specialization of format.- Specified by:
format
in classNumberFormat
- See Also:
-
format
Specialization of format.- Specified by:
format
in classNumberFormat
- See Also:
-
format
Formats a BigInteger. Specialization of format.- Specified by:
format
in classNumberFormat
- See Also:
-
format
Formats a BigDecimal. Specialization of format.- Specified by:
format
in classNumberFormat
- See Also:
-
format
Formats an ICU BigDecimal. Specialization of format.- Specified by:
format
in classNumberFormat
- See Also:
-
formatToCharacterIterator
- Overrides:
formatToCharacterIterator
in classFormat
-
format
public StringBuffer format(CurrencyAmount currAmt, StringBuffer result, FieldPosition fieldPosition) Formats a CurrencyAmount. Specialization of format.- Overrides:
format
in classNumberFormat
- See Also:
-
parse
Returns a Long if possible (e.g., within the range [Long.MIN_VALUE, Long.MAX_VALUE] and with no decimals); otherwise, returns another type, such as a BigDecimal, BigInteger, or Double. The return type is not guaranteed other than for the Long case.If IntegerOnly is set, will stop at a decimal point (or equivalent; e.g., for rational numbers "1 2/3", will stop after the 1).
Does not throw an exception; if no object can be parsed, index is unchanged!
For more detail on parsing, see the "Parsing" header in the class documentation of
DecimalFormat
.- Specified by:
parse
in classNumberFormat
- See Also:
-
parseCurrency
Parses text from the given string as a CurrencyAmount. Unlike the parse() method, this method will attempt to parse a generic currency name, searching for a match of this object's locale's currency display names, or for a 3-letter ISO currency code. This method will fail if this format is not a currency format, that is, if it does not contain the currency pattern symbol (U+00A4) in its prefix or suffix.- Overrides:
parseCurrency
in classNumberFormat
- Parameters:
text
- the text to parseparsePosition
- 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.- Returns:
- a CurrencyAmount, or null upon failure
-
getDecimalFormatSymbols
Returns a copy of the decimal format symbols used by this formatter.- Returns:
- desired DecimalFormatSymbols
- See Also:
-
setDecimalFormatSymbols
Sets the decimal format symbols used by this formatter. The formatter uses a copy of the provided symbols.- Parameters:
newSymbols
- desired DecimalFormatSymbols- See Also:
-
getPositivePrefix
Affixes: Gets the positive prefix string currently being used to format numbers.If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via
setPositivePrefix(java.lang.String)
, the string will be returned literally.- Returns:
- The string being prepended to positive numbers.
-
setPositivePrefix
Affixes: Sets the string to prepend to positive numbers. For example, if you set the value "#", then the number 123 will be formatted as "#123" in the locale en-US.Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.
- Parameters:
prefix
- The literal string to prepend to positive numbers.
-
getNegativePrefix
Affixes: Gets the negative prefix string currently being used to format numbers.If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via
setNegativePrefix(java.lang.String)
, the string will be returned literally.- Returns:
- The string being prepended to negative numbers.
-
setNegativePrefix
Affixes: Sets the string to prepend to negative numbers. For example, if you set the value "#", then the number -123 will be formatted as "#123" in the locale en-US (overriding the implicit default '-' in the pattern).Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.
- Parameters:
prefix
- The literal string to prepend to negative numbers.
-
getPositiveSuffix
Affixes: Gets the positive suffix string currently being used to format numbers.If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via
setPositiveSuffix(java.lang.String)
, the string will be returned literally.- Returns:
- The string being appended to positive numbers.
-
setPositiveSuffix
Affixes: Sets the string to append to positive numbers. For example, if you set the value "#", then the number 123 will be formatted as "123#" in the locale en-US.Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.
- Parameters:
suffix
- The literal string to append to positive numbers.
-
getNegativeSuffix
Affixes: Gets the negative suffix string currently being used to format numbers.If the affix was specified via the pattern, the string returned by this method will have locale symbols substituted in place of special characters according to the LDML specification. If the affix was specified via
setNegativeSuffix(java.lang.String)
, the string will be returned literally.- Returns:
- The string being appended to negative numbers.
-
setNegativeSuffix
Affixes: Sets the string to append to negative numbers. For example, if you set the value "#", then the number 123 will be formatted as "123#" in the locale en-US.Using this method overrides the affix specified via the pattern, and unlike the pattern, the string given to this method will be interpreted literally WITHOUT locale symbol substitutions.
- Parameters:
suffix
- The literal string to append to negative numbers.
-
isSignAlwaysShown
public boolean isSignAlwaysShown()Returns whether the sign is being shown on positive numbers.- Returns:
- Whether the sign is shown on positive numbers and zero.
- See Also:
-
setSignAlwaysShown
public void setSignAlwaysShown(boolean value) Sets whether to always shown the plus sign ('+' in en) on positive numbers. The rules in UTS #35 section 3.2.1 will be followed to ensure a locale-aware placement of the sign.More specifically, the following strategy will be used to place the plus sign:
- Patterns without a negative subpattern: The locale's plus sign will be prepended to the positive prefix.
- Patterns with a negative subpattern without a '-' sign (e.g., accounting): The locale's plus sign will be prepended to the positive prefix, as in case 1.
- Patterns with a negative subpattern that has a '-' sign: The locale's plus sign will substitute the '-' in the negative subpattern. The positive subpattern will be unused.
- Parameters:
value
- true to always show a sign; false to hide the sign on positive numbers and zero.
-
getMultiplier
public int getMultiplier()Returns the multiplier being applied to numbers before they are formatted.- See Also:
-
setMultiplier
public void setMultiplier(int multiplier) Sets a number that will be used to multiply all numbers prior to formatting. For example, when formatting percents, a multiplier of 100 can be used.If a percent or permille sign is specified in the pattern, the multiplier is automatically set to 100 or 1000, respectively.
If the number specified here is a power of 10, a more efficient code path will be used.
- Parameters:
multiplier
- The number by which all numbers passed toformat(double, java.lang.StringBuffer, java.text.FieldPosition)
will be multiplied.- Throws:
IllegalArgumentException
- If the given multiplier is zero.ArithmeticException
- when inverting multiplier produces a non-terminating decimal result in conjunction with MathContext of unlimited precision.
-
getRoundingIncrement
Returns the increment to which numbers are being rounded.- See Also:
-
setRoundingIncrement
Rounding and Digit Limits: Sets an increment, or interval, to which numbers are rounded. For example, a rounding increment of 0.05 will cause the number 1.23 to be rounded to 1.25 in the default rounding mode.The rounding increment can be specified via the pattern string: for example, the pattern "#,##0.05" encodes a rounding increment of 0.05.
The rounding increment is applied after any multipliers might take effect; for example, in scientific notation or when
setMultiplier(int)
is used.See
setMaximumFractionDigits(int)
andsetMaximumSignificantDigits(int)
for two other ways of specifying rounding strategies.- Parameters:
increment
- The increment to which numbers are to be rounded.- See Also:
-
setRoundingIncrement
Rounding and Digit Limits: Overload ofsetRoundingIncrement(java.math.BigDecimal)
.- Parameters:
increment
- The increment to which numbers are to be rounded.- See Also:
-
setRoundingIncrement
public void setRoundingIncrement(double increment) Rounding and Digit Limits: Overload ofsetRoundingIncrement(java.math.BigDecimal)
.- Parameters:
increment
- The increment to which numbers are to be rounded.- See Also:
-
getRoundingMode
public int getRoundingMode()Returns the rounding mode being used to round numbers.- Overrides:
getRoundingMode
in classNumberFormat
- Returns:
- A rounding mode, between
BigDecimal.ROUND_UP
andBigDecimal.ROUND_UNNECESSARY
. - See Also:
-
setRoundingMode
public void setRoundingMode(int roundingMode) Rounding and Digit Limits: Sets theRoundingMode
used to round numbers. The default rounding mode is HALF_EVEN, which rounds decimals to their closest whole number, and rounds to the closest even number if at the midpoint.For more detail on rounding modes, see the ICU User Guide.
For backwards compatibility, the rounding mode is specified as an int argument, which can be from either the constants in
BigDecimal
or the ordinal value ofRoundingMode
. The following two calls are functionally equivalent.df.setRoundingMode(BigDecimal.ROUND_CEILING); df.setRoundingMode(RoundingMode.CEILING.ordinal());
- Overrides:
setRoundingMode
in classNumberFormat
- Parameters:
roundingMode
- The integer constant rounding mode to use when formatting numbers.- See Also:
-
getMathContext
Returns theMathContext
being used to round numbers.- See Also:
-
setMathContext
Rounding and Digit Limits: Sets theMathContext
used to round numbers. A "math context" encodes both a rounding mode and a number of significant digits. Most users should callsetRoundingMode(int)
and/orsetMaximumSignificantDigits(int)
instead of this method.When formatting, since no division is ever performed, the default MathContext is unlimited significant digits. However, when division occurs during parsing to correct for percentages and multipliers, a MathContext of 34 digits, the IEEE 754R Decimal128 standard, is used by default. If you require more than 34 digits when parsing, you can set a custom MathContext using this method.
- Parameters:
mathContext
- The MathContext to use when rounding numbers.- Throws:
ArithmeticException
- when inverting multiplier produces a non-terminating decimal result in conjunction with MathContext of unlimited precision.- See Also:
-
getMathContextICU
Returns theMathContext
being used to round numbers.- See Also:
-
setMathContextICU
Rounding and Digit Limits: Overload ofsetMathContext(java.math.MathContext)
forMathContext
.- Parameters:
mathContextICU
- The MathContext to use when rounding numbers.- Throws:
ArithmeticException
- when inverting multiplier produces a non-terminating decimal result in conjunction with MathContext of unlimited precision.- See Also:
-
getMinimumIntegerDigits
public int getMinimumIntegerDigits()Returns the effective minimum number of digits before the decimal separator.- Overrides:
getMinimumIntegerDigits
in classNumberFormat
- Returns:
- the minimum number of integer digits
- See Also:
-
setMinimumIntegerDigits
public void setMinimumIntegerDigits(int value) Rounding and Digit Limits: Sets the minimum number of digits to display before the decimal separator. If the number has fewer than this many digits, the number is padded with zeros.For example, if minimum integer digits is 3, the number 12.3 will be printed as "001.23".
Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.
If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.
- Overrides:
setMinimumIntegerDigits
in classNumberFormat
- Parameters:
value
- The minimum number of digits before the decimal separator.- See Also:
-
getMaximumIntegerDigits
public int getMaximumIntegerDigits()Returns the effective maximum number of digits before the decimal separator.- Overrides:
getMaximumIntegerDigits
in classNumberFormat
- Returns:
- the maximum number of integer digits
- See Also:
-
setMaximumIntegerDigits
public void setMaximumIntegerDigits(int value) Rounding and Digit Limits: Sets the maximum number of digits to display before the decimal separator. If the number has more than this many digits, the number is truncated.For example, if maximum integer digits is 3, the number 12345 will be printed as "345".
Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.
If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.
- Overrides:
setMaximumIntegerDigits
in classNumberFormat
- Parameters:
value
- The maximum number of digits before the decimal separator.- See Also:
-
getMinimumFractionDigits
public int getMinimumFractionDigits()Returns the effective minimum number of integer digits after the decimal separator.- Overrides:
getMinimumFractionDigits
in classNumberFormat
- Returns:
- the minimum number of fraction digits
- See Also:
-
setMinimumFractionDigits
public void setMinimumFractionDigits(int value) Rounding and Digit Limits: Sets the minimum number of digits to display after the decimal separator. If the number has fewer than this many digits, the number is padded with zeros.For example, if minimum fraction digits is 2, the number 123.4 will be printed as "123.40".
Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.
If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.
See
setRoundingIncrement(java.math.BigDecimal)
andsetMaximumSignificantDigits(int)
for two other ways of specifying rounding strategies.- Overrides:
setMinimumFractionDigits
in classNumberFormat
- Parameters:
value
- The minimum number of integer digits after the decimal separator.- See Also:
-
getMaximumFractionDigits
public int getMaximumFractionDigits()Returns the effective maximum number of integer digits after the decimal separator.- Overrides:
getMaximumFractionDigits
in classNumberFormat
- Returns:
- the maximum number of fraction digits
- See Also:
-
setMaximumFractionDigits
public void setMaximumFractionDigits(int value) Rounding and Digit Limits: Sets the maximum number of digits to display after the decimal separator. If the number has more than this many digits, the number is rounded according to the rounding mode.For example, if maximum fraction digits is 2, the number 123.456 will be printed as "123.46".
Minimum integer and minimum and maximum fraction digits can be specified via the pattern string. For example, "#,#00.00#" has 2 minimum integer digits, 2 minimum fraction digits, and 3 maximum fraction digits. Note that it is not possible to specify maximum integer digits in the pattern except in scientific notation.
If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.
- Overrides:
setMaximumFractionDigits
in classNumberFormat
- Parameters:
value
- The maximum number of integer digits after the decimal separator.- See Also:
-
areSignificantDigitsUsed
public boolean areSignificantDigitsUsed()Returns whether significant digits are being used in rounding.- See Also:
-
setSignificantDigitsUsed
public void setSignificantDigitsUsed(boolean useSignificantDigits) Rounding and Digit Limits: Sets whether significant digits are to be used in rounding.Calling
df.setSignificantDigitsUsed(true)
is functionally equivalent to:df.setMinimumSignificantDigits(1); df.setMaximumSignificantDigits(6);
- Parameters:
useSignificantDigits
- true to enable significant digit rounding; false to disable it.
-
getMinimumSignificantDigits
public int getMinimumSignificantDigits()Returns the effective minimum number of significant digits displayed.- See Also:
-
setMinimumSignificantDigits
public void setMinimumSignificantDigits(int value) Rounding and Digit Limits: Sets the minimum number of significant digits to be displayed. If the number of significant digits is less than this value, the number will be padded with zeros as necessary.For example, if minimum significant digits is 3 and the number is 1.2, the number will be printed as "1.20".
If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.
- Parameters:
value
- The minimum number of significant digits to display.
-
getMaximumSignificantDigits
public int getMaximumSignificantDigits()Returns the effective maximum number of significant digits displayed.- See Also:
-
setMaximumSignificantDigits
public void setMaximumSignificantDigits(int value) Rounding and Digit Limits: Sets the maximum number of significant digits to be displayed. If the number of significant digits in the number exceeds this value, the number will be rounded according to the current rounding mode.For example, if maximum significant digits is 3 and the number is 12345, the number will be printed as "12300".
If minimum and maximum integer, fraction, or significant digits conflict with each other, the most recently specified value is used. For example, if there is a formatter with minInt=5, and then you set maxInt=3, then minInt will be changed to 3.
See
setRoundingIncrement(java.math.BigDecimal)
andsetMaximumFractionDigits(int)
for two other ways of specifying rounding strategies.- Parameters:
value
- The maximum number of significant digits to display.- See Also:
-
getFormatWidth
public int getFormatWidth()Returns the minimum number of characters in formatted output.- See Also:
-
setFormatWidth
public void setFormatWidth(int width) Padding: Sets the minimum width of the string output by the formatting pipeline. For example, if padding is enabled and paddingWidth is set to 6, formatting the number "3.14159" with the pattern "0.00" will result in "··3.14" if '·' is your padding string.If the number is longer than your padding width, the number will display as if no padding width had been specified, which may result in strings longer than the padding width.
Padding can be specified in the pattern string using the '*' symbol. For example, the format "*x######0" has a format width of 7 and a pad character of 'x'.
Padding is currently counted in UTF-16 code units; see ticket #13034 for more information.
- Parameters:
width
- The minimum number of characters in the output.- See Also:
-
getPadCharacter
public char getPadCharacter()Returns the character used for padding.- See Also:
-
setPadCharacter
public void setPadCharacter(char padChar) Padding: Sets the character used to pad numbers that are narrower than the width specified insetFormatWidth(int)
.In the pattern string, the padding character is the token that follows '*' before or after the prefix or suffix.
- Parameters:
padChar
- The character used for padding.- See Also:
-
getPadPosition
public int getPadPosition()Returns the position used for padding.- See Also:
-
setPadPosition
public void setPadPosition(int padPos) Padding: Sets the position where to insert the pad character when narrower than the width specified insetFormatWidth(int)
. For example, consider the pattern "P123S" with padding width 8 and padding char "*". The four positions are:PAD_BEFORE_PREFIX
⇒ "***P123S"PAD_AFTER_PREFIX
⇒ "P***123S"PAD_BEFORE_SUFFIX
⇒ "P123***S"PAD_AFTER_SUFFIX
⇒ "P123S***"
- Parameters:
padPos
- The position used for padding.- See Also:
-
isScientificNotation
public boolean isScientificNotation()Returns whether scientific (exponential) notation is enabled on this formatter.- See Also:
-
setScientificNotation
public void setScientificNotation(boolean useScientific) Scientific Notation: Sets whether this formatter should print in scientific (exponential) notation. For example, if scientific notation is enabled, the number 123000 will be printed as "1.23E5" in locale en-US. A locale-specific symbol is used as the exponent separator.Calling
df.setScientificNotation(true)
is functionally equivalent to callingdf.setMinimumExponentDigits(1)
.- Parameters:
useScientific
- true to enable scientific notation; false to disable it.- See Also:
-
getMinimumExponentDigits
public byte getMinimumExponentDigits()Returns the minimum number of digits printed in the exponent in scientific notation.- See Also:
-
setMinimumExponentDigits
public void setMinimumExponentDigits(byte minExpDig) Scientific Notation: Sets the minimum number of digits to be printed in the exponent. For example, if minimum exponent digits is 3, the number 123000 will be printed as "1.23E005".This setting corresponds to the number of zeros after the 'E' in a pattern string such as "0.00E000".
- Parameters:
minExpDig
- The minimum number of digits in the exponent.
-
isExponentSignAlwaysShown
public boolean isExponentSignAlwaysShown()Returns whether the sign (plus or minus) is always printed in scientific notation.- See Also:
-
setExponentSignAlwaysShown
public void setExponentSignAlwaysShown(boolean expSignAlways) Scientific Notation: Sets whether the sign (plus or minus) is always to be shown in the exponent in scientific notation. For example, if this setting is enabled, the number 123000 will be printed as "1.23E+5" in locale en-US. The number 0.0000123 will always be printed as "1.23E-5" in locale en-US whether or not this setting is enabled.This setting corresponds to the '+' in a pattern such as "0.00E+0".
- Parameters:
expSignAlways
- true to always shown the sign in the exponent; false to show it for negatives but not positives.
-
isGroupingUsed
public boolean isGroupingUsed()Returns whether or not grouping separators are being printed in the output.- Overrides:
isGroupingUsed
in classNumberFormat
- Returns:
- true if grouping is used
- See Also:
-
setGroupingUsed
public void setGroupingUsed(boolean enabled) Grouping: Sets whether grouping is to be used when formatting numbers. Grouping means whether the thousands, millions, billions, and larger powers of ten should be separated by a grouping separator (a comma in en-US).For example, if grouping is enabled, 12345 will be printed as "12,345" in en-US. If grouping were disabled, it would instead be printed as simply "12345".
- Overrides:
setGroupingUsed
in classNumberFormat
- Parameters:
enabled
- true to enable grouping separators; false to disable them.- See Also:
-
getGroupingSize
public int getGroupingSize()Returns the primary grouping size in use.- See Also:
-
setGroupingSize
public void setGroupingSize(int width) Grouping: Sets the primary grouping size (distance between grouping separators) used when formatting large numbers. For most locales, this defaults to 3: the number of digits between the ones and thousands place, between thousands and millions, and so forth.For example, with a grouping size of 3, the number 1234567 will be formatted as "1,234,567".
Grouping size can also be specified in the pattern: for example, "#,##0" corresponds to a grouping size of 3.
- Parameters:
width
- The grouping size to use.- See Also:
-
getSecondaryGroupingSize
public int getSecondaryGroupingSize()Returns the secondary grouping size in use.- See Also:
-
setSecondaryGroupingSize
public void setSecondaryGroupingSize(int width) Grouping: Sets the secondary grouping size (distance between grouping separators after the first separator) used when formatting large numbers. In many south Asian locales, this is set to 2.For example, with primary grouping size 3 and secondary grouping size 2, the number 1234567 will be formatted as "12,34,567".
Grouping size can also be specified in the pattern: for example, "#,##,##0" corresponds to a primary grouping size of 3 and a secondary grouping size of 2.
- Parameters:
width
- The secondary grouping size to use.- See Also:
-
getMinimumGroupingDigits
public int getMinimumGroupingDigits()Returns the minimum number of digits before grouping is triggered.- See Also:
-
setMinimumGroupingDigits
public void setMinimumGroupingDigits(int number) Sets the minimum number of digits that must be before the first grouping separator in order for the grouping separator to be printed. For example, if minimum grouping digits is set to 2, in en-US, 1234 will be printed as "1234" and 12345 will be printed as "12,345". Set the value to:- 1 to turn off minimum grouping digits.
- MINIMUM_GROUPING_DIGITS_AUTO to display grouping using the default strategy for all locales.
- MINIMUM_GROUPING_DIGITS_MIN2 to display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).
- Parameters:
number
- The minimum number of digits before grouping is triggered.
-
isDecimalSeparatorAlwaysShown
public boolean isDecimalSeparatorAlwaysShown()Returns whether the decimal separator is shown on integers.- See Also:
-
setDecimalSeparatorAlwaysShown
public void setDecimalSeparatorAlwaysShown(boolean value) Separators: Sets whether the decimal separator (a period in en-US) is shown on integers. For example, if this setting is turned on, formatting 123 will result in "123." with the decimal separator.This setting can be specified in the pattern for integer formats: "#,##0." is an example.
- Parameters:
value
- true to always show the decimal separator; false to show it only when there is a fraction part of the number.
-
getCurrency
Returns the currency used to display currency amounts. May be null.- Overrides:
getCurrency
in classNumberFormat
- See Also:
-
setCurrency
Sets the currency to be used when formatting numbers. The effect is twofold:- Substitutions for currency symbols in the pattern string will use this currency
- The rounding mode will obey the rules for this currency (see
setCurrencyUsage(com.ibm.icu.util.Currency.CurrencyUsage)
)
NumberFormat.getCurrencyInstance()
or one of its friends.- Overrides:
setCurrency
in classNumberFormat
- Parameters:
currency
- The currency to use.
-
getCurrencyUsage
Returns the strategy for rounding currency amounts.- See Also:
-
setCurrencyUsage
Sets the currency-dependent strategy to use when rounding numbers. There are two strategies:- STANDARD: When the amount displayed is intended for banking statements or electronic transfer.
- CASH: When the amount displayed is intended to be representable in physical currency, like at a cash register.
setMinimumFractionDigits(int)
andsetMaximumFractionDigits(int)
orsetRoundingIncrement(java.math.BigDecimal)
.- Parameters:
usage
- The strategy to use when rounding in the current currency.
-
getCurrencyPluralInfo
Returns the current instance of CurrencyPluralInfo.- See Also:
-
setCurrencyPluralInfo
Sets a custom instance of CurrencyPluralInfo. CurrencyPluralInfo generates pattern strings for printing currency long names.Most users should not call this method directly. You should instead create your formatter via
NumberFormat.getInstance(NumberFormat.PLURALCURRENCYSTYLE)
.- Parameters:
newInfo
- The CurrencyPluralInfo to use when printing currency long names.
-
isParseBigDecimal
public boolean isParseBigDecimal()Returns whetherparse(java.lang.String, java.text.ParsePosition)
will always return a BigDecimal.- See Also:
-
setParseBigDecimal
public void setParseBigDecimal(boolean value) Whether to makeparse(java.lang.String, java.text.ParsePosition)
prefer returning aBigDecimal
when possible. For strings corresponding to return values of Infinity, -Infinity, NaN, and -0.0, a Double will be returned even if ParseBigDecimal is enabled.- Parameters:
value
- true to causeparse(java.lang.String, java.text.ParsePosition)
to prefer BigDecimal; false to letparse(java.lang.String, java.text.ParsePosition)
return additional data types like Long or BigInteger.
-
getParseMaxDigits
Deprecated.Setting max parse digits has no effect since ICU4J 59.Always returns 1000, the default prior to ICU 59. -
setParseMaxDigits
Deprecated.Setting max parse digits has no effect since ICU4J 59.- Parameters:
maxDigits
- Prior to ICU 59, the maximum number of digits in the output number after exponential notation is applied.
-
isParseStrict
public boolean isParseStrict()Returns whether strict parsing is in effect.- Overrides:
isParseStrict
in classNumberFormat
- Returns:
- true if strict parsing is in effect
- See Also:
-
setParseStrict
public void setParseStrict(boolean parseStrict) Sets whether strict parsing is in effect. When this is true, the string is required to be a stronger match to the pattern than when lenient parsing is in effect. More specifically, the following conditions cause a parse failure relative to lenient mode (examples use the pattern "#,##0.#"):- The presence and position of special symbols, including currency, must match the
pattern.
'+123' fails (there is no plus sign in the pattern) - Leading or doubled grouping separators
',123' and '1,,234" fail - Groups of incorrect length when grouping is used
'1,23' and '1234,567' fail, but '1234' passes - Grouping separators used in numbers followed by exponents
'1,234E5' fails, but '1234E5' and '1,234E' pass ('E' is not an exponent when not followed by a number)
- Overrides:
setParseStrict
in classNumberFormat
- Parameters:
parseStrict
- True to enable strict parsing. Default is false.- See Also:
- The presence and position of special symbols, including currency, must match the
pattern.
-
setParseStrictMode
@Deprecated public void setParseStrictMode(com.ibm.icu.impl.number.DecimalFormatProperties.ParseMode parseMode) Deprecated.This API is ICU internal only.Android libcore uses this internal method to setDecimalFormatProperties.ParseMode.JAVA_COMPATIBILITY
. -
isParseIntegerOnly
public boolean isParseIntegerOnly()Returns true if this format will parse numbers as integers only. For example in the English locale, with ParseIntegerOnly true, the string "1234." would be parsed as the integer value 1234 and parsing would stop at the "." character. The decimal separator accepted by the parse operation is locale-dependent and determined by the subclass.- Overrides:
isParseIntegerOnly
in classNumberFormat
- Returns:
- true if this will parse integers only
- See Also:
-
setParseIntegerOnly
public void setParseIntegerOnly(boolean parseIntegerOnly) Parsing: Sets whether to ignore the fraction part of a number when parsing (defaults to false). If a string contains a decimal point, parsing will stop before the decimal point. Note that determining whether a character is a decimal point depends on the locale.For example, in en-US, parsing the string "123.45" will return the number 123 and parse position 3.
This is functionally equivalent to calling
setDecimalPatternMatchRequired(boolean)
and a pattern without a decimal point.- Overrides:
setParseIntegerOnly
in classNumberFormat
- Parameters:
parseIntegerOnly
- true to ignore fractional parts of numbers when parsing; false to consume fractional parts.- See Also:
-
isDecimalPatternMatchRequired
public boolean isDecimalPatternMatchRequired()Returns whether the presence of a decimal point must match the pattern.- See Also:
-
setDecimalPatternMatchRequired
public void setDecimalPatternMatchRequired(boolean value) Parsing: This method is used to either require or forbid the presence of a decimal point in the string being parsed (disabled by default). This feature was designed to be an extra layer of strictness on top of strict parsing, although it can be used in either lenient mode or strict mode.To require a decimal point, call this method in combination with either a pattern containing a decimal point or with
setDecimalSeparatorAlwaysShown(boolean)
.// Require a decimal point in the string being parsed: df.applyPattern("#."); df.setDecimalPatternMatchRequired(true); // Alternatively: df.setDecimalSeparatorAlwaysShown(true); df.setDecimalPatternMatchRequired(true);
To forbid a decimal point, call this method in combination with a pattern containing no decimal point. Alternatively, usesetParseIntegerOnly(boolean)
for the same behavior without depending on the contents of the pattern string.// Forbid a decimal point in the string being parsed: df.applyPattern("#"); df.setDecimalPatternMatchRequired(true);
- Parameters:
value
- true to either require or forbid the decimal point according to the pattern; false to disable this feature.- See Also:
-
isParseNoExponent
public boolean isParseNoExponent()Returns whether to ignore exponents when parsing.- See Also:
-
setParseNoExponent
public void setParseNoExponent(boolean value) Specifies whether to stop parsing when an exponent separator is encountered. For example, parses "123E4" to 123 (with parse position 3) instead of 1230000 (with parse position 5).- Parameters:
value
- true to prevent exponents from being parsed; false to allow them to be parsed.
-
isParseCaseSensitive
public boolean isParseCaseSensitive()Returns whether to force case (uppercase/lowercase) to match when parsing.- See Also:
-
setParseCaseSensitive
public void setParseCaseSensitive(boolean value) Specifies whether parsing should require cases to match in affixes, exponent separators, and currency codes. Case mapping is performed for each code point usingUCharacter.foldCase(int, boolean)
.- Parameters:
value
- true to force case (uppercase/lowercase) to match when parsing; false to ignore case and perform case folding.
-
equals
Tests for equality between this formatter and another formatter.If two DecimalFormat instances are equal, then they will always produce the same output. However, the reverse is not necessarily true: if two DecimalFormat instances always produce the same output, they are not necessarily equal.
- Overrides:
equals
in classNumberFormat
- Parameters:
obj
- the object to compare against- Returns:
- true if the object is equal to this.
-
hashCode
public int hashCode()- Overrides:
hashCode
in classNumberFormat
-
toString
Returns the default value of toString() with extra DecimalFormat-specific information appended to the end of the string. This extra information is intended for debugging purposes, and the format is not guaranteed to be stable. -
toPattern
Serializes this formatter object to a decimal format pattern string. The result of this method is guaranteed to be functionally equivalent to the pattern string used to create this instance after incorporating values from the setter methods.For more information on decimal format pattern strings, see UTS #35.
Important: Not all properties are capable of being encoded in a pattern string. See a list of properties in
applyPattern(java.lang.String)
.- Returns:
- A decimal format pattern string.
-
toLocalizedPattern
CallstoPattern()
and converts the string to localized notation. For more information on localized notation, seeapplyLocalizedPattern(java.lang.String)
. This method is provided for backwards compatibility and should not be used in new projects.- Returns:
- A decimal format pattern string in localized notation.
-
toNumberFormatter
Converts this DecimalFormat to a NumberFormatter. Starting in ICU 60, NumberFormatter is the recommended way to format numbers.- Returns:
- An instance of
LocalizedNumberFormatter
with the same behavior as this instance of DecimalFormat. - See Also:
-
getFixedDecimal
Deprecated.This API is ICU internal only. -
setProperties
Deprecated.This API is ICU internal only.
-