Optional
Date: 2016-05-24

com.google.common.base

## Class Optional<T>

- java.lang.Object
- - com.google.common.base.Optional<T>

- Type Parameters:
    `T` - the type of instance that can be contained. `Optional` is naturally covariant on this type, so it is safe to cast an `Optional<T>` to `Optional<S>` for any supertype `S` of `T`.
  All Implemented Interfaces:
    java.io.Serializable

      @CheckReturnValue
      @GwtCompatible(serializable=true)
      public abstract class Optional<T>
      extends java.lang.Object
      implements java.io.Serializable

  An immutable object that may contain a non-null reference to another object. Each instance of this type either contains a non-null reference, or contains nothing (in which case we say that the reference is "absent"); it is never said to "contain `null`".

  A non-null `Optional<T>` reference can be used as a replacement for a nullable `T` reference. It allows you to represent "a `T` that must be present" and a "a `T` that might be absent" as two distinct types in your program, which can aid clarity.

  Some uses of this class include

  - As a method return type, as an alternative to returning `null` to indicate that no value was available
  - To distinguish between "unknown" (for example, not present in a map) and "known to have no value" (present in the map, with value `Optional.absent()`)
  - To wrap nullable references for storage in a collection that does not support `null` (though there are several other approaches to this that should be considered first)

  A common alternative to using this class is to find or create a suitable null object for the type in question.

  This class is not intended as a direct analogue of any existing "option" or "maybe" construct from other programming environments, though it may bear some similarities.

  Comparison to `java.util.Optional` (JDK 8 and higher): A new `Optional` class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot share a common supertype). All known differences are listed either here or with the relevant methods below.

  - This class is serializable; `java.util.Optional` is not.
  - `java.util.Optional` has the additional methods `ifPresent`, `filter`, `flatMap`, and `orElseThrow`.
  - `java.util` offers the primitive-specialized versions `OptionalInt`, `OptionalLong` and `OptionalDouble`, the use of which is recommended; Guava does not have these.

  There are no plans to deprecate this class in the foreseeable future. However, we do gently recommend that you prefer the new, standard Java class whenever possible.

  See the Guava User Guide article on using `Optional`.

  Since:
    10.0
  See Also:
    Serialized Form

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> Optional<T>` | `absent()` Returns an `Optional` instance with no contained reference.
    `abstract java.util.Set<T>` | `asSet()` Returns an immutable singleton `Set` whose only element is the contained instance if it is present; an empty immutable `Set` otherwise.
    `abstract boolean` | `equals(java.lang.Object object)` Returns `true` if `object` is an `Optional` instance, and either the contained references are equal to each other or both are absent.
    `static <T> Optional<T>` | `fromNullable(T nullableReference)` If `nullableReference` is non-null, returns an `Optional` instance containing that reference; otherwise returns `absent()`.
    `abstract T` | `get()` Returns the contained instance, which must be present.
    `abstract int` | `hashCode()` Returns a hash code for this instance.
    `abstract boolean` | `isPresent()` Returns `true` if this holder contains a (non-null) instance.
    `static <T> Optional<T>` | `of(T reference)` Returns an `Optional` instance containing the given non-null reference.
    `abstract Optional<T>` | `or(Optional<? extends T> secondChoice)` Returns this `Optional` if it has a value present; `secondChoice` otherwise.
    `abstract T` | `or(Supplier<? extends T> supplier)` Returns the contained instance if it is present; `supplier.get()` otherwise.
    `abstract T` | `or(T defaultValue)` Returns the contained instance if it is present; `defaultValue` otherwise.
    `abstract T` | `orNull()` Returns the contained instance if it is present; `null` otherwise.
    `static <T> java.lang.Iterable<T>` | `presentInstances(java.lang.Iterable<? extends Optional<? extends T>> optionals)` Returns the value of each present instance from the supplied `optionals`, in order, skipping over occurrences of `absent()`.
    `abstract java.lang.String` | `toString()` Returns a string representation for this instance.
    `abstract <V> Optional<V>` | `transform(Function<? super T,V> function)` If the instance is present, it is transformed with the given `Function`; otherwise, `absent()` is returned.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Method Detail

    - #### absent

          public static <T> Optional<T> absent()

      Returns an `Optional` instance with no contained reference.

      Comparison to `java.util.Optional`: this method is equivalent to Java 8's `Optional.empty`.

    - #### of

          public static <T> Optional<T> of(T reference)

      Returns an `Optional` instance containing the given non-null reference. To have `null` treated as `absent()`, use `fromNullable(T)` instead.

      Comparison to `java.util.Optional`: no differences.

      Throws:
        `java.lang.NullPointerException` - if `reference` is null

    - #### fromNullable

          public static <T> Optional<T> fromNullable(@Nullable
                                     T nullableReference)

      If `nullableReference` is non-null, returns an `Optional` instance containing that reference; otherwise returns `absent()`.

      Comparison to `java.util.Optional`: this method is equivalent to Java 8's `Optional.ofNullable`.

    - #### isPresent

          public abstract boolean isPresent()

      Returns `true` if this holder contains a (non-null) instance.

      Comparison to `java.util.Optional`: no differences.

    - #### get

          public abstract T get()

      Returns the contained instance, which must be present. If the instance might be absent, use `or(Object)` or `orNull()` instead.

      Comparison to `java.util.Optional`: when the value is absent, this method throws `IllegalStateException`, whereas the Java 8 counterpart throws `NoSuchElementException`.

      Throws:
        `java.lang.IllegalStateException` - if the instance is absent (`isPresent()` returns `false`); depending on this specific exception type (over the more general `RuntimeException`) is discouraged

    - #### or

          public abstract T or(T defaultValue)

      Returns the contained instance if it is present; `defaultValue` otherwise. If no default value should be required because the instance is known to be present, use `get()` instead. For a default value of `null`, use `orNull()`.

      Note about generics: The signature `public T or(T defaultValue)` is overly restrictive. However, the ideal signature, `public <S super T> S or(S)`, is not legal Java. As a result, some sensible operations involving subtypes are compile errors:

             Optional<Integer> optionalInt = getSomeOptionalInt();
             Number value = optionalInt.or(0.5); // error

             FluentIterable<? extends Number> numbers = getSomeNumbers();
             Optional<? extends Number> first = numbers.first();
             Number value = first.or(0.5); // error

      As a workaround, it is always safe to cast an `Optional<? extends T>` to `Optional<T>`. Casting either of the above example `Optional` instances to `Optional<Number>` (where `Number` is the desired output type) solves the problem:

             Optional<Number> optionalInt = (Optional) getSomeOptionalInt();
             Number value = optionalInt.or(0.5); // fine

             FluentIterable<? extends Number> numbers = getSomeNumbers();
             Optional<Number> first = (Optional) numbers.first();
             Number value = first.or(0.5); // fine

      Comparison to `java.util.Optional`: this method is similar to Java 8's `Optional.orElse`, but will not accept `null` as a `defaultValue` (`orNull()` must be used instead). As a result, the value returned by this method is guaranteed non-null, which is not the case for the `java.util` equivalent.

    - #### or

          public abstract Optional<T> or(Optional<? extends T> secondChoice)

      Returns this `Optional` if it has a value present; `secondChoice` otherwise.

      Comparison to `java.util.Optional`: this method has no equivalent in Java 8's `Optional` class; write `thisOptional.isPresent() ? thisOptional : secondChoice` instead.

    - #### or

          @Beta
          public abstract T or(Supplier<? extends T> supplier)

      Returns the contained instance if it is present; `supplier.get()` otherwise.

      Comparison to `java.util.Optional`: this method is similar to Java 8's `Optional.orElseGet`, except when `supplier` returns `null`. In this case this method throws an exception, whereas the Java 8 method returns the `null` to the caller.

      Throws:
        `java.lang.NullPointerException` - if this optional's value is absent and the supplier returns `null`

    - #### orNull

          @Nullable
          public abstract T orNull()

      Returns the contained instance if it is present; `null` otherwise. If the instance is known to be present, use `get()` instead.

      Comparison to `java.util.Optional`: this method is equivalent to Java 8's `Optional.orElse(null)`.

    - #### asSet

          public abstract java.util.Set<T> asSet()

      Returns an immutable singleton `Set` whose only element is the contained instance if it is present; an empty immutable `Set` otherwise.

      Comparison to `java.util.Optional`: this method has no equivalent in Java 8's `Optional` class. However, this common usage:

             for (Foo foo : possibleFoo.asSet()) {
               doSomethingWith(foo);
             }

      ... can be replaced with:

             possibleFoo.ifPresent(foo -> doSomethingWith(foo));

      Since:
        11.0

    - #### transform

          public abstract <V> Optional<V> transform(Function<? super T,V> function)

      If the instance is present, it is transformed with the given `Function`; otherwise, `absent()` is returned.

      Comparison to `java.util.Optional`: this method is similar to Java 8's `Optional.map`, except when `function` returns `null`. In this case this method throws an exception, whereas the Java 8 method returns `Optional.absent()`.

      Throws:
        `java.lang.NullPointerException` - if the function returns `null`
      Since:
        12.0

    - #### equals

          public abstract boolean equals(@Nullable
                       java.lang.Object object)

      Returns `true` if `object` is an `Optional` instance, and either the contained references are equal to each other or both are absent. Note that `Optional` instances of differing parameterized types can be equal.

      Comparison to `java.util.Optional`: no differences.

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public abstract int hashCode()

      Returns a hash code for this instance.

      Comparison to `java.util.Optional`: this class leaves the specific choice of hash code unspecified, unlike the Java 8 equivalent.

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          public abstract java.lang.String toString()

      Returns a string representation for this instance.

      Comparison to `java.util.Optional`: this class leaves the specific string representation unspecified, unlike the Java 8 equivalent.

      Overrides:
        `toString` in class `java.lang.Object`

    - #### presentInstances

          @Beta
          public static <T> java.lang.Iterable<T> presentInstances(java.lang.Iterable<? extends Optional<? extends T>> optionals)

      Returns the value of each present instance from the supplied `optionals`, in order, skipping over occurrences of `absent()`. Iterators are unmodifiable and are evaluated lazily.

      Comparison to `java.util.Optional`: this method has no equivalent in Java 8's `Optional` class; use `optionals.stream().filter(Optional::isPresent).map(Optional::get)` instead.

      Since:
        11.0 (generics widened in 13.0)