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/FormattedNumber#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/icu/number/FormattedNumber#inhmethods)

# FormattedNumber

*** ** * ** ***


`
public


class
FormattedNumber
`


`

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


`

`


implements

https://developer.android.com/reference/android/icu/text/FormattedValue


`

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

<br />

*** ** * ** ***

The result of a number formatting operation. This class allows the result to be exported in several
data types, including a String, an AttributedCharacterIterator, and a BigDecimal.

Instances of this class are immutable and thread-safe.
**See also:**

- `https://developer.android.com/reference/android/icu/number/NumberFormatter`

## Summary

| ### Public methods ||
|---|---|
| ` <A extends https://developer.android.com/reference/java/lang/Appendable> A` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#appendTo(A)(A appendable) ` Appends the formatted string to an Appendable. |
| ` char` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#charAt(int)(int index) ` Returns the `char` value at the specified index. |
| ` https://developer.android.com/reference/android/icu/text/DisplayOptions.NounClass` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#getNounClass()() ` Gets the noun class of the formatted output. |
| ` https://developer.android.com/reference/android/icu/util/MeasureUnit` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#getOutputUnit()() ` Gets the resolved output unit. |
| ` int` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#length()() ` Returns the length of this character sequence. |
| ` boolean` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#nextPosition(android.icu.text.ConstrainedFieldPosition)(https://developer.android.com/reference/android/icu/text/ConstrainedFieldPosition cfpos) ` Iterates over field positions in the FormattedValue. |
| ` https://developer.android.com/reference/java/lang/CharSequence` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#subSequence(int,%20int)(int start, int end) ` Returns a `CharSequence` that is a subsequence of this sequence. |
| ` https://developer.android.com/reference/java/math/BigDecimal` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#toBigDecimal()() ` Export the formatted number as a BigDecimal. |
| ` https://developer.android.com/reference/java/text/AttributedCharacterIterator` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#toCharacterIterator()() ` Exports the formatted number as an AttributedCharacterIterator. |
| ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/android/icu/number/FormattedNumber#toString()() ` Returns a string representation of the object. |

| ### 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*. | ||
| From interface ` https://developer.android.com/reference/android/icu/text/FormattedValue ` |---|---| | ` abstract <A extends https://developer.android.com/reference/java/lang/Appendable> A` | ` https://developer.android.com/reference/android/icu/text/FormattedValue#appendTo(A)(A appendable) ` Appends the formatted string to an Appendable. | | ` abstract boolean` | ` https://developer.android.com/reference/android/icu/text/FormattedValue#nextPosition(android.icu.text.ConstrainedFieldPosition)(https://developer.android.com/reference/android/icu/text/ConstrainedFieldPosition cfpos) ` Iterates over field positions in the FormattedValue. | | ` abstract https://developer.android.com/reference/java/text/AttributedCharacterIterator` | ` https://developer.android.com/reference/android/icu/text/FormattedValue#toCharacterIterator()() ` Exports the formatted number as an AttributedCharacterIterator. | | ` abstract https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/android/icu/text/FormattedValue#toString()() ` Returns the formatted string as a Java String. | ||
| From interface ` https://developer.android.com/reference/java/lang/CharSequence ` |---|---| | ` abstract char` | ` https://developer.android.com/reference/java/lang/CharSequence#charAt(int)(int index) ` Returns the `char` value at the specified index. | | ` default https://developer.android.com/reference/java/util/stream/IntStream` | ` https://developer.android.com/reference/java/lang/CharSequence#chars()() ` Returns a stream of `int` zero-extending the `char` values from this sequence. | | ` default https://developer.android.com/reference/java/util/stream/IntStream` | ` https://developer.android.com/reference/java/lang/CharSequence#codePoints()() ` Returns a stream of code point values from this sequence. | | ` static int` | ` https://developer.android.com/reference/java/lang/CharSequence#compare(java.lang.CharSequence,%20java.lang.CharSequence)(https://developer.android.com/reference/java/lang/CharSequence cs1, https://developer.android.com/reference/java/lang/CharSequence cs2) ` Compares two `CharSequence` instances lexicographically. | | ` default void` | ` https://developer.android.com/reference/java/lang/CharSequence#getChars(int,%20int,%20char[],%20int)(int srcBegin, int srcEnd, char[] dst, int dstBegin) ` Copies characters from this sequence into the given destination array. | | ` default boolean` | ` https://developer.android.com/reference/java/lang/CharSequence#isEmpty()() ` Returns `true` if this character sequence is empty. | | ` abstract int` | ` https://developer.android.com/reference/java/lang/CharSequence#length()() ` Returns the length of this character sequence. | | ` abstract https://developer.android.com/reference/java/lang/CharSequence` | ` https://developer.android.com/reference/java/lang/CharSequence#subSequence(int,%20int)(int start, int end) ` Returns a `CharSequence` that is a subsequence of this sequence. | | ` abstract https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/CharSequence#toString()() ` Returns a string containing the characters in this sequence in the same order as this sequence. | ||

## Public methods

### appendTo

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

```
public A appendTo (A appendable)
```

Appends the formatted string to an Appendable.


If an IOException occurs when appending to the Appendable, an unchecked
`https://developer.android.com/reference/android/icu/util/ICUUncheckedIOException` is thrown instead.

<br />

| Parameters ||
|---|---|
| `appendable` | `A`: The Appendable to which to append the string output. <br /> |

| Returns ||
|---|---|
| `A` | The same Appendable, for chaining. <br /> |

### charAt

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

```
public char charAt (int index)
```

Returns the `char` value at the specified index. An index ranges from zero
to `length() - 1`. The first `char` value of the sequence is at
index zero, the next at index one, and so on, as for array
indexing.

If the `char` value specified by the index is a
[surrogate](https://reference/java/lang/Character.html#unicode), the surrogate
value is returned.

<br />

| Parameters ||
|---|---|
| `index` | `int`: the index of the `char` value to be returned <br /> |

| Returns ||
|---|---|
| `char` | the specified `char` value <br /> |

### getNounClass

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

```
public DisplayOptions.NounClass getNounClass ()
```

Gets the noun class of the formatted output. Returns `UNDEFINED` when the noun class is not
supported yet.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/text/DisplayOptions.NounClass` | NounClass <br /> |

### getOutputUnit

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

```
public MeasureUnit getOutputUnit ()
```

Gets the resolved output unit.


The output unit is dependent upon the localized preferences for the usage
specified via NumberFormatterSettings.usage(), and may be a unit with
MeasureUnit.Complexity.MIXED unit complexity (MeasureUnit.getComplexity()), such
as "foot-and-inch" or "hour-and-minute-and-second".

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/icu/util/MeasureUnit` | `MeasureUnit`. <br /> |

### length

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

```
public int length ()
```

Returns the length of this character sequence. The length is the number
of 16-bit `char`s in the sequence.

<br />

| Returns ||
|---|---|
| `int` | the number of `char`s in this sequence <br /> |

### nextPosition

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

```
public boolean nextPosition (ConstrainedFieldPosition cfpos)
```

Iterates over field positions in the FormattedValue. This lets you determine the position
of specific types of substrings, like a month or a decimal separator.

To loop over all field positions:

```
    ConstrainedFieldPosition cfpos = new ConstrainedFieldPosition();
    while (fmtval.nextPosition(cfpos)) {
        // handle the field position; get information from cfpos
    }
```

<br />

<br />

| Parameters ||
|---|---|
| `cfpos` | `ConstrainedFieldPosition`: The object used for iteration state. This can provide constraints to iterate over only one specific field; see `https://developer.android.com/reference/android/icu/text/ConstrainedFieldPosition#constrainField(java.text.Format.Field)`. <br /> |

| Returns ||
|---|---|
| `boolean` | true if a new occurrence of the field was found; false otherwise. <br /> |

### subSequence

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

```
public CharSequence subSequence (int start, 
                int end)
```

Returns a `CharSequence` that is a subsequence of this sequence.
The subsequence starts with the `char` value at the specified index and
ends with the `char` value at index `end - 1`. The length
(in `char`s) of the
returned sequence is `end - start`, so if `start == end`
then an empty sequence is returned.

<br />

| Parameters ||
|---|---|
| `start` | `int`: the start index, inclusive <br /> |
| `end` | `int`: the end index, exclusive <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/CharSequence` | the specified subsequence <br /> |

### toBigDecimal

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

```
public BigDecimal toBigDecimal ()
```

Export the formatted number as a BigDecimal. This endpoint is useful for obtaining the exact
number being printed after scaling and rounding have been applied by the number formatting
pipeline.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/math/BigDecimal` | A BigDecimal representation of the formatted number. <br /> |

**See also:**

- `https://developer.android.com/reference/android/icu/number/NumberFormatter`

### toCharacterIterator

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

```
public AttributedCharacterIterator toCharacterIterator ()
```

Exports the formatted number as an AttributedCharacterIterator.


Consider using `https://developer.android.com/reference/android/icu/text/FormattedValue#nextPosition(android.icu.text.ConstrainedFieldPosition)` if you are trying to get field information.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/text/AttributedCharacterIterator` | An AttributedCharacterIterator containing full field information. <br /> |

### toString

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

```
public String toString ()
```

Returns a string representation of the object.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/lang/String` | a string representation of the object. <br /> |