NumberFormat

Kotlin |Java

abstract class NumberFormat : UFormat

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

Known Direct Subclasses

DecimalFormat

[icu enhancement] ICU's replacement for java.text.DecimalFormat.

Known Indirect Subclasses

CompactDecimalFormat

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

[icu enhancement] ICU's replacement for java.text.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:

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.
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
open	`Field` The instances of this inner class are used as attribute keys and values in AttributedCharacterIterator that NumberFormat.

Constants
static 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.
static 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.
static Int	`CURRENCYSTYLE` [icu] Constant to specify general currency style of format.
static Int	`FRACTION_FIELD` Field constant used to construct a FieldPosition object.
static Int	`INTEGERSTYLE` [icu] Constant to specify a integer number style format.
static Int	`INTEGER_FIELD` Field constant used to construct a FieldPosition object.
static Int	`ISOCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency ISO code to represent currency, for example: "USD3.
static Int	`NUMBERSTYLE` [icu] Constant to specify normal number style of format.
static Int	`PERCENTSTYLE` [icu] Constant to specify a style of format to display percent.
static Int	`PLURALCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency long name with plural format to represent currency, for example, "3.
static Int	`SCIENTIFICSTYLE` [icu] Constant to specify a style of format to display scientific number.
static Int	`STANDARDCURRENCYSTYLE` [icu] Constant to specify currency style of format which uses currency symbol to represent currency, for example "$3.

Public constructors
`NumberFormat()` Empty constructor.

Public methods
open Any	`clone()` Overrides clone.
open Boolean	`equals(other: Any?)` Overrides equals.
String!	`format(number: BigDecimal!)` [icu] Convenience method to format an ICU BigDecimal.
abstract StringBuffer!	`format(number: BigDecimal!, toAppendTo: StringBuffer!, pos: FieldPosition!)` [icu] Formats an ICU BigDecimal.
String!	`format(currAmt: CurrencyAmount!)` [icu] Convenience method to format a CurrencyAmount.
open StringBuffer!	`format(currAmt: CurrencyAmount!, toAppendTo: StringBuffer!, pos: FieldPosition!)` [icu] Formats a CurrencyAmount.
String!	`format(number: Double)` Specialization of format.
abstract StringBuffer!	`format(number: Double, toAppendTo: StringBuffer!, pos: FieldPosition!)` Specialization of format.
open StringBuffer!	`format(number: Any!, toAppendTo: StringBuffer!, pos: FieldPosition!)` Formats a number and appends the resulting text to the given string buffer.
String!	`format(number: BigDecimal!)` Convenience method to format a BigDecimal.
abstract StringBuffer!	`format(number: BigDecimal!, toAppendTo: StringBuffer!, pos: FieldPosition!)` [icu] Formats a BigDecimal.
String!	`format(number: BigInteger!)` [icu] Convenience method to format a BigInteger.
abstract StringBuffer!	`format(number: BigInteger!, toAppendTo: StringBuffer!, pos: FieldPosition!)` [icu] Formats a BigInteger.
String!	`format(number: Long)` Specialization of format.
abstract StringBuffer!	`format(number: Long, toAppendTo: StringBuffer!, pos: FieldPosition!)` Specialization of format.
open static Array<Locale!>!	`getAvailableLocales()` Returns the list of Locales for which NumberFormats are available.
open DisplayContext!	`getContext(type: DisplayContext.Type!)` [icu] Get the formatter's DisplayContext value for the specified DisplayContext.
open Currency!	`getCurrency()` Returns the Currency object used to display currency amounts.
static NumberFormat!	`getCurrencyInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getCurrencyInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getCurrencyInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
static NumberFormat!	`getInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getInstance(desiredLocale: ULocale!, choice: Int)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
static NumberFormat!	`getInstance(style: Int)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getInstance(inLocale: Locale!, style: Int)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
static NumberFormat!	`getIntegerInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getIntegerInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getIntegerInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open Int	`getMaximumFractionDigits()` Returns the maximum number of digits allowed in the fraction portion of a number.
open Int	`getMaximumIntegerDigits()` Returns the maximum number of digits allowed in the integer portion of a number.
open Int	`getMinimumFractionDigits()` Returns the minimum number of digits allowed in the fraction portion of a number.
open Int	`getMinimumIntegerDigits()` Returns the minimum number of digits allowed in the integer portion of a number.
static NumberFormat!	`getNumberInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getNumberInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getNumberInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
static NumberFormat!	`getPercentInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getPercentInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getPercentInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open Int	`getRoundingMode()` Returns the rounding mode used in this NumberFormat.
static NumberFormat!	`getScientificInstance()` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getScientificInstance(inLocale: ULocale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open static NumberFormat!	`getScientificInstance(inLocale: Locale!)` NOTE: New users are strongly encouraged to use `NumberFormatter` instead of NumberFormat.
open Int	`hashCode()` Returns a hash code value for the object.
open Boolean	`isGroupingUsed()` Returns true if grouping is used in this format.
open Boolean	`isParseIntegerOnly()` Returns true if this format will parse numbers as integers only.
open Boolean	`isParseStrict()` [icu] Returns whether strict parsing is in effect.
open Number!	`parse(text: String!)` Parses text from the beginning of the given string to produce a number.
abstract Number!	`parse(text: String!, parsePosition: ParsePosition!)` Returns a Long if possible (e.g., within the range [Long.MIN_VALUE, Long.MAX_VALUE] and with no decimals); otherwise, returns another type, such as a BigDecimal, BigInteger, or Double.
open CurrencyAmount!	`parseCurrency(text: CharSequence!, pos: ParsePosition!)` Parses text from the given string as a CurrencyAmount.
Any!	`parseObject(source: String!, parsePosition: ParsePosition!)` Parses text from a string to produce a number.
open Unit	`setContext(context: DisplayContext!)` [icu] Set a particular DisplayContext value in the formatter, such as CAPITALIZATION_FOR_STANDALONE.
open Unit	`setCurrency(theCurrency: Currency!)` Sets the Currency object used to display currency amounts.
open Unit	`setGroupingUsed(newValue: Boolean)` Sets whether or not grouping will be used in this format.
open Unit	`setMaximumFractionDigits(newValue: Int)` Sets the maximum number of digits allowed in the fraction portion of a number.
open Unit	`setMaximumIntegerDigits(newValue: Int)` Sets the maximum number of digits allowed in the integer portion of a number.
open Unit	`setMinimumFractionDigits(newValue: Int)` Sets the minimum number of digits allowed in the fraction portion of a number.
open Unit	`setMinimumIntegerDigits(newValue: Int)` Sets the minimum number of digits allowed in the integer portion of a number.
open Unit	`setParseIntegerOnly(value: Boolean)` Sets whether to ignore the fraction part of a number when parsing (defaults to false).
open Unit	`setParseStrict(value: Boolean)` [icu] Sets whether strict parsing is in effect.
open Unit	`setRoundingMode(roundingMode: Int)` Set the rounding mode used in this NumberFormat.

Protected methods
open static String!	`getPattern(forLocale: ULocale!, choice: Int)` Returns the pattern for the provided locale and choice.

Parameters
`obj`	The object to format
`toAppendTo`	StringBuffer!: where the text is to be appended
`pos`	FieldPosition!: A `FieldPosition` identifying a field in the formatted text

Exceptions
`java.lang.NullPointerException`	if `toAppendTo` or `pos` is null
`java.lang.IllegalArgumentException`	if the Format cannot format the given object

Parameters
`desiredLocale`	ULocale!: the specific locale.
`choice`	Int: number format style

Parameters
`inLocale`	Locale!: the specific locale.
`style`	Int: number format style

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.

Parameters
`source`	String!: the String to parse
`pos`	A `ParsePosition` object with index and error index information as described above.
`parsePosition`	ParsePosition!: the position at which to start the parse

Parameters
`forLocale`	ULocale!: the locale of the data.
`choice`	Int: the pattern format.

NumberFormat

Synchronization

DecimalFormat

Summary

Constants

ACCOUNTINGCURRENCYSTYLE

CASHCURRENCYSTYLE

CURRENCYSTYLE

FRACTION_FIELD

INTEGERSTYLE

INTEGER_FIELD

ISOCURRENCYSTYLE

NUMBERSTYLE

PERCENTSTYLE

PLURALCURRENCYSTYLE

SCIENTIFICSTYLE

STANDARDCURRENCYSTYLE

Public constructors

NumberFormat

Public methods

clone

equals

format

format

format

format

format

format

format

format

format

format

format

format

format

getAvailableLocales

getContext

getCurrency

getCurrencyInstance

getCurrencyInstance

getCurrencyInstance

getInstance

getInstance

getInstance

getInstance

getInstance

getInstance

getIntegerInstance

getIntegerInstance

getIntegerInstance

getMaximumFractionDigits

getMaximumIntegerDigits

getMinimumFractionDigits

getMinimumIntegerDigits

getNumberInstance

getNumberInstance

getNumberInstance

getPercentInstance

getPercentInstance

getPercentInstance

getRoundingMode

getScientificInstance

getScientificInstance

getScientificInstance

hashCode

isGroupingUsed

isParseIntegerOnly

isParseStrict

parse

parse

parseCurrency

parseObject

setContext

setCurrency

setGroupingUsed

setMaximumFractionDigits

setMaximumIntegerDigits

setMinimumFractionDigits

setMinimumIntegerDigits

setParseIntegerOnly