Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Methods](https://developer.android.com/reference/android/icu/number/NumberFormatter#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/icu/number/NumberFormatter#inhmethods)

# NumberFormatter

*** ** * ** ***


`
public

final

class
NumberFormatter
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.icu.number.NumberFormatter |

<br />

*** ** * ** ***

All-in-one formatter for localized numbers, currencies, and units.

For a full list of options, see `https://developer.android.com/reference/android/icu/number/NumberFormatterSettings`.

```
// Most basic usage:
NumberFormatter.withLocale(...).format(123).toString();  // 1,234 in en-US

// Custom notation, unit, and rounding strategy:
NumberFormatter.with()
    .notation(Notation.compactShort())
    .unit(Currency.getInstance("EUR"))
    .precision(Precision.maxDigits(2))
    .locale(...)
    .format(1234)
    .toString();  // \u20ac1.2K in en-US

// Create a formatter in a private static final field:
private static final LocalizedNumberFormatter formatter = NumberFormatter.withLocale(...)
    .unit(NoUnit.PERCENT)
    .precision(Precision.fixedFraction(3));
formatter.format(5.9831).toString();  // 5.983% in en-US

// Create a "template" in a private static final field but without setting a locale until the call site:
private static final UnlocalizedNumberFormatter template = NumberFormatter.with()
    .sign(SignDisplay.ALWAYS)
    .unitWidth(UnitWidth.FULL_NAME);
template.locale(...).format(new Measure(1234, MeasureUnit.METER)).toString();  // +1,234 meters in en-US
```


This API offers more features than `https://developer.android.com/reference/android/icu/text/DecimalFormat` and is geared toward new
users of ICU.


NumberFormatter instances (i.e., LocalizedNumberFormatter and UnlocalizedNumberFormatter)
are immutable and thread safe. This means that invoking a configuration
method has no effect on the receiving instance; you must store and use the new number formatter
instance it returns instead.

```
UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter.with()
        .notation(Notation.scientific());
formatter.precision(Precision.maxFraction(2)); // does nothing!
formatter.locale(ULocale.ENGLISH).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0"
```


This API is based on the *fluent* design pattern popularized by libraries such as Google's
Guava. For extensive details on the design of this API, read [the
design doc](https://goo.gl/szi5VB).


Note: To format monetary/currency values, specify the currency in the \`.unit()\` function.

## Summary

| ### Public methods ||
|---|---|
| ` static https://developer.android.com/reference/android/icu/number/UnlocalizedNumberFormatter` | ` https://developer.android.com/reference/android/icu/number/NumberFormatter#forSkeleton(java.lang.String)(https://developer.android.com/reference/java/lang/String skeleton) ` Call this method at the beginning of a NumberFormatter fluent chain to create an instance based on a given number skeleton string. |
| ` static https://developer.android.com/reference/android/icu/number/UnlocalizedNumberFormatter` | ` https://developer.android.com/reference/android/icu/number/NumberFormatter#with()() ` Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not currently known at the call site. |
| ` static https://developer.android.com/reference/android/icu/number/LocalizedNumberFormatter` | ` https://developer.android.com/reference/android/icu/number/NumberFormatter#withLocale(java.util.Locale)(https://developer.android.com/reference/java/util/Locale locale) ` Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site. |
| ` static https://developer.android.com/reference/android/icu/number/LocalizedNumberFormatter` | ` https://developer.android.com/reference/android/icu/number/NumberFormatter#withLocale(android.icu.util.ULocale)(https://developer.android.com/reference/android/icu/util/ULocale locale) ` Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site. |

| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class<?>` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||

## Public methods

### forSkeleton

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public static UnlocalizedNumberFormatter forSkeleton (String skeleton)
```

Call this method at the beginning of a NumberFormatter fluent chain to create an instance based
on a given number skeleton string.

For more information on number skeleton strings, see:
https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html

<br />

| Parameters ||
|---|---|
| `skeleton` | `String`: The skeleton string off of which to base this NumberFormatter. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/number/UnlocalizedNumberFormatter` | An `https://developer.android.com/reference/android/icu/number/UnlocalizedNumberFormatter`, to be used for chaining. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/android/icu/number/SkeletonSyntaxException` | If the given string is not a valid number formatting skeleton. |

### with

Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public static UnlocalizedNumberFormatter with ()
```

Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not
currently known at the call site.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/number/UnlocalizedNumberFormatter` | An `https://developer.android.com/reference/android/icu/number/UnlocalizedNumberFormatter`, to be used for chaining. <br /> |

### withLocale

Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public static LocalizedNumberFormatter withLocale (Locale locale)
```

Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known
at the call site.

<br />

| Parameters ||
|---|---|
| `locale` | `Locale`: The locale from which to load formats and symbols for number formatting. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/number/LocalizedNumberFormatter` | A `https://developer.android.com/reference/android/icu/number/LocalizedNumberFormatter`, to be used for chaining. <br /> |

### withLocale

Added in [API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public static LocalizedNumberFormatter withLocale (ULocale locale)
```

Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known
at the call site.

<br />

| Parameters ||
|---|---|
| `locale` | `ULocale`: The locale from which to load formats and symbols for number formatting. <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/number/LocalizedNumberFormatter` | A `https://developer.android.com/reference/android/icu/number/LocalizedNumberFormatter`, to be used for chaining. <br /> |