Package io.vavr.control

Class Option<T>

  • Type Parameters:
    T - The type of the optional value.
    All Implemented Interfaces:
    Iterable<T>, java.io.Serializable, java.lang.Iterable<T>
    public abstract class Option<T>
extends java.lang.Object
implements Iterable<T>, java.io.Serializable
    Replacement for Optional.

    Option is a monadic container type which represents an optional value.

    Most of the API is taken from Optional. A similar type can be found in Haskell and Scala.

    See Also:
    Serialized Form

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      <R,​A>
      R      		 collect​(java.util.stream.Collector<? super T,​A,​R> collector)
      Collects the underlying value (if present) using the provided collector.
      abstract boolean equals​(java.lang.Object that)
      Checks if this Option is equal to the given object o.
      Option<T> filter​(java.util.function.Predicate<? super T> predicate)
      Returns Some(value) if this is a Some and the value satisfies the given predicate.
      <U> Option<U> flatMap​(java.util.function.Function<? super T,​Option<? extends U>> mapper)
      Maps the value to a new Option if this is a Some, otherwise returns None.
      <U> U fold​(java.util.function.Supplier<? extends U> ifEmpty, java.util.function.Function<? super T,​? extends U> ifDefined)
      Folds either the None or the Some side of the Option value.
      abstract T get()
      Deprecated.
      Unsafe operation (but not marked for removal).
      T getOrElse​(T other)
      Returns the value if this is a Some or the other value if this is a None.
      T getOrElseGet​(java.util.function.Supplier<? extends T> supplier)
      Returns the value if this is a Some, otherwise the other value is returned, if this is a None.
      <X extends java.lang.Throwable>
      T      		 getOrElseThrow​(java.util.function.Supplier<X> exceptionProvider)
      Returns the value if this is a Some, otherwise throws an exception.
      abstract int hashCode()
      Computes the hash of this Option.
      abstract boolean isDefined()
      Returns true, if this is Some, otherwise false, if this is None.
      abstract boolean isEmpty()
      Returns true, if this is None, otherwise false, if this is Some.
      Iterator<T> iterator()
      Returns an Iterator that allows us to perform intermediate, sequential operations known from Vavr's collection library.
      <U> Option<U> map​(java.util.function.Function<? super T,​? extends U> mapper)
      Maps the value and wraps it in a new Some if this is a Some, returns None.
      static <T> Option<T> none()
      Returns the single instance of None
      static <T> Option<T> of​(T value)
      Creates a new Option of a given value.
      static <T> Option<T> ofOptional​(java.util.Optional<? extends T> optional)
      Wraps a Java Optional to a new Option
      Option<T> onDefined​(java.util.function.Consumer<? super T> action)
      Applies an action to this value if this is defined, otherwise nothing happens.
      Option<T> onEmpty​(java.lang.Runnable action)
      Runs a Java Runnable passed as parameter if this Option is empty.
      Option<T> orElse​(java.util.function.Supplier<? extends Option<? extends T>> supplier)
      Returns this Option if it is nonempty, otherwise return the result of evaluating supplier.
      static <T> Option<T> some​(T value)
      Creates a new Some of a given value.
      java.util.stream.Stream<T> stream()
      Converts this Option to a Stream.
      <U> Either<U,​T> toEither​(java.util.function.Supplier<? extends U> leftSupplier)
      Converts this Option to an Either.
      java.util.Optional<T> toOptional()
      Converts this Option to an Optional.
      abstract java.lang.String toString()
      Returns a string representation of this Option.
      Try<T> toTry​(java.util.function.Supplier<? extends java.lang.Throwable> ifEmpty)
      Converts this Option to a Try.
      <U> Option<U> transform​(java.util.function.Supplier<? extends Option<? extends U>> ifEmpty, java.util.function.Function<? super T,​? extends Option<? extends U>> ifDefined)
      Transforms this Option by applying either ifDefined to this value or by calling ifEmpty.
      static <T> Option<T> unless​(boolean condition, java.util.function.Supplier<? extends T> supplier)
      Unless the given condition is true, Some(supplier.get()) is returned.
      static <T> Option<T> when​(boolean condition, java.util.function.Supplier<? extends T> supplier)
      When the given condition is true, Some(supplier.get()) is returned.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Method Detail

      • of

        public static <T> Option<T> of​(T value)
        Creates a new Option of a given value.
        Type Parameters:
        T - type of the value
        Parameters:
        value - A value
        Returns:
        A new Option containing the given value if value is not null, otherwise the empty Option.

      • some

        public static <T> Option<T> some​(T value)
        Creates a new Some of a given value.

        The only difference to of(Object) is, when called with argument null. 

         
 Option.of(null);   // = None
 Option.some(null); // = Some(null)
        Type Parameters:
        T - type of the value
        Parameters:
        value - A value
        Returns:
        Some(value)

      • none

        public static <T> Option<T> none()
        Returns the single instance of None
        Type Parameters:
        T - component type
        Returns:
        the single instance of None

      • when

        public static <T> Option<T> when​(boolean condition,
                                 java.util.function.Supplier<? extends T> supplier)
        When the given condition is true, Some(supplier.get()) is returned. Otherwise, None is returned.

        Same as Option.unless(!condition, supplier).

        Type Parameters:
        T - type of the optional value
        Parameters:
        condition - A boolean value
        supplier - An optional value supplier, may supply null
        Returns:
        a new Option
        Throws:
        java.lang.NullPointerException - if the given supplier is null
        See Also:
        unless(boolean, Supplier)

      • unless

        public static <T> Option<T> unless​(boolean condition,
                                   java.util.function.Supplier<? extends T> supplier)
        Unless the given condition is true, Some(supplier.get()) is returned. Otherwise, None is returned.

        Same as Option.when(!condition, supplier).

        Type Parameters:
        T - type of the optional value
        Parameters:
        condition - A boolean value
        supplier - An optional value supplier, may supply null
        Returns:
        a new Option
        Throws:
        java.lang.NullPointerException - if the given supplier is null
        See Also:
        when(boolean, Supplier)

      • ofOptional

        public static <T> Option<T> ofOptional​(java.util.Optional<? extends T> optional)
        Wraps a Java Optional to a new Option
        Type Parameters:
        T - type of the value
        Parameters:
        optional - a given optional to wrap in Option
        Returns:
        Some(optional.get()) if value is Java Optional is present, None otherwise

      • collect

        public <R,​A> R collect​(java.util.stream.Collector<? super T,​A,​R> collector)
        Collects the underlying value (if present) using the provided collector.

        Shortcut for .stream().collect(collector).

        Type Parameters:
        A - the mutable accumulation type of the reduction operation
        R - the result type of the reduction operation
        Parameters:
        collector - Collector performing reduction
        Returns:
        the reduction result of type R
        Throws:
        java.lang.NullPointerException - if the given collector is null

      • filter

        public Option<T> filter​(java.util.function.Predicate<? super T> predicate)
        Returns Some(value) if this is a Some and the value satisfies the given predicate. Otherwise None is returned.
        Parameters:
        predicate - A predicate which is used to test an optional value
        Returns:
        Some(value) or None as specified

      • flatMap

        public <U> Option<U> flatMap​(java.util.function.Function<? super T,​Option<? extends U>> mapper)
        Maps the value to a new Option if this is a Some, otherwise returns None.
        Type Parameters:
        U - Component type of the resulting Option
        Parameters:
        mapper - A mapper
        Returns:
        a new Option

      • fold

        public <U> U fold​(java.util.function.Supplier<? extends U> ifEmpty,
                  java.util.function.Function<? super T,​? extends U> ifDefined)
        Folds either the None or the Some side of the Option value.
        Type Parameters:
        U - type of the folded value
        Parameters:
        ifEmpty - maps the left value if this is a None
        ifDefined - maps the value if this is a Some
        Returns:
        A value of type U
        Throws:
        java.lang.NullPointerException - if one of the given ifEmpty or ifDefined is null

      • get

        @Deprecated
public abstract T get()
               throws java.util.NoSuchElementException
        Deprecated.
        Unsafe operation (but not marked for removal). User getOrElse(Object), getOrElseGet(Supplier) or getOrElseThrow(Supplier) instead. Other alternatives are onDefined(Consumer), Iterable.forEach(Consumer) or iteration using a for-loop.
        Gets the value if this is a Some or throws if this is a None.
        Returns:
        the value
        Throws:
        java.util.NoSuchElementException - if this is a None.

      • getOrElse

        public T getOrElse​(T other)
        Returns the value if this is a Some or the other value if this is a None.

        Please note, that the other value is eagerly evaluated.

        Parameters:
        other - An alternative value
        Returns:
        This value, if this Option is defined or the other value, if this Option is empty.

      • getOrElseGet

        public T getOrElseGet​(java.util.function.Supplier<? extends T> supplier)
        Returns the value if this is a Some, otherwise the other value is returned, if this is a None.

        Please note, that the other value is lazily evaluated.

        Parameters:
        supplier - An alternative value supplier
        Returns:
        This value, if this Option is defined or the other value, if this Option is empty.

      • getOrElseThrow

        public <X extends java.lang.Throwable> T getOrElseThrow​(java.util.function.Supplier<X> exceptionProvider)
                                                 throws X extends java.lang.Throwable
        Returns the value if this is a Some, otherwise throws an exception.
        Type Parameters:
        X - A throwable
        Parameters:
        exceptionProvider - An exception provider
        Returns:
        This value, if this Option is defined, otherwise throws X
        Throws:
        X - if this Option is empty
        java.lang.NullPointerException - if the given exceptionProvider is null
        X extends java.lang.Throwable

      • isDefined

        public abstract boolean isDefined()
        Returns true, if this is Some, otherwise false, if this is None.

        Please note that it is possible to create new Some(null), which is defined.

        Returns:
        true, if this Option has a defined value, false otherwise

      • isEmpty

        public abstract boolean isEmpty()
        Returns true, if this is None, otherwise false, if this is Some.
        Returns:
        true, if this Option is empty, false otherwise

      • iterator

        public Iterator<T> iterator()
        Description copied from interface: Iterable
        Returns an Iterator that allows us to perform intermediate, sequential operations known from Vavr's collection library.
        Specified by:
        iterator in interface Iterable<T>
        Specified by:
        iterator in interface java.lang.Iterable<T>
        Returns:
        an Iterator instance. It is not necessarily a new instance, like that returned by Iterator.empty().

      • map

        public <U> Option<U> map​(java.util.function.Function<? super T,​? extends U> mapper)
        Maps the value and wraps it in a new Some if this is a Some, returns None.
        Type Parameters:
        U - The new value type
        Parameters:
        mapper - A value mapper
        Returns:
        a new Some containing the mapped value if this Option is defined, otherwise None, if this is empty.

      • onEmpty

        public Option<T> onEmpty​(java.lang.Runnable action)
        Runs a Java Runnable passed as parameter if this Option is empty.
        Parameters:
        action - a given Runnable to be run
        Returns:
        this Option
        Throws:
        java.lang.NullPointerException - if the given action is null

      • onDefined

        public Option<T> onDefined​(java.util.function.Consumer<? super T> action)
        Applies an action to this value if this is defined, otherwise nothing happens.
        Parameters:
        action - An action which can be applied to an optional value
        Returns:
        this Option
        Throws:
        java.lang.NullPointerException - if the given action is null

      • orElse

        public Option<T> orElse​(java.util.function.Supplier<? extends Option<? extends T>> supplier)
        Returns this Option if it is nonempty, otherwise return the result of evaluating supplier.
        Parameters:
        supplier - An alternative Option supplier
        Returns:
        this Option if it is nonempty, otherwise return the result of evaluating supplier.

      • stream

        public java.util.stream.Stream<T> stream()
        Converts this Option to a Stream.
        Returns:
        Stream.of(get() if this is a Some, otherwise Stream.empty()

      • toEither

        public <U> Either<U,​T> toEither​(java.util.function.Supplier<? extends U> leftSupplier)
        Converts this Option to an Either.
        Type Parameters:
        U - the left type of the Either
        Parameters:
        leftSupplier - a left value supplier
        Returns:
        Either.right(get() if this is a defined Option, otherwise Either.left(leftSupplier.get())
        Throws:
        java.lang.NullPointerException - if the given leftSupplier is null

      • toOptional

        public java.util.Optional<T> toOptional()
        Converts this Option to an Optional.
        Returns:
        Optional.ofNullable(get()) if this is defined, otherwise Optional.empty()

      • toTry

        public Try<T> toTry​(java.util.function.Supplier<? extends java.lang.Throwable> ifEmpty)
        Converts this Option to a Try.
        Parameters:
        ifEmpty - supplies a Throwable if this Option is empty
        Returns:
        Try.success(get() if this is a defined Option, otherwise Try.failure(ifEmpty.get())
        Throws:
        java.lang.NullPointerException - if the given ifEmpty is null

      • transform

        public <U> Option<U> transform​(java.util.function.Supplier<? extends Option<? extends U>> ifEmpty,
                               java.util.function.Function<? super T,​? extends Option<? extends U>> ifDefined)
        Transforms this Option by applying either ifDefined to this value or by calling ifEmpty.
        Type Parameters:
        U - type of the transformed value
        Parameters:
        ifEmpty - supplies an Option if this Option is empty
        ifDefined - maps the value if this Option is defined
        Returns:
        A new Option instance
        Throws:
        java.lang.NullPointerException - if one of the given ifDefined or ifEmpty is null

      • equals

        public abstract boolean equals​(java.lang.Object that)
        Checks if this Option is equal to the given object o.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        that - an object, may be null
        Returns:
        true, if this and that both are a defined Option and the underlying values are equal or if this and that both are an empty Option. Otherwise it returns false.

      • hashCode

        public abstract int hashCode()
        Computes the hash of this Option.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        31 + Objects.hashCode(get()) if this is a Some, otherwise 1

      • toString

        public abstract java.lang.String toString()
        Returns a string representation of this Option.
        Overrides:
        toString in class java.lang.Object
        Returns:
        "Some(" + get() + ")" if this Option is defined, otherwise "None"