Package org.storynode.pigeon.option

Class Option<T>

java.lang.Object
org.storynode.pigeon.option.Option<T>
Type Parameters:
T -
All Implemented Interfaces:
SafelyWrapped<T>, Wrapped<T>
Direct Known Subclasses:
None, Some
public abstract class Option<T> extends Object implements SafelyWrapped<T>
Describes a value that can be Some value or None.

Why this and not Optional?

This implementation aims to be a - slightly - faster implementation of Optional, ditching all checks that comes at every method call that needs to assess if the value is empty or not before doing anything, in favour of fixed implementations.

For example: when calling map(Function) it doesn't need to check if this is empty or not because Option itself is abstract, and its inheritors (Some and None) already know if they must execute the mapping function or not.

The same applies to a variety of other methods, so for an intensive of this type of construct using Option instead of Optional can avoid ** a lot** of condition checks (potentially).

Author:
Andrea Coronese

  • Constructor Summary

    Constructors
    Constructor
    Description
    Option()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract Option<T>
    filter(Predicate<? super T> predicate)
    If a value is present, and the value matches the given predicate, returns an Option describing the value, otherwise returns an empty Option.
    abstract <U> Option<U>
    flatMap(Function<? super T,? extends Option<? 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.
    abstract void
    ifPresent(Consumer<T> func)
    Executes func if this is Some, consuming the contained value.
    abstract void
    ifPresentOrElse(Consumer<T> whenPresent, Runnable otherwise)
    Executes whenPresent if this is Some, consuming the contained value, or runs otherwise if this is None
    boolean
    isNone()
    Whether this option contains a value or not
    abstract boolean
    isSome()
    Whether this option contains a value or not
    abstract <U> Option<U>
    map(@NotNull Function<T,U> mapper)
    If a value is present, returns an Option describing (as if by some(T)) the result of applying the given mapping function to the value, otherwise returns an empty Option.
    static <T> @NotNull None<T>
    none()
    Creates an empty (None) Option
    static <T> @NotNull Option<T>
    of(@NotNull Supplier<T> valueSupplier)
    Creates a new Option with some value in it.
    static <T> @NotNull Option<T>
    of(T value)
    Creates a new Option with some value in it.
    abstract Option<? extends T>
    or(@NotNull Supplier<? extends Option<? extends T>> supplier)
    If a value is present, returns an Option describing the value, otherwise returns an Option produced by the given supplying function
    abstract T
    orElse(T other)
    If a value is present, returns the value, otherwise returns other.
    abstract T
    orElseGet(@NotNull Supplier<T> supplier)
    If a value is present, returns the value, otherwise returns the result produced by the supplying function.
    abstract T
    orElseThrow()
    If a value is present returns that value, otherwise throws NoSuchElementException.
    abstract <E extends Throwable>
    T
    orElseThrow(@NotNull Supplier<E> throwable)
    If a value is present returns that value, otherwise throws the supplied Throwable.
    static <T> @NotNull Option<T>
    some(T value)
    Creates a new Option with some value in it.
    abstract Stream<T>
    stream()
    Streams the contained value, if any.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface org.storynode.pigeon.protocol.SafelyWrapped

    tryUnwrap

    Methods inherited from interface org.storynode.pigeon.protocol.Wrapped

    unwrap

  • Constructor Details

    • Option

      public Option()

  • Method Details

    • some

      @Contract(value="_ -> new", pure=true) @NotNull public static <T> @NotNull Option<T> some(@NotNull T value)
      Creates a new Option with some value in it. If the provided value is null then the option will be empty (None).
      Type Parameters:
      T - The type of the inner value
      Parameters:
      value - The value to wrap
      Returns:
      The created Option

    • of

      @NotNull public static <T> @NotNull Option<T> of(T value)
      Creates a new Option with some value in it. If the provided value is null then the option will be empty (None).
      Type Parameters:
      T - The type of the inner value
      Parameters:
      value - The value to wrap
      Returns:
      The created Option

    • of

      @NotNull public static <T> @NotNull Option<T> of(@NotNull @NotNull Supplier<T> valueSupplier)
      Creates a new Option with some value in it. If the provided value is null then the option will be empty (None).
      Type Parameters:
      T - The type of the inner value
      Parameters:
      valueSupplier - The supplier for the value to wrap
      Returns:
      The created Option

    • none

      @NotNull public static <T> @NotNull None<T> none()
      Creates an empty (None) Option
      Type Parameters:
      T - a T class
      Returns:
      a None object

    • isSome

      public abstract boolean isSome()
      Whether this option contains a value or not
      Returns:
      true if this contains a value, false otherwise
      See Also:

    • isNone

      public boolean isNone()
      Whether this option contains a value or not
      Returns:
      false if this contains a value, true otherwise
      See Also:

    • ifPresent

      public abstract void ifPresent(Consumer<T> func)
      Executes func if this is Some, consuming the contained value.
      Parameters:
      func - The function to execute

    • ifPresentOrElse

      public abstract void ifPresentOrElse(Consumer<T> whenPresent, Runnable otherwise)
      Executes whenPresent if this is Some, consuming the contained value, or runs otherwise if this is None
      Parameters:
      whenPresent - The function to execute if this is Some
      otherwise - The function to execute if this is None

    • filter

      public abstract Option<T> filter(Predicate<? super T> predicate)
      If a value is present, and the value matches the given predicate, returns an Option describing the value, otherwise returns an empty Option.
      Parameters:
      predicate - the predicate to apply to a value, if present
      Returns:
      an Option describing the value of this Option, if a value is present and the value matches the given predicate, otherwise an empty Option
      Throws:
      NullPointerException - if the predicate is null

    • map

      public abstract <U> Option<U> map(@NotNull @NotNull Function<T,U> mapper)
      If a value is present, returns an Option describing (as if by some(T)) the result of applying the given mapping function to the value, otherwise returns an empty Option.

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

      Type Parameters:
      U - The type of the value returned from the mapping function
      Parameters:
      mapper - the mapping function to apply to a value, if present
      Returns:
      an Option describing the result of applying a mapping function to the value of this Option, if a value is present, otherwise an empty Option
      Throws:
      NullPointerException - if the mapping function is null

    • flatMap

      public abstract <U> Option<U> flatMap(Function<? super T,? extends Option<? 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 map(Function), but the mapping function is one whose result is already an Optional, and if invoked, flatMap does not wrap it within an additional Optional.

      Type Parameters:
      U - The type of value of the Optional returned by the mapping function
      Parameters:
      mapper - the mapping function to apply to a value, if present
      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

    • or

      public abstract Option<? extends T> or(@NotNull @NotNull Supplier<? extends Option<? extends T>> supplier)
      If a value is present, returns an Option describing the value, otherwise returns an Option produced by the given supplying function
      Parameters:
      supplier - The supplier that produces the Option in case a value is not present in this
      Returns:
      An Option with the value of this, if any is present, or another Option supplied by the provided supplying function

    • orElseGet

      public abstract T orElseGet(@NotNull @NotNull Supplier<T> supplier)
      If a value is present, returns the value, otherwise returns the result produced by the supplying function.
      Parameters:
      supplier - the supplying function that produces a value to be returned
      Returns:
      the value, if present, otherwise the result produced by the supplying function
      Throws:
      NullPointerException - if no value is present and the supplying function is null

    • orElse

      public abstract T orElse(T other)
      If a value is present, returns the value, otherwise returns other.
      Parameters:
      other - the value to be returned, if no value is present. May be null.
      Returns:
      the value, if present, otherwise other

    • orElseThrow

      public abstract T orElseThrow() throws NoSuchElementException
      If a value is present returns that value, otherwise throws NoSuchElementException.

      Please note that this is mainly for API compatibility with Optional but should be avoided in favour of orElse(Object) and orElseGet(Supplier)

      Returns:
      The contained value, if present
      Throws:
      NoSuchElementException - When the option is None

    • orElseThrow

      public abstract <E extends Throwable> T orElseThrow(@NotNull @NotNull Supplier<E> throwable) throws E
      If a value is present returns that value, otherwise throws the supplied Throwable.

      Please note that this is mainly for API compatibility with Optional but should be avoided in favour of orElse(Object) and orElseGet(Supplier)

      Type Parameters:
      E - The concrete type of the Throwable
      Parameters:
      throwable - The function that supplies the exception to throw
      Returns:
      a T object
      Throws:
      E - if any.

    • stream

      public abstract Stream<T> stream()
      Streams the contained value, if any.
      Returns:
      a Stream object