DecimalFormat

Kotlin |Java

open class DecimalFormat : NumberFormat

kotlin.Any
↳	java.text.Format
	↳	android.icu.text.UFormat
		↳	android.icu.text.NumberFormat
			↳	android.icu.text.DecimalFormat

Known Direct Subclasses

CompactDecimalFormat

Formats numbers in compact (abbreviated) notation, like "1.

[icu enhancement] ICU's replacement for java.text.DecimalFormat. Methods, fields, and other functionality specific to ICU are labeled '[icu]'.

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 android.icu.text.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 android.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. 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 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 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.

DecimalFormat parses all Unicode characters that represent decimal digits, as defined by android.icu.lang.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.

Grouping separators are ignored in lenient mode (default). In strict mode, grouping separators must match the locale-specified grouping sizes.

When using parseCurrency, 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(java.lang.String,java.text.ParsePosition) fails to parse a string, it returns null and leaves the parse position unchanged. The convenience method parse(java.lang.String) indicates parse failure by throwing a java.text.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:

android.icu.impl.number.Parse.DEBUGGING = true;
  df.parse("123.45", ppos);
  android.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.

Summary

Constants
static Int	`MINIMUM_GROUPING_DIGITS_AUTO` [icu] Constant for `setMinimumGroupingDigits(int)` to specify display grouping using the default strategy for all locales.
static Int	`MINIMUM_GROUPING_DIGITS_MIN2` [icu] Constant for `setMinimumGroupingDigits(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 Int	`PAD_AFTER_PREFIX` [icu] Constant for `getPadPosition()` and `setPadPosition(int)` to specify pad characters inserted after the prefix.
static Int	`PAD_AFTER_SUFFIX` [icu] Constant for `getPadPosition()` and `setPadPosition(int)` to specify pad characters inserted after the suffix.
static Int	`PAD_BEFORE_PREFIX` [icu] Constant for `getPadPosition()` and `setPadPosition(int)` to specify pad characters inserted before the prefix.
static Int	`PAD_BEFORE_SUFFIX` [icu] Constant for `getPadPosition()` and `setPadPosition(int)` to specify pad characters inserted before the suffix.

Inherited constants

From class NumberFormat

`Int`	`ACCOUNTINGCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency symbol to represent currency for accounting, for example: "($3.00), instead of "-$3.00" (`CURRENCYSTYLE`). Overrides any style specified using -cf- key in locale.
`Int`	`CASHCURRENCYSTYLE` [icu] Constant to specify currency cash style of format which uses currency ISO code to represent currency, for example: "NT$3" instead of "NT$3.23".
`Int`	`CURRENCYSTYLE` [icu] Constant to specify general currency style of format. Defaults to STANDARDCURRENCYSTYLE, using currency symbol, for example "$3.00", with non-accounting style for negative values (e.g. minus sign). The specific style may be specified using the -cf- locale key.
`Int`	`FRACTION_FIELD` Field constant used to construct a FieldPosition object. Signifies that the position of the fraction part of a formatted number should be returned.
`Int`	`INTEGERSTYLE` [icu] Constant to specify a integer number style format.
`Int`	`INTEGER_FIELD` Field constant used to construct a FieldPosition object. Signifies that the position of the integer part of a formatted number should be returned.
`Int`	`ISOCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency ISO code to represent currency, for example: "USD3.00".
`Int`	`NUMBERSTYLE` [icu] Constant to specify normal number style of format.
`Int`	`PERCENTSTYLE` [icu] Constant to specify a style of format to display percent.
`Int`	`PLURALCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency long name with plural format to represent currency, for example, "3.00 US Dollars".
`Int`	`SCIENTIFICSTYLE` [icu] Constant to specify a style of format to display scientific number.
`Int`	`STANDARDCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency symbol to represent currency, for example "$3.00", using non-accounting style for negative values (e.g. minus sign). Overrides any style specified using -cf- key in locale.

Public constructors
`DecimalFormat()` Creates a DecimalFormat based on the number pattern and symbols for the default locale.
`DecimalFormat(pattern: String!)` Creates a DecimalFormat based on the given pattern, using symbols for the default locale.
`DecimalFormat(pattern: String!, symbols: DecimalFormatSymbols!)` Creates a DecimalFormat based on the given pattern and symbols.
`DecimalFormat(pattern: String!, symbols: DecimalFormatSymbols!, infoInput: CurrencyPluralInfo!, style: Int)` Creates a DecimalFormat based on the given pattern and symbols, with additional control over the behavior of currency.

Public methods
open Unit	`applyLocalizedPattern(localizedPattern: String!)` Converts the given string to standard notation and then parses it using `applyPattern`.
open Unit	`applyPattern(pattern: String!)` Parses the given pattern string and overwrites the settings specified in the pattern string.
open Boolean	`areSignificantDigitsUsed()` [icu] Returns whether significant digits are being used in rounding.
open Any	`clone()`
open Boolean	`equals(other: Any?)` Tests for equality between this formatter and another formatter.
open StringBuffer!	`format(number: Double, result: StringBuffer!, fieldPosition: FieldPosition!)` Specialization of format.
open StringBuffer!	`format(number: Long, result: StringBuffer!, fieldPosition: FieldPosition!)` Specialization of format.
open StringBuffer!	`format(number: BigInteger!, result: StringBuffer!, fieldPosition: FieldPosition!)` [icu] Formats a BigInteger.
open StringBuffer!	`format(number: BigDecimal!, result: StringBuffer!, fieldPosition: FieldPosition!)` [icu] Formats a BigDecimal.
open StringBuffer!	`format(number: BigDecimal!, result: StringBuffer!, fieldPosition: FieldPosition!)` [icu] Formats an ICU BigDecimal.
open StringBuffer!	`format(currAmt: CurrencyAmount!, result: StringBuffer!, fieldPosition: FieldPosition!)` [icu] Formats a CurrencyAmount.
open AttributedCharacterIterator!	`formatToCharacterIterator(obj: Any!)` Formats an Object producing an `AttributedCharacterIterator`.
open Currency!	`getCurrency()` Returns the currency used to display currency amounts.
open CurrencyPluralInfo!	`getCurrencyPluralInfo()` [icu] Returns the current instance of CurrencyPluralInfo.
open Currency.CurrencyUsage!	`getCurrencyUsage()` [icu] Returns the strategy for rounding currency amounts.
open DecimalFormatSymbols!	`getDecimalFormatSymbols()` Returns a copy of the decimal format symbols used by this formatter.
open Int	`getFormatWidth()` Returns the minimum number of characters in formatted output.
open Int	`getGroupingSize()` Returns the primary grouping size in use.
open MathContext!	`getMathContext()` [icu] Returns the `java.math.MathContext` being used to round numbers.
open MathContext!	`getMathContextICU()` [icu] Returns the `android.icu.math.MathContext` being used to round numbers.
open Int	`getMaximumFractionDigits()` Returns the effective maximum number of integer digits after the decimal separator.
open Int	`getMaximumIntegerDigits()` Returns the effective maximum number of digits before the decimal separator.
open Int	`getMaximumSignificantDigits()` [icu] Returns the effective maximum number of significant digits displayed.
open Byte	`getMinimumExponentDigits()` [icu] Returns the minimum number of digits printed in the exponent in scientific notation.
open Int	`getMinimumFractionDigits()` Returns the effective minimum number of integer digits after the decimal separator.
open Int	`getMinimumGroupingDigits()` [icu] Returns the minimum number of digits before grouping is triggered.
open Int	`getMinimumIntegerDigits()` Returns the effective minimum number of digits before the decimal separator.
open Int	`getMinimumSignificantDigits()` [icu] Returns the effective minimum number of significant digits displayed.
open Int	`getMultiplier()` Returns the multiplier being applied to numbers before they are formatted.
open String!	`getNegativePrefix()` Affixes: Gets the negative prefix string currently being used to format numbers.
open String!	`getNegativeSuffix()` Affixes: Gets the negative suffix string currently being used to format numbers.
open Char	`getPadCharacter()` [icu] Returns the character used for padding.
open Int	`getPadPosition()` [icu] Returns the position used for padding.
open Int	`getParseMaxDigits()` Always returns 1000, the default prior to ICU 59.
open String!	`getPositivePrefix()` Affixes: Gets the positive prefix string currently being used to format numbers.
open String!	`getPositiveSuffix()` Affixes: Gets the positive suffix string currently being used to format numbers.
open BigDecimal!	`getRoundingIncrement()` [icu] Returns the increment to which numbers are being rounded.
open Int	`getRoundingMode()` Returns the rounding mode being used to round numbers.
open Int	`getSecondaryGroupingSize()` [icu] Returns the secondary grouping size in use.
open Int	`hashCode()` Returns a hash code value for the object.
open Boolean	`isDecimalPatternMatchRequired()` [icu] Returns whether the presence of a decimal point must match the pattern.
open Boolean	`isDecimalSeparatorAlwaysShown()` Returns whether the decimal separator is shown on integers.
open Boolean	`isExponentSignAlwaysShown()` [icu] Returns whether the sign (plus or minus) is always printed in scientific notation.
open Boolean	`isGroupingUsed()` Returns whether or not grouping separators are being printed in the output.
open Boolean	`isParseBigDecimal()` Returns whether #parse will always return a BigDecimal.
open Boolean	`isParseCaseSensitive()` [icu] Returns whether to force case (uppercase/lowercase) to match when parsing.
open Boolean	`isParseIntegerOnly()` Returns true if this format will parse numbers as integers only.
open Boolean	`isParseNoExponent()` [icu] Returns whether to ignore exponents when parsing.
open Boolean	`isParseStrict()` [icu] Returns whether strict parsing is in effect.
open Boolean	`isScientificNotation()` [icu] Returns whether scientific (exponential) notation is enabled on this formatter.
open Boolean	`isSignAlwaysShown()` [icu] Returns whether the sign is being shown on positive numbers.
open Number!	`parse(text: String!, 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.
open CurrencyAmount!	`parseCurrency(text: CharSequence!, parsePosition: ParsePosition!)` Parses text from the given string as a CurrencyAmount.
open Unit	`setCurrency(currency: Currency!)` Sets the currency to be used when formatting numbers.
open Unit	`setCurrencyPluralInfo(newInfo: CurrencyPluralInfo!)` [icu] Sets a custom instance of CurrencyPluralInfo.
open Unit	`setCurrencyUsage(usage: Currency.CurrencyUsage!)` [icu] Sets the currency-dependent strategy to use when rounding numbers.
open Unit	`setDecimalFormatSymbols(newSymbols: DecimalFormatSymbols!)` Sets the decimal format symbols used by this formatter.
open Unit	`setDecimalPatternMatchRequired(value: Boolean)` [icu] Parsing: This method is used to either require or the presence of a decimal point in the string being parsed (disabled by default).
open Unit	`setDecimalSeparatorAlwaysShown(value: Boolean)` Separators: Sets whether the decimal separator (a period in en-US) is shown on integers.
open Unit	`setExponentSignAlwaysShown(expSignAlways: Boolean)` [icu] Scientific Notation: Sets whether the sign (plus or minus) is always to be shown in the exponent in scientific notation.
open Unit	`setFormatWidth(width: Int)` Padding: Sets the minimum width of the string output by the formatting pipeline.
open Unit	`setGroupingSize(width: Int)` Grouping: Sets the primary grouping size (distance between grouping separators) used when formatting large numbers.
open Unit	`setGroupingUsed(enabled: Boolean)` Grouping: Sets whether grouping is to be used when formatting numbers.
open Unit	`setMathContext(mathContext: MathContext!)` [icu] Rounding and Digit Limits: Sets the `java.math.MathContext` used to round numbers.
open Unit	`setMathContextICU(mathContextICU: MathContext!)` [icu] Rounding and Digit Limits: Overload of `setMathContext` for `android.icu.math.MathContext`.
open Unit	`setMaximumFractionDigits(value: Int)` Rounding and Digit Limits: Sets the maximum number of digits to display after the decimal separator.
open Unit	`setMaximumIntegerDigits(value: Int)` Rounding and Digit Limits: Sets the maximum number of digits to display before the decimal separator.
open Unit	`setMaximumSignificantDigits(value: Int)` [icu] Rounding and Digit Limits: Sets the maximum number of significant digits to be displayed.
open Unit	`setMinimumExponentDigits(minExpDig: Byte)` [icu] Scientific Notation: Sets the minimum number of digits to be printed in the exponent.
open Unit	`setMinimumFractionDigits(value: Int)` Rounding and Digit Limits: Sets the minimum number of digits to display after the decimal separator.
open Unit	`setMinimumGroupingDigits(number: Int)` [icu] Sets the minimum number of digits that must be before the first grouping separator in order for the grouping separator to be printed.
open Unit	`setMinimumIntegerDigits(value: Int)` Rounding and Digit Limits: Sets the minimum number of digits to display before the decimal separator.
open Unit	`setMinimumSignificantDigits(value: Int)` [icu] Rounding and Digit Limits: Sets the minimum number of significant digits to be displayed.
open Unit	`setMultiplier(multiplier: Int)` Sets a number that will be used to multiply all numbers prior to formatting.
open Unit	`setNegativePrefix(prefix: String!)` Affixes: Sets the string to prepend to negative numbers.
open Unit	`setNegativeSuffix(suffix: String!)` Affixes: Sets the string to append to negative numbers.
open Unit	`setPadCharacter(padChar: Char)` [icu] Padding: Sets the character used to pad numbers that are narrower than the width specified in `setFormatWidth`.
open Unit	`setPadPosition(padPos: Int)` [icu] Padding: Sets the position where to insert the pad character when narrower than the width specified in `setFormatWidth`.
open Unit	`setParseBigDecimal(value: Boolean)` Whether to make #parse prefer returning a `android.icu.math.BigDecimal` when possible.
open Unit	`setParseCaseSensitive(value: Boolean)` [icu] Specifies whether parsing should require cases to match in affixes, exponent separators, and currency codes.
open Unit	`setParseIntegerOnly(parseIntegerOnly: Boolean)` Parsing: Sets whether to ignore the fraction part of a number when parsing (defaults to false).
open Unit	`setParseMaxDigits(maxDigits: Int)`
open Unit	`setParseNoExponent(value: Boolean)` [icu] Specifies whether to stop parsing when an exponent separator is encountered.
open Unit	`setParseStrict(parseStrict: Boolean)` [icu] Sets whether strict parsing is in effect.
open Unit	`setPositivePrefix(prefix: String!)` Affixes: Sets the string to prepend to positive numbers.
open Unit	`setPositiveSuffix(suffix: String!)` Affixes: Sets the string to append to positive numbers.
open Unit	`setRoundingIncrement(increment: BigDecimal!)` [icu] Rounding and Digit Limits: Sets an increment, or interval, to which numbers are rounded.
open Unit	`setRoundingIncrement(increment: BigDecimal!)` [icu] Rounding and Digit Limits: Overload of `setRoundingIncrement(java.math.BigDecimal)`.
open Unit	`setRoundingIncrement(increment: Double)` [icu] Rounding and Digit Limits: Overload of `setRoundingIncrement(java.math.BigDecimal)`.
open Unit	`setRoundingMode(roundingMode: Int)` Rounding and Digit Limits: Sets the `RoundingMode` used to round numbers.
open Unit	`setScientificNotation(useScientific: Boolean)` [icu] Scientific Notation: Sets whether this formatter should print in scientific (exponential) notation.
open Unit	`setSecondaryGroupingSize(width: Int)` [icu] Grouping: Sets the secondary grouping size (distance between grouping separators after the first separator) used when formatting large numbers.
open Unit	`setSignAlwaysShown(value: Boolean)` Sets whether to always shown the plus sign ('+' in en) on positive numbers.
open Unit	`setSignificantDigitsUsed(useSignificantDigits: Boolean)` [icu] Rounding and Digit Limits: Sets whether significant digits are to be used in rounding.
open String!	`toLocalizedPattern()` Calls `toPattern` and converts the string to localized notation.
open String!	`toPattern()` Serializes this formatter object to a decimal format pattern string.
open String	`toString()` Returns the default value of toString() with extra DecimalFormat-specific information appended to the end of the string.

Inherited functions

From class NumberFormat

`StringBuffer!`	`format(number: Any!, toAppendTo: StringBuffer!, pos: FieldPosition!)` Formats a number and appends the resulting text to the given string buffer. [icu] Note: recognizes `BigInteger` and `BigDecimal` objects.
`String!`	`format(number: Double)` Specialization of format.
`String!`	`format(number: Long)` Specialization of format.
`String!`	`format(number: BigInteger!)` [icu] Convenience method to format a BigInteger.
`String!`	`format(number: BigDecimal!)` Convenience method to format a BigDecimal.
`String!`	`format(number: BigDecimal!)` [icu] Convenience method to format an ICU BigDecimal.
`String!`	`format(currAmt: CurrencyAmount!)` [icu] Convenience method to format a CurrencyAmount.
`Array<Locale!>!`	`getAvailableLocales()` Returns the list of Locales for which NumberFormats are available.
`DisplayContext!`	`getContext(type: DisplayContext.Type!)` [icu] Get the formatter's DisplayContext value for the specified DisplayContext.Type, such as CAPITALIZATION.
`NumberFormat!`	`getCurrencyInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a currency format for the current default `FORMAT` locale.
`NumberFormat!`	`getCurrencyInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a currency format for the specified locale.
`NumberFormat!`	`getCurrencyInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a currency format for the specified locale.
`NumberFormat!`	`getInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns the default number format for the current default `FORMAT` locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getIntegerInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale-dependent.
`NumberFormat!`	`getInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale-dependent.
`NumberFormat!`	`getInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale-dependent.
`NumberFormat!`	`getInstance(style: Int)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a specific style number format for default `FORMAT` locale.
`NumberFormat!`	`getInstance(inLocale: Locale!, style: Int)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a specific style number format for a specific locale.
`NumberFormat!`	`getInstance(desiredLocale: ULocale!, choice: Int)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a specific style number format for a specific locale.
`NumberFormat!`	`getIntegerInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns an integer number format for the current default `FORMAT` locale. The returned number format is configured to round floating point numbers to the nearest integer using IEEE half-even rounding (see `ROUND_HALF_EVEN`) for formatting, and to parse only the integer part of an input string (see `isParseIntegerOnly`).
`NumberFormat!`	`getIntegerInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns an integer number format for the specified locale. The returned number format is configured to round floating point numbers to the nearest integer using IEEE half-even rounding (see `ROUND_HALF_EVEN`) for formatting, and to parse only the integer part of an input string (see `isParseIntegerOnly`).
`NumberFormat!`	`getIntegerInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns an integer number format for the specified locale. The returned number format is configured to round floating point numbers to the nearest integer using IEEE half-even rounding (see `ROUND_HALF_EVEN`) for formatting, and to parse only the integer part of an input string (see `isParseIntegerOnly`).
`NumberFormat!`	`getNumberInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a general-purpose number format for the current default `FORMAT` locale.
`NumberFormat!`	`getNumberInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a general-purpose number format for the specified locale.
`NumberFormat!`	`getNumberInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a general-purpose number format for the specified locale.
`String!`	`getPattern(forLocale: ULocale!, choice: Int)` Returns the pattern for the provided locale and choice.
`NumberFormat!`	`getPercentInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a percentage format for the current default `FORMAT` locale.
`NumberFormat!`	`getPercentInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. Returns a percentage format for the specified locale.
`NumberFormat!`	`getPercentInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a percentage format for the specified locale.
`NumberFormat!`	`getScientificInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a scientific format for the current default `FORMAT` locale.
`NumberFormat!`	`getScientificInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a scientific format for the specified locale.
`NumberFormat!`	`getScientificInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat. [icu] Returns a scientific format for the specified locale.
`Number!`	`parse(text: String!)` Parses text from the beginning of the given string to produce a number. The method might not use the entire text of the given string.
`Any!`	`parseObject(source: String!, parsePosition: ParsePosition!)` Parses text from a string to produce a number.
`Unit`	`setContext(context: DisplayContext!)` [icu] Set a particular DisplayContext value in the formatter, such as CAPITALIZATION_FOR_STANDALONE.

Constants

MINIMUM_GROUPING_DIGITS_AUTO

Added in API level 33

static val MINIMUM_GROUPING_DIGITS_AUTO: Int

[icu] Constant for setMinimumGroupingDigits(int) to specify display grouping using the default strategy for all locales.

Value: -2

See Also

#setMinimumGroupingDigits(int)
#MINIMUM_GROUPING_DIGITS_MIN2

MINIMUM_GROUPING_DIGITS_MIN2

Added in API level 33

static val MINIMUM_GROUPING_DIGITS_MIN2: Int

[icu] Constant for setMinimumGroupingDigits(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).

Value: -3

See Also

#setMinimumGroupingDigits(int)
#MINIMUM_GROUPING_DIGITS_AUTO

Parameters
`pattern`	String!: A pattern string such as "#,##0.00" conforming to UTS #35.
`symbols`	DecimalFormatSymbols!: The set of symbols to be used.

Parameters
`pattern`	String!: a non-localized pattern string
`symbols`	DecimalFormatSymbols!: the set of symbols to be used
`infoInput`	CurrencyPluralInfo!: the information used for currency plural format, including currency plural patterns and plural rules.
`style`	Int: 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;

Exceptions
`java.lang.NullPointerException`	if obj is null.
`java.lang.IllegalArgumentException`	when the Format cannot format the given object.

Parameters
`text`	CharSequence!: the text to parse
`pos`	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.

Parameters
`theCurrency`	new currency object to use. May be null for some subclasses.
`currency`	Currency!: The currency to use.

Parameters
`newValue`	true to use grouping.
`enabled`	Boolean: true to enable grouping separators; false to disable them.

Parameters
`newValue`	the maximum number of fraction digits to be shown; if less than zero, then zero is used. The concrete subclass may enforce an upper limit to this value appropriate to the numeric type being formatted.
`value`	Int: The maximum number of integer digits after the decimal separator.

Parameters
`newValue`	the maximum number of integer digits to be shown; if less than zero, then zero is used. Subclasses might enforce an upper limit to this value appropriate to the numeric type being formatted.
`value`	Int: The maximum number of digits before the decimal separator.

Parameters
`newValue`	the minimum number of fraction digits to be shown; if less than zero, then zero is used. Subclasses might enforce an upper limit to this value appropriate to the numeric type being formatted.
`value`	Int: The minimum number of integer digits after the decimal separator.

Parameters
`newValue`	the minimum number of integer digits to be shown; if less than zero, then zero is used. Subclasses might enforce an upper limit to this value appropriate to the numeric type being formatted.
`value`	Int: The minimum number of digits before the decimal separator.

Exceptions
`java.lang.IllegalArgumentException`	If the given multiplier is zero.
`java.lang.ArithmeticException`	when inverting multiplier produces a non-terminating decimal result in conjunction with MathContext of unlimited precision.

Parameters
`value`	true if this should parse integers only
`parseIntegerOnly`	Boolean: true to ignore fractional parts of numbers when parsing; false to consume fractional parts.

DecimalFormat

Example Usage

Properties and Symbols

Rounding

Pattern Strings

Pattern String BNF

Parsing

Thread Safety and Best Practices

Summary

Constants

MINIMUM_GROUPING_DIGITS_AUTO

MINIMUM_GROUPING_DIGITS_MIN2

PAD_AFTER_PREFIX

PAD_AFTER_SUFFIX

PAD_BEFORE_PREFIX

PAD_BEFORE_SUFFIX

Public constructors

DecimalFormat

DecimalFormat

DecimalFormat

DecimalFormat

Public methods

applyLocalizedPattern

applyPattern

areSignificantDigitsUsed

clone

equals

format

format

format

format

format

format

formatToCharacterIterator

getCurrency

getCurrencyPluralInfo

getCurrencyUsage

getDecimalFormatSymbols

getFormatWidth

getGroupingSize

getMathContext

getMathContextICU

getMaximumFractionDigits

getMaximumIntegerDigits

getMaximumSignificantDigits

getMinimumExponentDigits

getMinimumFractionDigits

getMinimumGroupingDigits

getMinimumIntegerDigits

getMinimumSignificantDigits

getMultiplier

getNegativePrefix

getNegativeSuffix

getPadCharacter

getPadPosition

getParseMaxDigits

getPositivePrefix

getPositiveSuffix

getRoundingIncrement

getRoundingMode

getSecondaryGroupingSize

hashCode

isDecimalPatternMatchRequired

isDecimalSeparatorAlwaysShown

isExponentSignAlwaysShown

isGroupingUsed

isParseBigDecimal

isParseCaseSensitive

isParseIntegerOnly

isParseNoExponent

isParseStrict

isScientificNotation

isSignAlwaysShown

parse

parseCurrency

setCurrency

setCurrencyPluralInfo

setCurrencyUsage

setDecimalFormatSymbols

setDecimalPatternMatchRequired