Package: java.util

## [Java] Class Optional

- java.util.Optional

-     public class Optional
      extends Object

  GDK enhancements for Optional.

  displayName:
    Optional
  receiverFqcn:
    java.util.Optional

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `asBoolean()` Coerce an `Optional` instance to a `boolean` value.
    `<S, T>` | `public Optional<T>` | `collect(Closure<T> transform)` If a value is present in the `Optional`, returns transformed value obtained using the `transform` closure or no value as an optional.
    `<T>` | `public Optional<T>` | `filter(Class<T> type)` Tests given value against specified type and changes generics of result.
    `<T, E>` | `public Collection<T>` | `flatten()` Flatten an Optional.
    `<T>` | `public T` | `getAt(int index)` If a value is present in the `Optional`, returns the value or null.
    `<T>` | `public OptionalDouble` | `mapToDouble(ToDoubleFunction<? super T> mapper)` If a value is present in the `Optional`, returns an `OptionalDouble` consisting of the result of applying the given function to the value or else empty.
    `<T>` | `public OptionalInt` | `mapToInt(ToIntFunction<? super T> mapper)` If a value is present in the `Optional`, returns an `OptionalInt` consisting of the result of applying the given function to the value or else empty.
    `<T>` | `public OptionalLong` | `mapToLong(ToLongFunction<? super T> mapper)` If a value is present in the `Optional`, returns an `OptionalLong` consisting of the result of applying the given function to the value or else empty.
    `<T>` | `public Optional<T>` | `orOptional(Supplier<Optional<? extends T>> supplier)` Provides similar functionality to JDK9 `or` on JDK8.
    `<T>` | `public Optional<T>` | `peek(Consumer<? super T> action)` If a value is present in the `Optional`, executes the specified `action` with the value as input and then returns `self`.
    `<T>` | `public Stream<T>` | `stream()` If a value is present in the Optional, returns a Stream with the value as its source or else an empty stream.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, clamp, clamp, collect, collect, collect, dump, each, eachMatch, eachMatch, eachWithIndex, every, every, find, find, findAll, findAll, findIndexOf, findIndexOf, findIndexValues, findIndexValues, findLastIndexOf, findLastIndexOf, findResult, findResult, findResult, findResult, getAt, getMetaClass, getMetaPropertyValues, getProperties, grep, grep, hasProperty, identity, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, takeIf, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method Detail

    - #### public boolean asBoolean()

      Coerce an `Optional` instance to a `boolean` value.

           assert !Optional.empty().asBoolean()
           assert Optional.of(1234).asBoolean()

      Returns:
        `true` if a value is present, `false` otherwise
      Since:
        2.5.0

    - #### <S, T> public Optional<T> collect(Closure<T> transform)

      If a value is present in the `Optional`, returns transformed value obtained using the `transform` closure or no value as an optional.

           assert Optional.of("foobar").collect{ it.size() }.get() == 6
           assert !Optional.empty().collect{ it.size() }.isPresent()

      Returns:
        an Optional containing the transformed value or empty if the input is empty or the transform returns null
      Since:
        3.0.0

    - #### <T> public Optional<T> filter(Class<T> type)

      Tests given value against specified type and changes generics of result. This is equivalent to: `self.filter(it -> it instanceof Type).map(it -> (Type) it)`

           assert !Optional.empty().filter(Number).isPresent()
           assert !Optional.of('x').filter(Number).isPresent()
           assert Optional.of(1234).filter(Number).isPresent()
           assert Optional.of(1234).filter(Number).get().equals(1234)

      Since:
        3.0.0

    - #### <T, E> public Collection<T> flatten()

      Flatten an Optional. This yields a collection containing the Optional value if the Optional is present, or an empty collection otherwise.

      Example:

           assert Optional.of(1).flatten() == [1]
           assert Optional.empty().flatten() == []

      Returns:
        a flattened Optional
      Since:
        5.0.0

    - #### <T> public T getAt(int index)

      If a value is present in the `Optional`, returns the value or null.

           def opt = Optional.empty()
           assert opt[-1] == null
           assert opt[0] == null
           opt = Optional.of('')
           assert opt[-1] == ''
           assert opt[0] == ''

           groovy.test.GroovyAssert.shouldFail(IndexOutOfBoundsException) { opt[1] }

           // use via destructuring
           opt = Optional.empty()
           def (String s) = opt
           assert s == null
           opt = Optional.of('')
           (s) = opt
           assert s == ''

      throws:
        IndexOutOfBoundsException if index is not 0 or -1
      Since:
        5.0.0

    - #### <T> public OptionalDouble mapToDouble(ToDoubleFunction<? super T> mapper)

      If a value is present in the `Optional`, returns an `OptionalDouble` consisting of the result of applying the given function to the value or else empty.

           assert !Optional.empty().mapToDouble(x -> Math.PI).isPresent()
           assert  Optional.of('x').mapToDouble(x -> Math.PI).getAsDouble() == Math.PI

      Since:
        3.0.0

    - #### <T> public OptionalInt mapToInt(ToIntFunction<? super T> mapper)

      If a value is present in the `Optional`, returns an `OptionalInt` consisting of the result of applying the given function to the value or else empty.

           assert !Optional.empty().mapToInt(x -> 42).isPresent()
           assert  Optional.of('x').mapToInt(x -> 42).getAsInt() == 42

      Since:
        3.0.0

    - #### <T> public OptionalLong mapToLong(ToLongFunction<? super T> mapper)

      If a value is present in the `Optional`, returns an `OptionalLong` consisting of the result of applying the given function to the value or else empty.

           assert !Optional.empty().mapToLong(x -> 42L).isPresent()
           assert  Optional.of('x').mapToLong(x -> 42L).getAsLong() == 42L

      Since:
        3.0.0

    - #### <T> public Optional<T> orOptional(Supplier<Optional<? extends T>> supplier)

      Provides similar functionality to JDK9 `or` on JDK8.

           def x = Optional.empty()
           def y = Optional.of('y')
           assert y.orOptional(() -> Optional.of('z')).get() == 'y'
           assert x.orOptional(() -> Optional.of('z')).get() == 'z'

      Since:
        3.0.6

    - #### <T> public Optional<T> peek(Consumer<? super T> action)

      If a value is present in the `Optional`, executes the specified `action` with the value as input and then returns `self`.

           boolean called = false
           def opt = Optional.empty()
           def out = opt.peek{ called = true }
           assert out === opt
           assert !called

           opt = Optional.of('x')
           out = opt.peek{ assert it == 'x'; called = true }
           assert out === opt
           assert called

      Since:
        5.0.0

    - #### <T> public Stream<T> stream()

      If a value is present in the Optional, returns a Stream with the value as its source or else an empty stream.

      Since:
        3.0.0