# Optional

public final class **Optional** extends [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)  
A container object which may or may not contain a non-null value.
If a value is present, `isPresent()` will return `true` and
`get()` will return the value.

Additional methods that depend on the presence or absence of a contained
value are provided, such as `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#orElse(T)`
(return a default value if value not present) and
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#ifPresent(java.util.function.Consumer<?%20super%20T>)` (execute a block
of code if the value is present).

### Public Method Summary

|---|---|
| static \<T\> [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\> | [empty](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#empty())() Returns an empty `Optional` instance. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Indicates whether some other object is "equal to" this Optional. |
| [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\> | [filter](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#filter(java.util.function.Predicate<?%20super%20T>))([Predicate](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Predicate.html)\<? super T\> predicate) If a value is present, and the value matches the given predicate, return an `Optional` describing the value, otherwise return an empty `Optional`. |
| \<U\> [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<U\> | [flatMap](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#flatMap(java.util.function.Function<?%20super%20T,%20java.util.Optional<U>>))([Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<? super T, [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<U\>\> mapper) If a value is present, apply the provided `Optional`-bearing mapping function to it, return that result, otherwise return an empty `Optional`. |
| T | [get](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#get())() If a value is present in this `Optional`, returns the value, otherwise throws `NoSuchElementException`. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#hashCode())() Returns the hash code value of the present value, if any, or 0 (zero) if no value is present. |
| void | [ifPresent](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#ifPresent(java.util.function.Consumer<?%20super%20T>))([Consumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Consumer.html)\<? super T\> consumer) If a value is present, invoke the specified consumer with the value, otherwise do nothing. |
| boolean | [isPresent](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#isPresent())() Return `true` if there is a value present, otherwise `false`. |
| \<U\> [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<U\> | [map](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#map(java.util.function.Function<?%20super%20T,%20?%20extends%20U>))([Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<? super T, ? extends U\> mapper) If a value is present, apply the provided mapping function to it, and if the result is non-null, return an `Optional` describing the result. |
| static \<T\> [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\> | [of](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#of(T))(T value) Returns an `Optional` with the specified present non-null value. |
| static \<T\> [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\> | [ofNullable](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#ofNullable(T))(T value) Returns an `Optional` describing the specified value, if non-null, otherwise returns an empty `Optional`. |
| T | [orElse](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#orElse(T))(T other) Return the value if present, otherwise return `other`. |
| T | [orElseGet](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#orElseGet(java.util.function.Supplier<?%20extends%20T>))([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<? extends T\> other) Return the value if present, otherwise invoke `other` and return the result of that invocation. |
| \<X extends [Throwable](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Throwable.html)\> T | [orElseThrow](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#orElseThrow(java.util.function.Supplier<?%20extends%20X>))([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<? extends X\> exceptionSupplier) Return the contained value, if present, otherwise throw an exception to be created by the provided supplier. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#toString())() Returns a non-empty string representation of this Optional suitable for debugging. |

### Inherited Method Summary

From class [java.lang.Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html)

|---|---|
| [Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) | [clone](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#clone())() Creates and returns a copy of this `Object`. |
| boolean | [equals](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#equals(java.lang.Object))([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) obj) Compares this instance with the specified object and indicates if they are equal. |
| void | [finalize](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#finalize())() Invoked when the garbage collector has detected that this instance is no longer reachable. |
| final [Class](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html)\<?\> | [getClass](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#getClass())() Returns the unique instance of `https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Class.html` that represents this object's class. |
| int | [hashCode](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#hashCode())() Returns an integer hash code for this object. |
| final void | [notify](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notify())() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| final void | [notifyAll](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#notifyAll())() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up. |
| [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html) | [toString](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#toString())() Returns a string containing a concise, human-readable description of this object. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long,%20int))(long timeout, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait(long))(long timeout) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires. |
| final void | [wait](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html#wait())() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object. |

## Public Methods

#### public static [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\>
**empty**
()

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

##### Returns

- an empty `Optional`

#### public boolean
**equals**
([Object](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Object.html) 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 />

##### Parameters

| obj | an object to be tested for equality |
|---|---|

##### Returns

- {code true} if the other object is "equal to" this object otherwise `false`

#### public [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\>
**filter**
([Predicate](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Predicate.html)\<? super T\> predicate)

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

##### Parameters

| predicate | a predicate to apply to the value, if present |
|---|---|

##### Returns

- an `Optional` describing the value of this `Optional` if a value is present and the value matches the given predicate, otherwise an empty `Optional`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if the predicate is null |
|---|---|

#### public [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<U\>
**flatMap**
([Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<? super T, [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<U\>\> mapper)

If a value is present, apply the provided `Optional`-bearing
mapping function to it, return that result, otherwise return an empty
`Optional`. This method is similar to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#map(java.util.function.Function<?%20super%20T,%20?%20extends%20U>)`,
but the provided mapper is one whose result is already an `Optional`,
and if invoked, `flatMap` does not wrap it with an additional
`Optional`.

##### Parameters

| mapper | a mapping function to apply to the value, if present the mapping function |
|---|---|

##### Returns

- the result of applying an `Optional`-bearing mapping function to the value of this `Optional`, if a value is present, otherwise an empty `Optional`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if the mapping function is null or returns a null result |
|---|---|

#### public T
**get**
()

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

##### Returns

- the non-null value held by this `Optional`

##### Throws

| [NoSuchElementException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/NoSuchElementException.html) | if there is no value present |
|---|---|

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html#isPresent()`

#### public int
**hashCode**
()

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

##### Returns

- hash code value of the present value or 0 if no value is present

#### public void
**ifPresent**
([Consumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Consumer.html)\<? super T\> consumer)

If a value is present, invoke the specified consumer with the value,
otherwise do nothing.

##### Parameters

| consumer | block to be executed if a value is present |
|---|---|

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if value is present and `consumer` is null |
|---|---|

#### public boolean
**isPresent**
()

Return `true` if there is a value present, otherwise `false`.

##### Returns

- `true` if there is a value present, otherwise `false`

#### public [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<U\>
**map**
([Function](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Function.html)\<? super T, ? extends U\> mapper)

If a value is present, apply the provided mapping function to it,
and if the result is non-null, return an `Optional` describing the
result. Otherwise return an empty `Optional`.

##### Parameters

| mapper | a mapping function to apply to the value, if present |
|---|---|

##### Returns

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

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if the mapping function is null |
|---|---|

#### public static [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\>
**of**
(T value)

Returns an `Optional` with the specified present non-null value.

##### Parameters

| value | the value to be present, which must be non-null |
|---|---|

##### Returns

- an `Optional` with the value present

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if value is null |
|---|---|

#### public static [Optional](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Optional.html)\<T\>
**ofNullable**
(T value)

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

##### Parameters

| value | the possibly-null value to describe |
|---|---|

##### Returns

- an `Optional` with a present value if the specified value is non-null, otherwise an empty `Optional`

#### public T
**orElse**
(T other)

Return the value if present, otherwise return `other`.

##### Parameters

| other | the value to be returned if there is no value present, may be null |
|---|---|

##### Returns

- the value, if present, otherwise `other`

#### public T
**orElseGet**
([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<? extends T\> other)

Return the value if present, otherwise invoke `other` and return
the result of that invocation.

##### Parameters

| other | a `Supplier` whose result is returned if no value is present |
|---|---|

##### Returns

- the value if present otherwise the result of `other.get()`

##### Throws

| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if value is not present and `other` is null |
|---|---|

#### public T
**orElseThrow**
([Supplier](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Supplier.html)\<? extends X\> exceptionSupplier)

Return the contained value, if present, otherwise throw an exception
to be created by the provided supplier.

##### Parameters

| exceptionSupplier | The supplier which will return the exception to be thrown |
|---|---|

##### Returns

- the present value

##### Throws

|   | if there is no value present |
| [NullPointerException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/NullPointerException.html) | if no value is present and `exceptionSupplier` is null |
| [Throwable](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/Throwable.html) |   |
|---|---|

#### public [String](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/String.html)
**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.

##### Returns

- the string representation of this instance