NumberFormat

public abstract class NumberFormat
extends UFormat

java.lang.Object
   ↳ java.text.Format
     ↳ android.icu.text.UFormat
       ↳ android.icu.text.NumberFormat


[icu enhancement] ICU's replacement for NumberFormat. 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, NumberFormat, is only provided for java.text.NumberFormat compatibility.


NumberFormat is the abstract base class for all number formats. This class provides the interface for formatting and parsing numbers. NumberFormat also provides methods for determining which locales have number formats, and what their names are. NumberFormat helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points, thousands-separators, or even the particular decimal digits used, or whether the number format is even decimal.

To format a number for the current Locale, use one of the factory class methods:

  myString = NumberFormat.getInstance().format(myNumber);
 
If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.
 NumberFormat nf = NumberFormat.getInstance();
 for (int i = 0; i < a.length; ++i) {
     output.println(nf.format(myNumber[i]) + "; ");
 }
 
To format a number for a different Locale, specify it in the call to getInstance.
 NumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);
 
You can also use a NumberFormat to parse numbers:
 myNumber = nf.parse(myString);
 
Use getInstance or getNumberInstance to get the normal number format. Use getIntegerInstance to get an integer number format. Use getCurrencyInstance to get the currency number format. And use getPercentInstance to get a format for displaying percentages. Some factory methods are found within subclasses of NumberFormat. With this format, a fraction like 0.53 is displayed as 53%.

Starting from ICU 4.2, you can use getInstance() by passing in a 'style' as parameter to get the correct instance. For example, use getInstance(...NUMBERSTYLE) to get the normal number format, getInstance(...PERCENTSTYLE) to get a format for displaying percentage, getInstance(...SCIENTIFICSTYLE) to get a format for displaying scientific number, getInstance(...INTEGERSTYLE) to get an integer number format, getInstance(...CURRENCYSTYLE) to get the currency number format, in which the currency is represented by its symbol, for example, "$3.00". getInstance(...ISOCURRENCYSTYLE) to get the currency number format, in which the currency is represented by its ISO code, for example "USD3.00". getInstance(...PLURALCURRENCYSTYLE) to get the currency number format, in which the currency is represented by its full name in plural format, for example, "3.00 US dollars" or "1.00 US dollar".

You can also control the display of numbers with such methods as setMinimumFractionDigits. If you want even more control over the format or parsing, or want to give your users more control, you can try casting the NumberFormat you get from the factory methods to a DecimalFormat. This will work for the vast majority of locales; just remember to put it in a try block in case you encounter an unusual one.

NumberFormat is designed such that some controls work for formatting and others work for parsing. The following is the detailed description for each these control methods,

setParseIntegerOnly : only affects parsing, e.g. if true, "3456.78" -> 3456 (and leaves the parse position just after '6') if false, "3456.78" -> 3456.78 (and leaves the parse position just after '8') This is independent of formatting. If you want to not show a decimal point where there might be no digits after the decimal point, use setDecimalSeparatorAlwaysShown on DecimalFormat.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:

  • progressively parse through pieces of a string
  • align the decimal point and other areas
For example, you can align numbers in two ways:
  1. If you are using a monospaced font with spacing for alignment, you can pass the FieldPosition in your format call, with field = INTEGER_FIELD. On output, getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.
  2. If you are using proportional fonts, instead of padding with spaces, measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal, but possibly additional characters at the end, e.g., with parentheses in negative numbers: "(12)" for -12.

Synchronization

Number formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

DecimalFormat

DecimalFormat is the concrete implementation of NumberFormat, and the NumberFormat API is essentially an abstraction from DecimalFormat's API. Refer to DecimalFormat for more information about this API.

see DecimalFormat see java.text.ChoiceFormat

Summary

Nested classes

class NumberFormat.Field

The instances of this inner class are used as attribute keys and values in AttributedCharacterIterator that NumberFormat.formatToCharacterIterator() method returns. 

Constants

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).

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.

int FRACTION_FIELD

Field constant used to construct a FieldPosition object.

int INTEGERSTYLE

[icu] Constant to specify a integer number style format.

int INTEGER_FIELD

Field constant used to construct a FieldPosition object.

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.

Public constructors

NumberFormat()

Empty constructor.

Public methods

Object clone()

Overrides clone.

boolean equals(Object obj)

Overrides equals.

abstract StringBuffer format(BigInteger number, StringBuffer toAppendTo, FieldPosition pos)

[icu] Formats a BigInteger.

abstract StringBuffer format(BigDecimal number, StringBuffer toAppendTo, FieldPosition pos)

[icu] Formats an ICU BigDecimal.

StringBuffer format(Object number, StringBuffer toAppendTo, FieldPosition pos)

Formats a number and appends the resulting text to the given string buffer.

final String format(BigDecimal number)

Convenience method to format a BigDecimal.

abstract StringBuffer format(double number, StringBuffer toAppendTo, FieldPosition pos)

Specialization of format.

final String format(BigInteger number)

[icu] Convenience method to format a BigInteger.

abstract StringBuffer format(BigDecimal number, StringBuffer toAppendTo, FieldPosition pos)

[icu] Formats a BigDecimal.

final String format(BigDecimal number)

[icu] Convenience method to format an ICU BigDecimal.

final String format(double number)

Specialization of format.

final String format(long number)

Specialization of format.

StringBuffer format(CurrencyAmount currAmt, StringBuffer toAppendTo, FieldPosition pos)

[icu] Formats a CurrencyAmount.

final String format(CurrencyAmount currAmt)

[icu] Convenience method to format a CurrencyAmount.

abstract StringBuffer format(long number, StringBuffer toAppendTo, FieldPosition pos)

Specialization of format.

static Locale[] getAvailableLocales()

Returns the list of Locales for which NumberFormats are available.

DisplayContext getContext(DisplayContext.Type type)

[icu] Get the formatter's DisplayContext value for the specified DisplayContext.Type, such as CAPITALIZATION.

Currency getCurrency()

Returns the Currency object used to display currency amounts.

static NumberFormat getCurrencyInstance(Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getCurrencyInstance(ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getCurrencyInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getInstance(Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getInstance(ULocale desiredLocale, int choice)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getInstance(Locale inLocale, int style)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getInstance(ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getInstance(int style)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getIntegerInstance(ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getIntegerInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getIntegerInstance(Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

int getMaximumFractionDigits()

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

int getMaximumIntegerDigits()

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

int getMinimumFractionDigits()

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

int getMinimumIntegerDigits()

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

static NumberFormat getNumberInstance(ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getNumberInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getNumberInstance(Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getPercentInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getPercentInstance(Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getPercentInstance(ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

int getRoundingMode()

Returns the rounding mode used in this NumberFormat.

static NumberFormat getScientificInstance(ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static NumberFormat getScientificInstance(Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

static final NumberFormat getScientificInstance()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.

int hashCode()

Returns a hash code value for the object.

boolean isGroupingUsed()

Returns true if grouping is used in this format.

boolean isParseIntegerOnly()

Returns true if this format will parse numbers as integers only.

boolean isParseStrict()

[icu] Returns whether strict parsing is in effect.

Number parse(String text)

Parses text from the beginning of the given string to produce a number.

abstract Number 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.

CurrencyAmount parseCurrency(CharSequence text, ParsePosition pos)

Parses text from the given string as a CurrencyAmount.

final Object parseObject(String source, ParsePosition parsePosition)

Parses text from a string to produce a number.

void setContext(DisplayContext context)

[icu] Set a particular DisplayContext value in the formatter, such as CAPITALIZATION_FOR_STANDALONE.

void setCurrency(Currency theCurrency)

Sets the Currency object used to display currency amounts.

void setGroupingUsed(boolean newValue)

Sets whether or not grouping will be used in 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 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 setParseIntegerOnly(boolean value)

Sets whether to ignore the fraction part of a number when parsing (defaults to false).

void setParseStrict(boolean value)

[icu] Sets whether strict parsing is in effect.

void setRoundingMode(int roundingMode)

Set the rounding mode used in this NumberFormat.

Protected methods

static String getPattern(ULocale forLocale, int choice)

Returns the pattern for the provided locale and choice.

Inherited methods

Constants

ACCOUNTINGCURRENCYSTYLE

Added in API level 24
public static final 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.

Constant Value: 7 (0x00000007)

CASHCURRENCYSTYLE

Added in API level 24
public static final 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".

Constant Value: 8 (0x00000008)

CURRENCYSTYLE

Added in API level 24
public static final 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.

Constant Value: 1 (0x00000001)

FRACTION_FIELD

Added in API level 24
public static final 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.

See also:

Constant Value: 1 (0x00000001)

INTEGERSTYLE

Added in API level 24
public static final int INTEGERSTYLE

[icu] Constant to specify a integer number style format.

Constant Value: 4 (0x00000004)

INTEGER_FIELD

Added in API level 24
public static final 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.

See also:

Constant Value: 0 (0x00000000)

ISOCURRENCYSTYLE

Added in API level 24
public static final int ISOCURRENCYSTYLE

[icu] Constant to specify currency style of format which uses currency ISO code to represent currency, for example: "USD3.00".

Constant Value: 5 (0x00000005)

NUMBERSTYLE

Added in API level 24
public static final int NUMBERSTYLE

[icu] Constant to specify normal number style of format.

Constant Value: 0 (0x00000000)

PERCENTSTYLE

Added in API level 24
public static final int PERCENTSTYLE

[icu] Constant to specify a style of format to display percent.

Constant Value: 2 (0x00000002)

PLURALCURRENCYSTYLE

Added in API level 24
public static final 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".

Constant Value: 6 (0x00000006)

SCIENTIFICSTYLE

Added in API level 24
public static final int SCIENTIFICSTYLE

[icu] Constant to specify a style of format to display scientific number.

Constant Value: 3 (0x00000003)

STANDARDCURRENCYSTYLE

Added in API level 26
public static final 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.

Constant Value: 9 (0x00000009)

Public constructors

NumberFormat

Added in API level 24
public NumberFormat ()

Empty constructor. Public for API compatibility with historic versions of NumberFormat which had public constructor even though this is an abstract class.

Public methods

clone

Added in API level 24
public Object clone ()

Overrides clone.

Returns
Object a clone of this instance.

equals

Added in API level 24
public boolean equals (Object obj)

Overrides equals. Two NumberFormats are equal they are of the same class and the user-specified values for settings (groupingUsed, parseIntegerOnly, maximumIntegerDigits, etc.) are equal.

Parameters
obj Object: the object to compare against

Returns
boolean true if the object is equal to this.

format

Added in API level 24
public abstract StringBuffer format (BigInteger number, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

[icu] Formats a BigInteger. Specialization of format.

Parameters
number BigInteger

toAppendTo StringBuffer

pos FieldPosition

Returns
StringBuffer

format

Added in API level 24
public abstract StringBuffer format (BigDecimal number, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

[icu] Formats an ICU BigDecimal. Specialization of format.

Parameters
number BigDecimal

toAppendTo StringBuffer

pos FieldPosition

Returns
StringBuffer

format

Added in API level 24
public StringBuffer format (Object number, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

Formats a number and appends the resulting text to the given string buffer. [icu] Note: recognizes BigInteger and BigDecimal objects.

Parameters
number Object: The object to format

toAppendTo StringBuffer: where the text is to be appended

pos FieldPosition: A FieldPosition identifying a field in the formatted text

Returns
StringBuffer the string buffer passed in as toAppendTo, with formatted text appended

format

Added in API level 24
public final String format (BigDecimal number)

Convenience method to format a BigDecimal.

Parameters
number BigDecimal

Returns
String

format

Added in API level 24
public abstract StringBuffer format (double number, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

Specialization of format.

Parameters
number double

toAppendTo StringBuffer

pos FieldPosition

Returns
StringBuffer

format

Added in API level 24
public final String format (BigInteger number)

[icu] Convenience method to format a BigInteger.

Parameters
number BigInteger

Returns
String

format

Added in API level 24
public abstract StringBuffer format (BigDecimal number, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

[icu] Formats a BigDecimal. Specialization of format.

Parameters
number BigDecimal

toAppendTo StringBuffer

pos FieldPosition

Returns
StringBuffer

format

Added in API level 24
public final String format (BigDecimal number)

[icu] Convenience method to format an ICU BigDecimal.

Parameters
number BigDecimal

Returns
String

format

Added in API level 24
public final String format (double number)

Specialization of format.

Parameters
number double

Returns
String

format

Added in API level 24
public final String format (long number)

Specialization of format.

Parameters
number long

Returns
String

format

Added in API level 24
public StringBuffer format (CurrencyAmount currAmt, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

[icu] Formats a CurrencyAmount. Specialization of format.

Parameters
currAmt CurrencyAmount

toAppendTo StringBuffer

pos FieldPosition

Returns
StringBuffer

format

Added in API level 24
public final String format (CurrencyAmount currAmt)

[icu] Convenience method to format a CurrencyAmount.

Parameters
currAmt CurrencyAmount

Returns
String

format

Added in API level 24
public abstract StringBuffer format (long number, 
                StringBuffer toAppendTo, 
                FieldPosition pos)

Specialization of format.

Parameters
number long

toAppendTo StringBuffer

pos FieldPosition

Returns
StringBuffer

getAvailableLocales

Added in API level 24
public static Locale[] getAvailableLocales ()

Returns the list of Locales for which NumberFormats are available.

Returns
Locale[] the available locales

getContext

Added in API level 24
public DisplayContext getContext (DisplayContext.Type type)

[icu] Get the formatter's DisplayContext value for the specified DisplayContext.Type, such as CAPITALIZATION.

Parameters
type DisplayContext.Type: the DisplayContext.Type whose value to return

Returns
DisplayContext the current DisplayContext setting for the specified type

getCurrency

Added in API level 24
public Currency getCurrency ()

Returns the Currency object used to display currency amounts. This may be null.

Returns
Currency

getCurrencyInstance

Added in API level 24
public static NumberFormat getCurrencyInstance (Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


Returns a currency format for the specified locale.

Parameters
inLocale Locale

Returns
NumberFormat a number format for currency

getCurrencyInstance

Added in API level 24
public static NumberFormat getCurrencyInstance (ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a currency format for the specified locale.

Parameters
inLocale ULocale

Returns
NumberFormat a number format for currency

getCurrencyInstance

Added in API level 24
public static final NumberFormat getCurrencyInstance ()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


Returns a currency format for the current default FORMAT locale.

Returns
NumberFormat a number format for currency

getInstance

Added in API level 24
public static final 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.

Returns
NumberFormat

getInstance

Added in API level 24
public static NumberFormat getInstance (Locale inLocale)

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.

Parameters
inLocale Locale

Returns
NumberFormat

getInstance

Added in API level 24
public static NumberFormat getInstance (ULocale desiredLocale, 
                int choice)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


Returns a specific style number format for a specific locale.

Parameters
desiredLocale ULocale: the specific locale.

choice int: number format style

Returns
NumberFormat

Throws
IllegalArgumentException if choice is not one of NUMBERSTYLE, CURRENCYSTYLE, PERCENTSTYLE, SCIENTIFICSTYLE, INTEGERSTYLE, ISOCURRENCYSTYLE, PLURALCURRENCYSTYLE, ACCOUNTINGCURRENCYSTYLE. CASHCURRENCYSTYLE, STANDARDCURRENCYSTYLE.

getInstance

Added in API level 24
public static NumberFormat getInstance (Locale inLocale, 
                int style)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a specific style number format for a specific locale.

Parameters
inLocale Locale: the specific locale.

style int: number format style

Returns
NumberFormat

getInstance

Added in API level 24
public static NumberFormat getInstance (ULocale inLocale)

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.

Parameters
inLocale ULocale

Returns
NumberFormat

getInstance

Added in API level 24
public static final NumberFormat getInstance (int style)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a specific style number format for default FORMAT locale.

Parameters
style int: number format style

Returns
NumberFormat

getIntegerInstance

Added in API level 24
public static NumberFormat getIntegerInstance (ULocale inLocale)

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).

Parameters
inLocale ULocale: the locale for which a number format is needed

Returns
NumberFormat a number format for integer values

getIntegerInstance

Added in API level 24
public static final 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).

Returns
NumberFormat a number format for integer values

getIntegerInstance

Added in API level 24
public static NumberFormat getIntegerInstance (Locale inLocale)

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).

Parameters
inLocale Locale: the locale for which a number format is needed

Returns
NumberFormat a number format for integer values

getMaximumFractionDigits

Added in API level 24
public int getMaximumFractionDigits ()

Returns the maximum number of digits allowed in the fraction portion of a number. The default value is 3, which subclasses can override. When formatting, the exact behavior when this value is exceeded is subclass-specific. When parsing, this has no effect.

Returns
int the maximum number of fraction digits

getMaximumIntegerDigits

Added in API level 24
public int getMaximumIntegerDigits ()

Returns the maximum number of digits allowed in the integer portion of a number. The default value is 40, which subclasses can override. When formatting, if the number of digits exceeds this value, the highest- significance digits are truncated until the limit is reached, in accordance with UTS#35. This setting has no effect on parsing.

Returns
int the maximum number of integer digits

getMinimumFractionDigits

Added in API level 24
public int getMinimumFractionDigits ()

Returns the minimum number of digits allowed in the fraction portion of a number. The default value is 0, which subclasses can override. When formatting, if this value is not reached, numbers are padded on the right with the locale-specific '0' character to ensure at least this number of fraction digits. When parsing, this has no effect.

Returns
int the minimum number of fraction digits

getMinimumIntegerDigits

Added in API level 24
public int getMinimumIntegerDigits ()

Returns the minimum number of digits allowed in the integer portion of a number. The default value is 1, which subclasses can override. When formatting, if this value is not reached, numbers are padded on the left with the locale-specific '0' character to ensure at least this number of integer digits. When parsing, this has no effect.

Returns
int the minimum number of integer digits

getNumberInstance

Added in API level 24
public static NumberFormat getNumberInstance (ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a general-purpose number format for the specified locale.

Parameters
inLocale ULocale

Returns
NumberFormat

getNumberInstance

Added in API level 24
public static final 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.

Returns
NumberFormat

getNumberInstance

Added in API level 24
public static NumberFormat getNumberInstance (Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


Returns a general-purpose number format for the specified locale.

Parameters
inLocale Locale

Returns
NumberFormat

getPercentInstance

Added in API level 24
public static final NumberFormat getPercentInstance ()

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


Returns a percentage format for the current default FORMAT locale.

Returns
NumberFormat a number format for percents

getPercentInstance

Added in API level 24
public static NumberFormat getPercentInstance (Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


Returns a percentage format for the specified locale.

Parameters
inLocale Locale

Returns
NumberFormat a number format for percents

getPercentInstance

Added in API level 24
public static NumberFormat getPercentInstance (ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a percentage format for the specified locale.

Parameters
inLocale ULocale

Returns
NumberFormat a number format for percents

getRoundingMode

Added in API level 24
public int getRoundingMode ()

Returns the rounding mode used in this NumberFormat. The default implementation of tis method in NumberFormat always throws UnsupportedOperationException.

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

getScientificInstance

Added in API level 24
public static NumberFormat getScientificInstance (ULocale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a scientific format for the specified locale.

Parameters
inLocale ULocale

Returns
NumberFormat a scientific number format

getScientificInstance

Added in API level 24
public static NumberFormat getScientificInstance (Locale inLocale)

NOTE: New users are strongly encouraged to use NumberFormatter instead of NumberFormat.


[icu] Returns a scientific format for the specified locale.

Parameters
inLocale Locale

Returns
NumberFormat a scientific number format

getScientificInstance

Added in API level 24
public static final 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.

Returns
NumberFormat a scientific number format

hashCode

Added in API level 24
public int hashCode ()

Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.

Returns
int a hash code value for this object.

isGroupingUsed

Added in API level 24
public boolean isGroupingUsed ()

Returns true if grouping is used in this format. For example, in the en_US locale, with grouping on, the number 1234567 will be formatted as "1,234,567". The grouping separator as well as the size of each group is locale-dependent and is determined by subclasses of NumberFormat. Grouping affects both parsing and formatting.

Returns
boolean true if grouping is used

isParseIntegerOnly

Added in API level 24
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.

Returns
boolean true if this will parse integers only

isParseStrict

Added in API level 24
public boolean isParseStrict ()

[icu] Returns whether strict parsing is in effect.

Returns
boolean true if strict parsing is in effect

parse

Added in API level 24
public Number parse (String text)

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.

Parameters
text String: A String whose beginning should be parsed.

Returns
Number A Number parsed from the string.

Throws
ParseException if the beginning of the specified string cannot be parsed.

See also:

parse

Added in API level 24
public abstract Number 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. 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.

Parameters
text String

parsePosition ParsePosition

Returns
Number

parseCurrency

Added in API level 24
public 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

parseObject

Added in API level 24
public final Object parseObject (String source, 
                ParsePosition parsePosition)

Parses text from a string to produce a number.

Parameters
source String: the String to parse

parsePosition ParsePosition: the position at which to start the parse

Returns
Object the parsed number, or null

setContext

Added in API level 24
public void setContext (DisplayContext context)

[icu] Set a particular DisplayContext value in the formatter, such as CAPITALIZATION_FOR_STANDALONE.

Parameters
context DisplayContext: The DisplayContext value to set.

setCurrency

Added in API level 24
public void setCurrency (Currency theCurrency)

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

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

setGroupingUsed

Added in API level 24
public void setGroupingUsed (boolean newValue)

Sets whether or not grouping will be used in this format. Grouping affects both parsing and formatting.

Parameters
newValue boolean: true to use grouping.

See also:

setMaximumFractionDigits

Added in API level 24
public void setMaximumFractionDigits (int newValue)

Sets the maximum number of digits allowed in the fraction portion of a number. This must be >= minimumFractionDigits. If the new value for maximumFractionDigits is less than the current value of minimumFractionDigits, then minimumFractionDigits will also be set to the new value.

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.

setMaximumIntegerDigits

Added in API level 24
public void setMaximumIntegerDigits (int newValue)

Sets the maximum number of digits allowed in the integer portion of a number. This must be >= minimumIntegerDigits. If the new value for maximumIntegerDigits is less than the current value of minimumIntegerDigits, then minimumIntegerDigits will also be set to the new value.

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.

setMinimumFractionDigits

Added in API level 24
public void setMinimumFractionDigits (int newValue)

Sets the minimum number of digits allowed in the fraction portion of a number. This must be <= maximumFractionDigits. If the new value for minimumFractionDigits exceeds the current value of maximumFractionDigits, then maximumFractionDigits will also be set to the new value.

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.

setMinimumIntegerDigits

Added in API level 24
public void setMinimumIntegerDigits (int newValue)

Sets the minimum number of digits allowed in the integer portion of a number. This must be <= maximumIntegerDigits. If the new value for minimumIntegerDigits is more than the current value of maximumIntegerDigits, then maximumIntegerDigits will also be set to the new value.

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.

setParseIntegerOnly

Added in API level 24
public void setParseIntegerOnly (boolean value)

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.

Parameters
value boolean: true if this should parse integers only

setParseStrict

Added in API level 24
public void setParseStrict (boolean value)

[icu] 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)
When strict parsing is off, all grouping separators are ignored. This is the default behavior.

Parameters
value boolean: True to enable strict parsing. Default is false.

See also:

setRoundingMode

Added in API level 24
public void setRoundingMode (int roundingMode)

Set the rounding mode used in this NumberFormat. The default implementation of tis method in NumberFormat always throws UnsupportedOperationException.

Parameters
roundingMode int: A rounding mode, between BigDecimal.ROUND_UP and BigDecimal.ROUND_UNNECESSARY.

See also:

Protected methods

getPattern

Added in API level 24
protected static String getPattern (ULocale forLocale, 
                int choice)

Returns the pattern for the provided locale and choice.

Parameters
forLocale ULocale: the locale of the data.

choice int: the pattern format.

Returns
String the pattern