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

# Optional

` public final class Optional `   
` extends https://developer.android.com/reference/java/lang/Object ` ` `

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | java.util.Optional\<T\> |

<br />

*** ** * ** ***

A container object which may or may not contain a non-`null` value. If a value is present, `isPresent()` returns `true`. If no value is present, the object is considered *empty* and `isPresent()` returns `false`.

Additional methods that depend on the presence or absence of a contained value are provided, such as `https://developer.android.com/reference/java/util/Optional#orElse(T)` (returns a default value if no value is present) and `https://developer.android.com/reference/java/util/Optional#ifPresent(java.util.function.Consumer<?%20super%20T>)` (performs an action if a value is present).

This is a [value-based](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/doc-files/ValueBased.html) class; programmers should treat instances that are [equal](https://developer.android.com/reference/java/util/Optional#equals(java.lang.Object)) as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail.

## Summary

| ### Public methods ||
|---|---|
| ` static <T> https://developer.android.com/reference/java/util/Optional<T>` | ` https://developer.android.com/reference/java/util/Optional#empty()() ` Returns an empty `Optional` instance. |
| ` boolean` | ` https://developer.android.com/reference/java/util/Optional#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this `Optional`. |
| ` https://developer.android.com/reference/java/util/Optional<T>` | ` https://developer.android.com/reference/java/util/Optional#filter(java.util.function.Predicate<?%20super%20T>)(https://developer.android.com/reference/java/util/function/Predicate<? super T> predicate) ` If a value is present, and the value matches the given predicate, returns an `Optional` describing the value, otherwise returns an empty `Optional`. |
| ` <U> https://developer.android.com/reference/java/util/Optional<U>` | ` https://developer.android.com/reference/java/util/Optional#flatMap(java.util.function.Function<?%20super%20T,?%20extends%20java.util.Optional<?%20extends%20U>>)(https://developer.android.com/reference/java/util/function/Function<? super T, ? extends https://developer.android.com/reference/java/util/Optional<? extends U>> mapper) ` If a value is present, returns the result of applying the given `Optional`-bearing mapping function to the value, otherwise returns an empty `Optional`. |
| ` T` | ` https://developer.android.com/reference/java/util/Optional#get()() ` If a value is present, returns the value, otherwise throws `NoSuchElementException`. |
| ` int` | ` https://developer.android.com/reference/java/util/Optional#hashCode()() ` Returns the hash code of the value, if present, otherwise `0` (zero) if no value is present. |
| ` void` | ` https://developer.android.com/reference/java/util/Optional#ifPresent(java.util.function.Consumer<?%20super%20T>)(https://developer.android.com/reference/java/util/function/Consumer<? super T> action) ` If a value is present, performs the given action with the value, otherwise does nothing. |
| ` void` | ` https://developer.android.com/reference/java/util/Optional#ifPresentOrElse(java.util.function.Consumer<?%20super%20T>,%20java.lang.Runnable)(https://developer.android.com/reference/java/util/function/Consumer<? super T> action, https://developer.android.com/reference/java/lang/Runnable emptyAction) ` If a value is present, performs the given action with the value, otherwise performs the given empty-based action. |
| ` boolean` | ` https://developer.android.com/reference/java/util/Optional#isEmpty()() ` If a value is not present, returns `true`, otherwise `false`. |
| ` boolean` | ` https://developer.android.com/reference/java/util/Optional#isPresent()() ` If a value is present, returns `true`, otherwise `false`. |
| ` <U> https://developer.android.com/reference/java/util/Optional<U>` | ` https://developer.android.com/reference/java/util/Optional#map(java.util.function.Function<?%20super%20T,?%20extends%20U>)(https://developer.android.com/reference/java/util/function/Function<? super T, ? extends U> mapper) ` If a value is present, returns an `Optional` describing (as if by `https://developer.android.com/reference/java/util/Optional#ofNullable(T)`) the result of applying the given mapping function to the value, otherwise returns an empty `Optional`. |
| ` static <T> https://developer.android.com/reference/java/util/Optional<T>` | ` https://developer.android.com/reference/java/util/Optional#of(T)(T value) ` Returns an `Optional` describing the given non-`null` value. |
| ` static <T> https://developer.android.com/reference/java/util/Optional<T>` | ` https://developer.android.com/reference/java/util/Optional#ofNullable(T)(T value) ` Returns an `Optional` describing the given value, if non-`null`, otherwise returns an empty `Optional`. |
| ` https://developer.android.com/reference/java/util/Optional<T>` | ` https://developer.android.com/reference/java/util/Optional#or(java.util.function.Supplier<?%20extends%20java.util.Optional<?%20extends%20T>>)(https://developer.android.com/reference/java/util/function/Supplier<? extends https://developer.android.com/reference/java/util/Optional<? extends T>> supplier) ` If a value is present, returns an `Optional` describing the value, otherwise returns an `Optional` produced by the supplying function. |
| ` T` | ` https://developer.android.com/reference/java/util/Optional#orElse(T)(T other) ` If a value is present, returns the value, otherwise returns `other`. |
| ` T` | ` https://developer.android.com/reference/java/util/Optional#orElseGet(java.util.function.Supplier<?%20extends%20T>)(https://developer.android.com/reference/java/util/function/Supplier<? extends T> supplier) ` If a value is present, returns the value, otherwise returns the result produced by the supplying function. |
| ` <X extends https://developer.android.com/reference/java/lang/Throwable> T` | ` https://developer.android.com/reference/java/util/Optional#orElseThrow(java.util.function.Supplier<?%20extends%20X>)(https://developer.android.com/reference/java/util/function/Supplier<? extends X> exceptionSupplier) ` If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function. |
| ` T` | ` https://developer.android.com/reference/java/util/Optional#orElseThrow()() ` If a value is present, returns the value, otherwise throws `NoSuchElementException`. |
| ` https://developer.android.com/reference/java/util/stream/Stream<T>` | ` https://developer.android.com/reference/java/util/Optional#stream()() ` If a value is present, returns a sequential `https://developer.android.com/reference/java/util/stream/Stream` containing only that value, otherwise returns an empty `Stream`. |
| ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/util/Optional#toString()() ` Returns a non-empty string representation of this `Optional` suitable for debugging. |

### 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

### empty

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

```
public static Optional<T> empty ()
```

Returns an empty `Optional` instance. No value is present for this `Optional`.

<br />

##### API Note:

- Though it may be tempting to do so, avoid testing if an object is empty by comparing with `==` or `!=` against instances returned by `Optional.empty()`. There is no guarantee that it is a singleton. Instead, use `https://developer.android.com/reference/java/util/Optional#isEmpty()` or `https://developer.android.com/reference/java/util/Optional#isPresent()`.

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<T>` | an empty `Optional` <br /> |

### equals

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

```
public boolean equals (Object obj)
```

Indicates whether some other object is "equal to" this `Optional`. The other object is considered equal if:

- it is also an `Optional` and;
- both instances have no value present or;
- the present values are "equal to" each other via `equals()`.

<br />

<br />

| Parameters ||
|---|---|
| `obj` | `Object`: an object to be tested for equality <br /> |

| Returns ||
|---|---|
| `boolean` | `true` if the other object is "equal to" this object otherwise `false` <br /> |

### filter

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

```
public Optional<T> filter (Predicate<? super T> predicate)
```

If a value is present, and the value matches the given predicate, returns an `Optional` describing the value, otherwise returns an empty `Optional`.

<br />

| Parameters ||
|---|---|
| `predicate` | `Predicate`: the predicate to apply to a value, if present <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<T>` | an `Optional` describing the value of this `Optional`, if a value is present and the value matches the given predicate, otherwise an empty `Optional` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the predicate is `null` |

### flatMap

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

```
public Optional<U> flatMap (Function<? super T, ? extends Optional<? extends U>> mapper)
```

If a value is present, returns the result of applying the given `Optional`-bearing mapping function to the value, otherwise returns an empty `Optional`.

This method is similar to `https://developer.android.com/reference/java/util/Optional#map(java.util.function.Function<?%20super%20T,?%20extends%20U>)`, but the mapping function is one whose result is already an `Optional`, and if invoked, `flatMap` does not wrap it within an additional `Optional`.

<br />

| Parameters ||
|---|---|
| `mapper` | `Function`: the mapping function to apply to a value, if present <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<U>` | the result of applying an `Optional`-bearing mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the mapping function is `null` or returns a `null` result |

### get

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

```
public T get ()
```

If a value is present, returns the value, otherwise throws `NoSuchElementException`.

<br />

##### API Note:

- The preferred alternative to this method is `https://developer.android.com/reference/java/util/Optional#orElseThrow()`.

| Returns ||
|---|---|
| `T` | the non-`null` value described by this `Optional` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/NoSuchElementException` | if no value is present |

### hashCode

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

```
public int hashCode ()
```

Returns the hash code of the value, if present, otherwise `0` (zero) if no value is present.

<br />

| Returns ||
|---|---|
| `int` | hash code value of the present value or `0` if no value is present <br /> |

### ifPresent

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

```
public void ifPresent (Consumer<? super T> action)
```

If a value is present, performs the given action with the value, otherwise does nothing.

<br />

| Parameters ||
|---|---|
| `action` | `Consumer`: the action to be performed, if a value is present <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if value is present and the given action is `null` |

### ifPresentOrElse

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

```
public void ifPresentOrElse (Consumer<? super T> action, 
                Runnable emptyAction)
```

If a value is present, performs the given action with the value, otherwise performs the given empty-based action.

<br />

| Parameters ||
|---|---|
| `action` | `Consumer`: the action to be performed, if a value is present <br /> |
| `emptyAction` | `Runnable`: the empty-based action to be performed, if no value is present <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if a value is present and the given action is `null`, or no value is present and the given empty-based action is `null`. |

### isEmpty

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

```
public boolean isEmpty ()
```

If a value is not present, returns `true`, otherwise `false`.

<br />

| Returns ||
|---|---|
| `boolean` | `true` if a value is not present, otherwise `false` <br /> |

### isPresent

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

```
public boolean isPresent ()
```

If a value is present, returns `true`, otherwise `false`.

<br />

| Returns ||
|---|---|
| `boolean` | `true` if a value is present, otherwise `false` <br /> |

### map

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

```
public Optional<U> map (Function<? super T, ? extends U> mapper)
```

If a value is present, returns an `Optional` describing (as if by `https://developer.android.com/reference/java/util/Optional#ofNullable(T)`) the result of applying the given mapping function to the value, otherwise returns an empty `Optional`.

If the mapping function returns a `null` result then this method returns an empty `Optional`.

<br />

##### API Note:

- This method supports post-processing on `Optional` values, without the need to explicitly check for a return status. For example, the following code traverses a stream of URIs, selects one that has not yet been processed, and creates a path from that URI, returning an `Optional<Path>`:

      Optional<Path> p =
              uris.stream().filter(uri -> !isProcessedYet(uri))
                            .findFirst()
                            .map(Paths::get);

  Here, `findFirst` returns an `Optional<URI>`, and then `map` returns an `Optional<Path>` for the desired URI if one exists.

| Parameters ||
|---|---|
| `mapper` | `Function`: the mapping function to apply to a value, if present <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<U>` | an `Optional` describing the result of applying a mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the mapping function is `null` |

### of

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

```
public static Optional<T> of (T value)
```

Returns an `Optional` describing the given non-`null` value.

<br />

| Parameters ||
|---|---|
| `value` | `T`: the value to describe, which must be non-`null` <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<T>` | an `Optional` with the value present <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if value is `null` |

### ofNullable

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

```
public static Optional<T> ofNullable (T value)
```

Returns an `Optional` describing the given value, if non-`null`, otherwise returns an empty `Optional`.

<br />

| Parameters ||
|---|---|
| `value` | `T`: the possibly-`null` value to describe <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<T>` | an `Optional` with a present value if the specified value is non-`null`, otherwise an empty `Optional` <br /> |

### or

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

```
public Optional<T> or (Supplier<? extends Optional<? extends T>> supplier)
```

If a value is present, returns an `Optional` describing the value, otherwise returns an `Optional` produced by the supplying function.

<br />

| Parameters ||
|---|---|
| `supplier` | `Supplier`: the supplying function that produces an `Optional` to be returned <br /> |

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/Optional<T>` | returns an `Optional` describing the value of this `Optional`, if a value is present, otherwise an `Optional` produced by the supplying function. <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if the supplying function is `null` or produces a `null` result |

### orElse

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

```
public T orElse (T other)
```

If a value is present, returns the value, otherwise returns `other`.

<br />

| Parameters ||
|---|---|
| `other` | `T`: the value to be returned, if no value is present. May be `null`. <br /> |

| Returns ||
|---|---|
| `T` | the value, if present, otherwise `other` <br /> |

### orElseGet

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

```
public T orElseGet (Supplier<? extends T> supplier)
```

If a value is present, returns the value, otherwise returns the result produced by the supplying function.

<br />

| Parameters ||
|---|---|
| `supplier` | `Supplier`: the supplying function that produces a value to be returned <br /> |

| Returns ||
|---|---|
| `T` | the value, if present, otherwise the result produced by the supplying function <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException` | if no value is present and the supplying function is `null` |

### orElseThrow

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

```
public T orElseThrow (Supplier<? extends X> exceptionSupplier)
```

If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.

<br />

##### API Note:

- A method reference to the exception constructor with an empty argument list can be used as the supplier. For example, `IllegalStateException::new`

| Parameters ||
|---|---|
| `exceptionSupplier` | `Supplier`: the supplying function that produces an exception to be thrown <br /> |

| Returns ||
|---|---|
| `T` | the value, if present <br /> |

| Throws ||
|---|---|
|   | if no value is present |
| `https://developer.android.com/reference/java/lang/NullPointerException` | if no value is present and the exception supplying function is `null` |
| `https://developer.android.com/reference/java/lang/Throwable` |   |

### orElseThrow

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

```
public T orElseThrow ()
```

If a value is present, returns the value, otherwise throws `NoSuchElementException`.

<br />

| Returns ||
|---|---|
| `T` | the non-`null` value described by this `Optional` <br /> |

| Throws ||
|---|---|
| `https://developer.android.com/reference/java/util/NoSuchElementException` | if no value is present |

### stream

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

```
public Stream<T> stream ()
```

If a value is present, returns a sequential `https://developer.android.com/reference/java/util/stream/Stream` containing only that value, otherwise returns an empty `Stream`.

<br />

##### API Note:

- This method can be used to transform a `Stream` of optional elements to a `Stream` of present value elements:

      Stream<Optional<T>> os = ..
          Stream<T> s = os.flatMap(Optional::stream)

| Returns ||
|---|---|
| `https://developer.android.com/reference/java/util/stream/Stream<T>` | the optional value as a `Stream` <br /> |

### toString

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

```
public String toString ()
```

Returns a non-empty string representation of this `Optional` suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.

<br />

##### Implementation Requirements:

- If a value is present the result must include its string representation in the result. Empty and present `Optional`s must be unambiguously differentiable.

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