Most visited

Recently visited

Added in API level 24

DecimalFormat

public class DecimalFormat
extends NumberFormat

java.lang.Object
   ↳ java.text.Format
     ↳ android.icu.text.UFormat
       ↳ android.icu.text.NumberFormat
         ↳ android.icu.text.DecimalFormat
Known Direct Subclasses


[icu enhancement] ICU's replacement for DecimalFormat. Methods, fields, and other functionality specific to ICU are labeled '[icu]'. DecimalFormat is a concrete subclass of NumberFormat that formats decimal numbers. It has a variety of features designed to make it possible to parse and format numbers in any locale, including support for Western, Arabic, or Indic digits. It also supports different flavors of numbers, including integers ("123"), fixed-point numbers ("123.4"), scientific notation ("1.23E4"), percentages ("12%"), and currency amounts ("$123.00", "USD123.00", "123.00 US dollars"). All of these flavors can be easily localized.

To obtain a NumberFormat for a specific locale (including the default locale) call one of NumberFormat's factory methods such as getInstance(). Do not call the DecimalFormat constructors directly, unless you know what you are doing, since the NumberFormat factory methods may return subclasses other than DecimalFormat. If you need to customize the format object, do something like this:

 NumberFormat f = NumberFormat.getInstance(loc);
 if (f instanceof DecimalFormat) {
     ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true);
 }

Example Usage Print out a number using the localized number, currency, and percent format for each locale.

 Locale[] locales = NumberFormat.getAvailableLocales();
 double myNumber = -1234.56;
 NumberFormat format;
 for (int j=0; j<3; ++j) {
     System.out.println("FORMAT");
     for (int i = 0; i < locales.length; ++i) {
         if (locales[i].getCountry().length() == 0) {
            // Skip language-only locales
            continue;
         }
         System.out.print(locales[i].getDisplayName());
         switch (j) {
         case 0:
             format = NumberFormat.getInstance(locales[i]); break;
         case 1:
             format = NumberFormat.getCurrencyInstance(locales[i]); break;
         default:
             format = NumberFormat.getPercentInstance(locales[i]); break;
         }
         try {
             // Assume format is a DecimalFormat
             System.out.print(": " + ((DecimalFormat) format).toPattern()
                              + " -> " + form.format(myNumber));
         } catch (Exception e) {}
         try {
             System.out.println(" -> " + format.parse(form.format(myNumber)));
         } catch (ParseException e) {}
     }
 }

Another example use getInstance(style).
Print out a number using the localized number, currency, percent, scientific, integer, iso currency, and plural currency format for each locale.

 ULocale locale = new ULocale("en_US");
 double myNumber = 1234.56;
 for (int j=NumberFormat.NUMBERSTYLE; j<=NumberFormat.PLURALCURRENCYSTYLE; ++j) {
     NumberFormat format = NumberFormat.getInstance(locale, j);
     try {
         // Assume format is a DecimalFormat
         System.out.print(": " + ((DecimalFormat) format).toPattern()
                          + " -> " + form.format(myNumber));
     } catch (Exception e) {}
     try {
         System.out.println(" -> " + format.parse(form.format(myNumber)));
     } catch (ParseException e) {}
 }

Patterns

A DecimalFormat consists of a pattern and a set of symbols. The pattern may be set directly using applyPattern(String), or indirectly using other API methods which manipulate aspects of the pattern, such as the minimum number of integer digits. The symbols are stored in a DecimalFormatSymbols object. When using the NumberFormat factory methods, the pattern and symbols are read from ICU's locale data.

Special Pattern Characters

Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. For example, the '#' character is replaced by a localized digit. Often the replacement character is the same as the pattern character; in the U.S. locale, the ',' grouping character is replaced by ','. However, the replacement is still happening, and if the symbols are modified, the grouping character changes. Some special characters affect the behavior of the formatter by their presence; for example, if the percent character is seen, then the value is multiplied by 100 before being displayed.

To insert a special character in a pattern as a literal, that is, without any special meaning, the character must be quoted. There are some exceptions to this which are noted below.

The characters listed here are used in non-localized patterns. Localized patterns use the corresponding characters taken from this formatter's DecimalFormatSymbols object instead, and these characters lose their special status. Two exceptions are the currency sign and quote, which are not localized.

Symbol Location Localized? Meaning
0 Number Yes Digit
1-9 Number Yes '1' through '9' indicate rounding.
@ Number No Significant digit
# Number Yes Digit, zero shows as absent
. Number Yes Decimal separator or monetary decimal separator
- Number Yes Minus sign
, Number Yes Grouping separator
E Number Yes Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
+ Exponent Yes Prefix positive exponents with localized plus sign. Need not be quoted in prefix or suffix.
; Subpattern boundary Yes Separates positive and negative subpatterns
% Prefix or suffix Yes Multiply by 100 and show as percentage
\u2030 Prefix or suffix Yes Multiply by 1000 and show as per mille
¤ (\u00A4) Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If tripled, replaced by currency plural names, for example, "US dollar" or "US dollars" for America. If present in a pattern, the monetary decimal separator is used instead of the decimal separator.
' Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".
* Prefix or suffix boundary Yes Pad escape, precedes pad character

A DecimalFormat pattern contains a postive and negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, a numeric part, and a suffix. If there is no explicit negative subpattern, the negative subpattern is the localized minus sign prefixed to the positive subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are ignored in the negative subpattern. That means that "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)".

The prefixes, suffixes, and various symbols used for infinity, digits, thousands separators, decimal separators, etc. may be set to arbitrary values, and they will appear properly during formatting. However, care must be taken that the symbols and strings do not conflict, or parsing will be unreliable. For example, either the positive and negative prefixes or the suffixes must be distinct for parse(String) to be able to distinguish positive from negative values. Another example is that the decimal separator and thousands separator should be distinct characters, or parsing will be impossible.

The grouping separator is a character that separates clusters of integer digits to make large numbers more legible. It commonly used for thousands, but in some locales it separates ten-thousands. The grouping size is the number of digits between the grouping separators, such as 3 for "100,000,000" or 4 for "1 0000 0000". There are actually two different grouping sizes: One used for the least significant integer digits, the primary grouping size, and one used for all others, the secondary grouping size. In most locales these are the same, but sometimes they are different. For example, if the primary grouping interval is 3, and the secondary is 2, then this corresponds to the pattern "#,##,##0", and the number 123456789 is formatted as "12,34,56,789". If a pattern contains multiple grouping separators, the interval between the last one and the end of the integer defines the primary grouping size, and the interval between the last two defines the secondary grouping size. All others are ignored, so "#,##,###,####" == "###,###,####" == "##,#,###,####".

Illegal patterns, such as "#.#.#" or "#.###,###", will cause DecimalFormat to throw an IllegalArgumentException with a message that describes the problem.

Pattern BNF

 pattern    := subpattern (';' subpattern)?
 subpattern := prefix? number exponent? suffix?
 number     := (integer ('.' fraction)?) | sigDigits
 prefix     := '\u0000'..'\uFFFD' - specialCharacters
 suffix     := '\u0000'..'\uFFFD' - specialCharacters
 integer    := '#'* '0'* '0'
 fraction   := '0'* '#'*
 sigDigits  := '#'* '@' '@'* '#'*
 exponent   := 'E' '+'? '0'* '0'
 padSpec    := '*' padChar
 padChar    := '\u0000'..'\uFFFD' - quote
  
 Notation:
   X*       0 or more instances of X
   X?       0 or 1 instances of X
   X|Y      either X or Y
   C..D     any character from C up to D, inclusive
   S-T      characters in S, except those in T
 
The first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers.

Not indicated in the BNF syntax above:

Parsing

DecimalFormat parses all Unicode characters that represent decimal digits, as defined by digit(int). In addition, DecimalFormat also recognizes as digits the ten consecutive characters starting with the localized zero digit defined in the DecimalFormatSymbols object. During formatting, the DecimalFormatSymbols-based digits are output.

During parsing, grouping separators are ignored.

For currency parsing, the formatter is able to parse every currency style formats no matter which style the formatter is constructed with. For example, a formatter instance gotten from NumberFormat.getInstance(ULocale, NumberFormat.CURRENCYSTYLE) can parse formats such as "USD1.00" and "3.00 US dollars".

If parse(String, ParsePosition) fails to parse a string, it returns null and leaves the parse position unchanged. The convenience method parse(String) indicates parse failure by throwing a ParseException.

Parsing an extremely large or small absolute value (such as 1.0E10000 or 1.0E-10000) requires huge memory allocation for representing the parsed number. Such input may expose a risk of DoS attacks. To prevent huge memory allocation triggered by such inputs, DecimalFormat internally limits of maximum decimal digits to be 1000. Thus, an input string resulting more than 1000 digits in plain decimal representation (non-exponent) will be treated as either overflow (positive/negative infinite) or underflow (+0.0/-0.0).

Formatting

Formatting is guided by several parameters, all of which can be specified either using a pattern or using the API. The following description applies to formats that do not use scientific notation or significant digits.

Special Values

NaN is represented as a single character, typically \uFFFD. This character is determined by the DecimalFormatSymbols object. This is the only value for which the prefixes and suffixes are not used.

Infinity is represented as a single character, typically \u221E, with the positive or negative prefixes and suffixes applied. The infinity character is determined by the DecimalFormatSymbols object.

Scientific Notation

Numbers in scientific notation are expressed as the product of a mantissa and a power of ten, for example, 1234 can be expressed as 1.234 x 103. The mantissa is typically in the half-open interval [1.0, 10.0) or sometimes [0.0, 1.0), but it need not be. DecimalFormat supports arbitrary mantissas. DecimalFormat can be instructed to use scientific notation through the API or through the pattern. In a pattern, the exponent character immediately followed by one or more digit characters indicates scientific notation. Example: "0.###E0" formats the number 1234 as "1.234E3".

Significant Digits

DecimalFormat has two ways of controlling how many digits are shows: (a) significant digits counts, or (b) integer and fraction digit counts. Integer and fraction digit counts are described above. When a formatter is using significant digits counts, the number of integer and fraction digits is not specified directly, and the formatter settings for these counts are ignored. Instead, the formatter uses however many integer and fraction digits are required to display the specified number of significant digits. Examples:
Pattern Minimum significant digits Maximum significant digits Number Output of format()
@@@ 3 3 12345 12300
@@@ 3 3 0.12345 0.123
@@## 2 4 3.14159 3.142
@@## 2 4 1.23004 1.23

Padding

DecimalFormat supports padding the result of format(BigDecimal) to a specific width. Padding may be specified either through the API or through the pattern syntax. In a pattern the pad escape character, followed by a single pad character, causes padding to be parsed and formatted. The pad escape character is '*' in unlocalized patterns, and can be localized using setPadEscape(char). For example, "$*x#,##0.00" formats 123 to "$xx123.00", and 1234 to "$1,234.00".

Rounding

DecimalFormat supports rounding to a specific increment. For example, 1230 rounded to the nearest 50 is 1250. 1.234 rounded to the nearest 0.65 is 1.3. The rounding increment may be specified through the API or in a pattern. To specify a rounding increment in a pattern, include the increment in the pattern itself. "#,#50" specifies a rounding increment of 50. "#,##0.05" specifies a rounding increment of 0.05.

Synchronization

DecimalFormat objects are not synchronized. Multiple threads should not access one formatter concurrently.

See also:

Summary

Constants

int PAD_AFTER_PREFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted after the prefix.

int PAD_AFTER_SUFFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted after the suffix.

int PAD_BEFORE_PREFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted before the prefix.

int PAD_BEFORE_SUFFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted before the suffix.

Inherited constants

From class android.icu.text.NumberFormat

Public constructors

DecimalFormat()

Creates a DecimalFormat using the default pattern and symbols for the default FORMAT locale.

DecimalFormat(String pattern)

Creates a DecimalFormat from the given pattern and the symbols for the default FORMAT locale.

DecimalFormat(String pattern, DecimalFormatSymbols symbols)

Creates a DecimalFormat from the given pattern and symbols.

DecimalFormat(String pattern, DecimalFormatSymbols symbols, CurrencyPluralInfo infoInput, int style)

Creates a DecimalFormat from the given pattern, symbols, information used for currency plural format, and format style.

Public methods

void applyLocalizedPattern(String pattern)

Applies the given pattern to this Format object.

void applyPattern(String pattern)

Applies the given pattern to this Format object.

boolean areSignificantDigitsUsed()

[icu] Returns true if significant digits are in use or false if integer and fraction digit counts are in use.

Object clone()

Overrides clone.

boolean equals(Object obj)

Overrides equals.

StringBuffer format(BigInteger number, StringBuffer result, FieldPosition fieldPosition)

Formats a BigInteger number.

StringBuffer format(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)

Formats a BigDecimal number.

StringBuffer format(double number, StringBuffer result, FieldPosition fieldPosition)

Specialization of format.

StringBuffer format(BigDecimal number, StringBuffer result, FieldPosition fieldPosition)

Formats a BigDecimal number.

StringBuffer format(long number, StringBuffer result, FieldPosition fieldPosition)

Specialization of format.

AttributedCharacterIterator formatToCharacterIterator(Object obj)

Formats the object to an attributed string, and return the corresponding iterator.

CurrencyPluralInfo getCurrencyPluralInfo()

[icu] Returns a copy of the CurrencyPluralInfo used by this format.

Currency.CurrencyUsage getCurrencyUsage()

Returns the Currency Usage object used to display currency

DecimalFormatSymbols getDecimalFormatSymbols()

Returns a copy of the decimal format symbols used by this format.

int getFormatWidth()

Returns the width to which the output of format() is padded.

int getGroupingSize()

Returns the grouping size.

MathContext getMathContext()

[icu] Returns the MathContext used by this format.

MathContext getMathContextICU()

[icu] Returns the MathContext used by this format.

int getMaximumSignificantDigits()

[icu] Returns the maximum number of significant digits that will be displayed.

byte getMinimumExponentDigits()

[icu] Returns the minimum exponent digits that will be shown.

int getMinimumSignificantDigits()

[icu] Returns the minimum number of significant digits that will be displayed.

int getMultiplier()

Returns the multiplier for use in percent, permill, etc.

String getNegativePrefix()

Returns the negative prefix.

String getNegativeSuffix()

Returns the negative suffix.

char getPadCharacter()

[icu] Returns the character used to pad to the format width.

int getPadPosition()

[icu] Returns the position at which padding will take place.

int getParseMaxDigits()

Get the current maximum number of exponent digits when parsing a number.

String getPositivePrefix()

Returns the positive prefix.

String getPositiveSuffix()

Returns the positive suffix.

BigDecimal getRoundingIncrement()

[icu] Returns the rounding increment.

int getRoundingMode()

Returns the rounding mode.

int getSecondaryGroupingSize()

[icu] Returns the secondary grouping size.

int hashCode()

Overrides hashCode.

boolean isDecimalPatternMatchRequired()

[icu] Returns whether the input to parsing must contain a decimal mark if there is a decimal mark in the pattern.

boolean isDecimalSeparatorAlwaysShown()

Returns the behavior of the decimal separator with integers.

boolean isExponentSignAlwaysShown()

[icu] Returns whether the exponent sign is always shown.

boolean isParseBigDecimal()

Returns whether parse(String, ParsePosition) returns BigDecimal.

boolean isScientificNotation()

[icu] Returns whether or not scientific notation is used.

Number parse(String text, ParsePosition parsePosition)

Parses the given string, returning a Number object to represent the parsed value.

CurrencyAmount parseCurrency(CharSequence text, ParsePosition pos)

Parses text from the given string as a CurrencyAmount.

void setCurrency(Currency theCurrency)

Sets the Currency object used to display currency amounts.

void setCurrencyPluralInfo(CurrencyPluralInfo newInfo)

[icu] Sets the CurrencyPluralInfo used by this format.

void setCurrencyUsage(Currency.CurrencyUsage newUsage)

Sets the Currency Usage object used to display currency.

void setDecimalFormatSymbols(DecimalFormatSymbols newSymbols)

Sets the decimal format symbols used by this format.

void setDecimalPatternMatchRequired(boolean value)

When decimal match is not required, the input does not have to contain a decimal mark when there is a decimal mark specified in the pattern.

void setDecimalSeparatorAlwaysShown(boolean newValue)

Sets the behavior of the decimal separator with integers.

void setExponentSignAlwaysShown(boolean expSignAlways)

[icu] Sets whether the exponent sign is always shown.

void setFormatWidth(int width)

Sets the width to which the output of format() is padded.

void setGroupingSize(int newValue)

Sets the grouping size.

void setMathContext(MathContext newValue)

[icu] Sets the MathContext used by this format.

void setMathContextICU(MathContext newValue)

[icu] Sets the MathContext used by this format.

void setMaximumFractionDigits(int newValue)

Sets the maximum number of digits allowed in the fraction portion of a number.

void setMaximumIntegerDigits(int newValue)

Sets the maximum number of digits allowed in the integer portion of a number.

void setMaximumSignificantDigits(int max)

[icu] Sets the maximum number of significant digits that will be displayed.

void setMinimumExponentDigits(byte minExpDig)

[icu] Sets the minimum exponent digits that will be shown.

void setMinimumFractionDigits(int newValue)

Sets the minimum number of digits allowed in the fraction portion of a number.

void setMinimumIntegerDigits(int newValue)

Sets the minimum number of digits allowed in the integer portion of a number.

void setMinimumSignificantDigits(int min)

[icu] Sets the minimum number of significant digits that will be displayed.

void setMultiplier(int newValue)

Sets the multiplier for use in percent, permill, etc.

void setNegativePrefix(String newValue)

Sets the negative prefix.

void setNegativeSuffix(String newValue)

Sets the positive suffix.

void setPadCharacter(char padChar)

[icu] Sets the character used to pad to the format width.

void setPadPosition(int padPos)

[icu] Sets the position at which padding will take place.

void setParseBigDecimal(boolean value)

Sets whether parse(String, ParsePosition) returns BigDecimal.

void setParseMaxDigits(int newValue)

Set the maximum number of exponent digits when parsing a number.

void setPositivePrefix(String newValue)

Sets the positive prefix.

void setPositiveSuffix(String newValue)

Sets the positive suffix.

void setRoundingIncrement(BigDecimal newValue)

[icu] Sets the rounding increment.

void setRoundingIncrement(BigDecimal newValue)

[icu] Sets the rounding increment.

void setRoundingIncrement(double newValue)

[icu] Sets the rounding increment.

void setRoundingMode(int roundingMode)

Sets the rounding mode.

void setScientificNotation(boolean useScientific)

[icu] Sets whether or not scientific notation is used.

void setSecondaryGroupingSize(int newValue)

[icu] Sets the secondary grouping size.

void setSignificantDigitsUsed(boolean useSignificantDigits)

[icu] Sets whether significant digits are in use, or integer and fraction digit counts are in use.

String toLocalizedPattern()

Synthesizes a localized pattern string that represents the current state of this Format object.

String toPattern()

Synthesizes a pattern string that represents the current state of this Format object.

Inherited methods

From class android.icu.text.NumberFormat
From class java.text.Format
From class java.lang.Object

Constants

PAD_AFTER_PREFIX

Added in API level 24
int PAD_AFTER_PREFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted after the prefix.

See also:

Constant Value: 1 (0x00000001)

PAD_AFTER_SUFFIX

Added in API level 24
int PAD_AFTER_SUFFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted after the suffix.

See also:

Constant Value: 3 (0x00000003)

PAD_BEFORE_PREFIX

Added in API level 24
int PAD_BEFORE_PREFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted before the prefix.

See also:

Constant Value: 0 (0x00000000)

PAD_BEFORE_SUFFIX

Added in API level 24
int PAD_BEFORE_SUFFIX

[icu] Constant for getPadPosition() and setPadPosition(int) to specify pad characters inserted before the suffix.

See also:

Constant Value: 2 (0x00000002)

Public constructors

DecimalFormat

Added in API level 24
DecimalFormat ()

Creates a DecimalFormat using the default pattern and symbols for the default FORMAT locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

See also:

DecimalFormat

Added in API level 24
DecimalFormat (String pattern)

Creates a DecimalFormat from the given pattern and the symbols for the default FORMAT locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale.

Parameters
pattern String: A non-localized pattern string.
Throws
IllegalArgumentException if the given pattern is invalid.

See also:

DecimalFormat

Added in API level 24
DecimalFormat (String pattern, 
                DecimalFormatSymbols symbols)

Creates a DecimalFormat from the given pattern and symbols. Use this constructor when you need to completely customize the behavior of the format.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance. If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method.

Parameters
pattern String: a non-localized pattern string
symbols DecimalFormatSymbols: the set of symbols to be used
Throws
IllegalArgumentException if the given pattern is invalid

See also:

DecimalFormat

Added in API level 24
DecimalFormat (String pattern, 
                DecimalFormatSymbols symbols, 
                CurrencyPluralInfo infoInput, 
                int style)

Creates a DecimalFormat from the given pattern, symbols, information used for currency plural format, and format style. Use this constructor when you need to completely customize the behavior of the format.

To obtain standard formats for a given locale, use the factory methods on NumberFormat such as getInstance or getCurrencyInstance.

If you need only minor adjustments to a standard format, you can modify the format returned by a NumberFormat factory method using the setters.

If you want to completely customize a decimal format, using your own DecimalFormatSymbols (such as group separators) and your own information for currency plural formatting (such as plural rule and currency plural patterns), you can use this constructor.

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;

Public methods

applyLocalizedPattern

Added in API level 24
void applyLocalizedPattern (String pattern)

Applies the given pattern to this Format object. The pattern is assumed to be in a localized notation. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.

There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon

Example "#,#00.0#" -> 1,234.56

This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.

Example: "#,#00.0#;(#,#00.0#)" for negatives in parantheses.

In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.

Parameters
pattern String

applyPattern

Added in API level 24
void applyPattern (String pattern)

Applies the given pattern to this Format object. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.

There is no limit to integer digits are set by this routine, since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers, use a second pattern, separated by a semicolon

Example "#,#00.0#" -> 1,234.56

This means a minimum of 2 integer digits, 1 fraction digit, and a maximum of 2 fraction digits.

Example: "#,#00.0#;(#,#00.0#)" for negatives in parentheses.

In negative patterns, the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern.

Parameters
pattern String

areSignificantDigitsUsed

Added in API level 24
boolean areSignificantDigitsUsed ()

[icu] Returns true if significant digits are in use or false if integer and fraction digit counts are in use.

Returns
boolean true if significant digits are in use

clone

Added in API level 24
Object clone ()

Overrides clone.

Returns
Object a clone of this instance.

equals

Added in API level 24
boolean equals (Object obj)

Overrides equals.

Parameters
obj Object: the object to compare against
Returns
boolean true if the object is equal to this.

format

Added in API level 24
StringBuffer format (BigInteger number, 
                StringBuffer result, 
                FieldPosition fieldPosition)

Formats a BigInteger number.

Parameters
number BigInteger
result StringBuffer
fieldPosition FieldPosition
Returns
StringBuffer

format

Added in API level 24
StringBuffer format (BigDecimal number, 
                StringBuffer result, 
                FieldPosition fieldPosition)

Formats a BigDecimal number.

Parameters
number BigDecimal
result StringBuffer
fieldPosition FieldPosition
Returns
StringBuffer

format

Added in API level 24
StringBuffer format (double number, 
                StringBuffer result, 
                FieldPosition fieldPosition)

Specialization of format.

Parameters
number double
result StringBuffer
fieldPosition FieldPosition
Returns
StringBuffer

format

Added in API level 24
StringBuffer format (BigDecimal number, 
                StringBuffer result, 
                FieldPosition fieldPosition)

Formats a BigDecimal number.

Parameters
number BigDecimal
result StringBuffer
fieldPosition FieldPosition
Returns
StringBuffer

format

Added in API level 24
StringBuffer format (long number, 
                StringBuffer result, 
                FieldPosition fieldPosition)

Specialization of format.

Parameters
number long
result StringBuffer
fieldPosition FieldPosition
Returns
StringBuffer

formatToCharacterIterator

Added in API level 24
AttributedCharacterIterator formatToCharacterIterator (Object obj)

Formats the object to an attributed string, and return the corresponding iterator.

Parameters
obj Object: The object to format
Returns
AttributedCharacterIterator AttributedCharacterIterator describing the formatted value.

getCurrencyPluralInfo

Added in API level 24
CurrencyPluralInfo getCurrencyPluralInfo ()

[icu] Returns a copy of the CurrencyPluralInfo used by this format. It might return null if the decimal format is not a plural type currency decimal format. Plural type currency decimal format means either the pattern in the decimal format contains 3 currency signs, or the decimal format is initialized with PLURALCURRENCYSTYLE.

Returns
CurrencyPluralInfo desired CurrencyPluralInfo

See also:

getCurrencyUsage

Added in API level 24
Currency.CurrencyUsage getCurrencyUsage ()

Returns the Currency Usage object used to display currency

Returns
Currency.CurrencyUsage

getDecimalFormatSymbols

Added in API level 24
DecimalFormatSymbols getDecimalFormatSymbols ()

Returns a copy of the decimal format symbols used by this format.

Returns
DecimalFormatSymbols desired DecimalFormatSymbols

See also:

getFormatWidth

Added in API level 24
int getFormatWidth ()

Returns the width to which the output of format() is padded. The width is counted in 16-bit code units.

Returns
int the format width, or zero if no padding is in effect

See also:

getGroupingSize

Added in API level 24
int getGroupingSize ()

Returns the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "123,456.78", the grouping size is 3.

Returns
int

See also:

getMathContext

Added in API level 24
MathContext getMathContext ()

[icu] Returns the MathContext used by this format.

Returns
MathContext desired MathContext

See also:

getMathContextICU

Added in API level 24
MathContext getMathContextICU ()

[icu] Returns the MathContext used by this format.

Returns
MathContext desired MathContext

See also:

getMaximumSignificantDigits

Added in API level 24
int getMaximumSignificantDigits ()

[icu] Returns the maximum number of significant digits that will be displayed. This value has no effect unless areSignificantDigitsUsed() returns true.

Returns
int the most significant digits that will be shown

getMinimumExponentDigits

Added in API level 24
byte getMinimumExponentDigits ()

[icu] Returns the minimum exponent digits that will be shown.

Returns
byte the minimum exponent digits that will be shown

See also:

getMinimumSignificantDigits

Added in API level 24
int getMinimumSignificantDigits ()

[icu] Returns the minimum number of significant digits that will be displayed. This value has no effect unless areSignificantDigitsUsed() returns true.

Returns
int the fewest significant digits that will be shown

getMultiplier

Added in API level 24
int getMultiplier ()

Returns the multiplier for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the multiplier to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "‱" and the multiplier to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23

Returns
int the multiplier

getNegativePrefix

Added in API level 24
String getNegativePrefix ()

Returns the negative prefix.

Examples: -123, ($123) (with negative suffix), sFr-123

Returns
String the prefix

getNegativeSuffix

Added in API level 24
String getNegativeSuffix ()

Returns the negative suffix.

Examples: -123%, ($123) (with positive suffixes)

Returns
String the suffix

getPadCharacter

Added in API level 24
char getPadCharacter ()

[icu] Returns the character used to pad to the format width. The default is ' '.

Returns
char the pad character

See also:

getPadPosition

Added in API level 24
int getPadPosition ()

[icu] Returns the position at which padding will take place. This is the location at which padding will be inserted if the result of format() is shorter than the format width.

Returns
int the pad position, one of PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, or PAD_AFTER_SUFFIX.

See also:

getParseMaxDigits

Added in API level 24
int getParseMaxDigits ()

Get the current maximum number of exponent digits when parsing a number.

Returns
int the maximum number of exponent digits for parsing

getPositivePrefix

Added in API level 24
String getPositivePrefix ()

Returns the positive prefix.

Examples: +123, $123, sFr123

Returns
String the prefix

getPositiveSuffix

Added in API level 24
String getPositiveSuffix ()

Returns the positive suffix.

Example: 123%

Returns
String the suffix

getRoundingIncrement

Added in API level 24
BigDecimal getRoundingIncrement ()

[icu] Returns the rounding increment.

Returns
BigDecimal A positive rounding increment, or null if a custom rounding increment is not in effect.

See also:

getRoundingMode

Added in API level 24
int getRoundingMode ()

Returns the rounding mode.

Returns
int A rounding mode, between BigDecimal.ROUND_UP and BigDecimal.ROUND_UNNECESSARY.

See also:

getSecondaryGroupingSize

Added in API level 24
int getSecondaryGroupingSize ()

[icu] Returns the secondary grouping size. In some locales one grouping interval is used for the least significant integer digits (the primary grouping size), and another is used for all others (the secondary grouping size). A formatter supporting a secondary grouping size will return a positive integer unequal to the primary grouping size returned by getGroupingSize(). For example, if the primary grouping size is 4, and the secondary grouping size is 2, then the number 123456789 formats as "1,23,45,6789", and the pattern appears as "#,##,###0".

Returns
int the secondary grouping size, or a value less than one if there is none

See also:

hashCode

Added in API level 24
int hashCode ()

Overrides hashCode.

Returns
int a hash code value for this object.

isDecimalPatternMatchRequired

Added in API level 24
boolean isDecimalPatternMatchRequired ()

[icu] Returns whether the input to parsing must contain a decimal mark if there is a decimal mark in the pattern.

Returns
boolean true if input must contain a match to decimal mark in pattern

isDecimalSeparatorAlwaysShown

Added in API level 24
boolean isDecimalSeparatorAlwaysShown ()

Returns the behavior of the decimal separator with integers. (The decimal separator will always appear with decimals.)

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345

Returns
boolean

isExponentSignAlwaysShown

Added in API level 24
boolean isExponentSignAlwaysShown ()

[icu] Returns whether the exponent sign is always shown.

Returns
boolean true if the exponent is always prefixed with either the localized minus sign or the localized plus sign, false if only negative exponents are prefixed with the localized minus sign.

See also:

isParseBigDecimal

Added in API level 24
boolean isParseBigDecimal ()

Returns whether parse(String, ParsePosition) returns BigDecimal.

Returns
boolean true if parse(String, ParsePosition) returns BigDecimal.

isScientificNotation

Added in API level 24
boolean isScientificNotation ()

[icu] Returns whether or not scientific notation is used.

Returns
boolean true if this object formats and parses scientific notation

See also:

parse

Added in API level 24
Number parse (String text, 
                ParsePosition parsePosition)

Parses the given string, returning a Number object to represent the parsed value. Double objects are returned to represent non-integral values which cannot be stored in a BigDecimal. These are NaN, infinity, -infinity, and -0.0. If isParseBigDecimal() is false (the default), all other values are returned as Long, BigInteger, or BigDecimal values, in that order of preference. If isParseBigDecimal() is true, all other values are returned as BigDecimal valuse. If the parse fails, null is returned.

Parameters
text String: the string to be parsed
parsePosition ParsePosition: defines the position where parsing is to begin, and upon return, the position where parsing left off. If the position has not changed upon return, then parsing failed.
Returns
Number a Number object with the parsed value or null if the parse failed

parseCurrency

Added in API level 24
CurrencyAmount parseCurrency (CharSequence text, 
                ParsePosition pos)

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.

Parameters
text CharSequence: the text to parse
pos ParsePosition: 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
CurrencyAmount a CurrencyAmount, or null upon failure

setCurrency

Added in API level 24
void setCurrency (Currency theCurrency)

Sets the Currency object used to display currency amounts. This takes effect immediately, if this format is a currency format. If this format is not a currency format, then the currency object is used if and when this object becomes a currency format through the application of a new pattern.

Parameters
theCurrency Currency: new currency object to use. Must not be null.

setCurrencyPluralInfo

Added in API level 24
void setCurrencyPluralInfo (CurrencyPluralInfo newInfo)

[icu] Sets the CurrencyPluralInfo used by this format. The format uses a copy of the provided information.

Parameters
newInfo CurrencyPluralInfo: desired CurrencyPluralInfo

See also:

setCurrencyUsage

Added in API level 24
void setCurrencyUsage (Currency.CurrencyUsage newUsage)

Sets the Currency Usage object used to display currency. This takes effect immediately, if this format is a currency format.

Parameters
newUsage Currency.CurrencyUsage: new currency context object to use.

setDecimalFormatSymbols

Added in API level 24
void setDecimalFormatSymbols (DecimalFormatSymbols newSymbols)

Sets the decimal format symbols used by this format. The format uses a copy of the provided symbols.

Parameters
newSymbols DecimalFormatSymbols: desired DecimalFormatSymbols

See also:

setDecimalPatternMatchRequired

Added in API level 24
void setDecimalPatternMatchRequired (boolean value)

When decimal match is not required, the input does not have to contain a decimal mark when there is a decimal mark specified in the pattern.

Parameters
value boolean: true if input must contain a match to decimal mark in pattern Default is false.

setDecimalSeparatorAlwaysShown

Added in API level 24
void setDecimalSeparatorAlwaysShown (boolean newValue)

Sets the behavior of the decimal separator with integers. (The decimal separator will always appear with decimals.)

This only affects formatting, and only where there might be no digits after the decimal point, e.g., if true, 3456.00 -> "3,456." if false, 3456.00 -> "3456" This is independent of parsing. If you want parsing to stop at the decimal point, use setParseIntegerOnly.

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345

Parameters
newValue boolean

setExponentSignAlwaysShown

Added in API level 24
void setExponentSignAlwaysShown (boolean expSignAlways)

[icu] Sets whether the exponent sign is always shown. This has no effect unless scientific notation is in use.

Parameters
expSignAlways boolean: true if the exponent is always prefixed with either the localized minus sign or the localized plus sign, false if only negative exponents are prefixed with the localized minus sign.

See also:

setFormatWidth

Added in API level 24
void setFormatWidth (int width)

Sets the width to which the output of format() is padded. The width is counted in 16-bit code units. This method also controls whether padding is enabled.

Parameters
width int: the width to which to pad the result of format(), or zero to disable padding
Throws
IllegalArgumentException if width is < 0

See also:

setGroupingSize

Added in API level 24
void setGroupingSize (int newValue)

Sets the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "123,456.78", the grouping size is 3.

Parameters
newValue int

See also:

setMathContext

Added in API level 24
void setMathContext (MathContext newValue)

[icu] Sets the MathContext used by this format.

Parameters
newValue MathContext: desired MathContext

See also:

setMathContextICU

Added in API level 24
void setMathContextICU (MathContext newValue)

[icu] Sets the MathContext used by this format.

Parameters
newValue MathContext: desired MathContext

See also:

setMaximumFractionDigits

Added in API level 24
void setMaximumFractionDigits (int newValue)

Sets the maximum number of digits allowed in the fraction portion of a number. This override limits the fraction digit count to 340.

Parameters
newValue int: 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.

See also:

setMaximumIntegerDigits

Added in API level 24
void setMaximumIntegerDigits (int newValue)

Sets the maximum number of digits allowed in the integer portion of a number. This override limits the integer digit count to 2,000,000,000 to match ICU4C.

Parameters
newValue int: 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.

See also:

setMaximumSignificantDigits

Added in API level 24
void setMaximumSignificantDigits (int max)

[icu] Sets the maximum number of significant digits that will be displayed. If max is less than one then it is set to one. If the minimum significant digits count is greater than max, then it is set to max. This function also enables the use of significant digits by this formatter - areSignificantDigitsUsed() will return true.

Parameters
max int: the most significant digits to be shown

setMinimumExponentDigits

Added in API level 24
void setMinimumExponentDigits (byte minExpDig)

[icu] Sets the minimum exponent digits that will be shown. This has no effect unless scientific notation is in use.

Parameters
minExpDig byte: a value >= 1 indicating the fewest exponent digits that will be shown
Throws
IllegalArgumentException if minExpDig < 1

See also:

setMinimumFractionDigits

Added in API level 24
void setMinimumFractionDigits (int newValue)

Sets the minimum number of digits allowed in the fraction portion of a number. This override limits the fraction digit count to 340.

Parameters
newValue int: 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.

See also:

setMinimumIntegerDigits

Added in API level 24
void setMinimumIntegerDigits (int newValue)

Sets the minimum number of digits allowed in the integer portion of a number. This override limits the integer digit count to 309.

Parameters
newValue int: 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.

See also:

setMinimumSignificantDigits

Added in API level 24
void setMinimumSignificantDigits (int min)

[icu] Sets the minimum number of significant digits that will be displayed. If min is less than one then it is set to one. If the maximum significant digits count is less than min, then it is set to min. This function also enables the use of significant digits by this formatter - areSignificantDigitsUsed() will return true.

Parameters
min int: the fewest significant digits to be shown

setMultiplier

Added in API level 24
void setMultiplier (int newValue)

Sets the multiplier for use in percent, permill, etc. For a percentage, set the suffixes to have "%" and the multiplier to be 100. (For Arabic, use arabic percent symbol). For a permill, set the suffixes to have "‱" and the multiplier to be 1000.

Examples: with 100, 1.23 -> "123", and "123" -> 1.23

Parameters
newValue int: the multiplier

setNegativePrefix

Added in API level 24
void setNegativePrefix (String newValue)

Sets the negative prefix.

Examples: -123, ($123) (with negative suffix), sFr-123

Parameters
newValue String: the prefix

setNegativeSuffix

Added in API level 24
void setNegativeSuffix (String newValue)

Sets the positive suffix.

Examples: 123%

Parameters
newValue String: the suffix

setPadCharacter

Added in API level 24
void setPadCharacter (char padChar)

[icu] Sets the character used to pad to the format width. If padding is not enabled, then this will take effect if padding is later enabled.

Parameters
padChar char: the pad character

See also:

setPadPosition

Added in API level 24
void setPadPosition (int padPos)

[icu] Sets the position at which padding will take place. This is the location at which padding will be inserted if the result of format() is shorter than the format width. This has no effect unless padding is enabled.

Parameters
padPos int: the pad position, one of PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_SUFFIX, or PAD_AFTER_SUFFIX.
Throws
IllegalArgumentException if the pad position in unrecognized

See also:

setParseBigDecimal

Added in API level 24
void setParseBigDecimal (boolean value)

Sets whether parse(String, ParsePosition) returns BigDecimal. The default value is false.

Parameters
value boolean: true if parse(String, ParsePosition) returns BigDecimal.

setParseMaxDigits

Added in API level 24
void setParseMaxDigits (int newValue)

Set the maximum number of exponent digits when parsing a number. If the limit is set too high, an OutOfMemoryException may be triggered. The default value is 1000.

Parameters
newValue int: the new limit

setPositivePrefix

Added in API level 24
void setPositivePrefix (String newValue)

Sets the positive prefix.

Examples: +123, $123, sFr123

Parameters
newValue String: the prefix

setPositiveSuffix

Added in API level 24
void setPositiveSuffix (String newValue)

Sets the positive suffix.

Example: 123%

Parameters
newValue String: the suffix

setRoundingIncrement

Added in API level 24
void setRoundingIncrement (BigDecimal newValue)

[icu] Sets the rounding increment. In the absence of a rounding increment, numbers will be rounded to the number of digits displayed.

Parameters
newValue BigDecimal: A positive rounding increment, or null or BigDecimal(0.0) to use the default rounding increment.
Throws
IllegalArgumentException if newValue is < 0.0

See also:

setRoundingIncrement

Added in API level 24
void setRoundingIncrement (BigDecimal newValue)

[icu] Sets the rounding increment. In the absence of a rounding increment, numbers will be rounded to the number of digits displayed.

Parameters
newValue BigDecimal: A positive rounding increment, or null or BigDecimal(0.0) to use the default rounding increment.
Throws
IllegalArgumentException if newValue is < 0.0

See also:

setRoundingIncrement

Added in API level 24
void setRoundingIncrement (double newValue)

[icu] Sets the rounding increment. In the absence of a rounding increment, numbers will be rounded to the number of digits displayed.

Parameters
newValue double: A positive rounding increment, or 0.0 to use the default rounding increment.
Throws
IllegalArgumentException if newValue is < 0.0

See also:

setRoundingMode

Added in API level 24
void setRoundingMode (int roundingMode)

Sets the rounding mode. This has no effect unless the rounding increment is greater than zero.

Parameters
roundingMode int: A rounding mode, between BigDecimal.ROUND_UP and BigDecimal.ROUND_UNNECESSARY.
Throws
IllegalArgumentException if roundingMode is unrecognized.

See also:

setScientificNotation

Added in API level 24
void setScientificNotation (boolean useScientific)

[icu] Sets whether or not scientific notation is used. When scientific notation is used, the effective maximum number of integer digits is <= 8. If the maximum number of integer digits is set to more than 8, the effective maximum will be 1. This allows this call to generate a 'default' scientific number format without additional changes.

Parameters
useScientific boolean: true if this object formats and parses scientific notation

See also:

setSecondaryGroupingSize

Added in API level 24
void setSecondaryGroupingSize (int newValue)

[icu] Sets the secondary grouping size. If set to a value less than 1, then secondary grouping is turned off, and the primary grouping size is used for all intervals, not just the least significant.

Parameters
newValue int

See also:

setSignificantDigitsUsed

Added in API level 24
void setSignificantDigitsUsed (boolean useSignificantDigits)

[icu] Sets whether significant digits are in use, or integer and fraction digit counts are in use.

Parameters
useSignificantDigits boolean: true to use significant digits, or false to use integer and fraction digit counts

toLocalizedPattern

Added in API level 24
String toLocalizedPattern ()

Synthesizes a localized pattern string that represents the current state of this Format object.

Returns
String

See also:

toPattern

Added in API level 24
String toPattern ()

Synthesizes a pattern string that represents the current state of this Format object.

Returns
String

See also: