Package io.vavr.control

Class Either<L,​R>

  • Type Parameters:
    L - The type of the Left value of an Either.
    R - The type of the Right value of an Either.
    All Implemented Interfaces:
    Iterable<R>, java.io.Serializable, java.lang.Iterable<R>
    public abstract class Either<L,​R>
extends java.lang.Object
implements Iterable<R>, java.io.Serializable
    Either represents a value of two possible types. An Either is either a Either.Left or a Either.Right.
    See Also:
    Serialized Form

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      <T,​A>
      T      		 collect​(java.util.stream.Collector<? super R,​A,​T> collector)
      Collects the underlying value (if present) using the provided collector.
      static <L,​R>
      Either<L,​R>      		 cond​(boolean test, java.util.function.Supplier<? extends L> leftSupplier, java.util.function.Supplier<? extends R> rightSupplier)
      Conditionally returns either a Left or a Right, depending of the given test value.
      abstract boolean equals​(java.lang.Object that)
      Checks if this Either is equal to the given object o.
      Either<L,​R> filterOrElse​(java.util.function.Predicate<? super R> predicate, java.util.function.Function<? super R,​? extends L> zero)
      Filters this right-biased Either by testing a predicate.
      <U> Either<L,​U> flatMap​(java.util.function.Function<? super R,​Either<L,​? extends U>> mapper)
      FlatMaps this right-biased Either.
      <U> U fold​(java.util.function.Function<? super L,​? extends U> ifLeft, java.util.function.Function<? super R,​? extends U> ifRight)
      Folds either the left or the right side of this disjunction.
      abstract R get()
      Deprecated.
      Unsafe operation (but not marked for removal).
      abstract L getLeft()
      Deprecated.
      Unsafe operation (but not marked for removal).
      R getOrElse​(R other)
      Gets the Right value or an alternate value, if the Either is a Left.
      R getOrElseGet​(java.util.function.Function<? super L,​? extends R> other)
      Gets the Right value or an alternate value, if the Either is a Left.
      <X extends java.lang.Throwable>
      R      		 getOrElseThrow​(java.util.function.Function<? super L,​X> exceptionProvider)
      Gets the Right value or throws, if this Either is a Left.
      abstract int hashCode()
      Computes the hash of this Either.
      abstract boolean isLeft()
      Returns whether this Either is a Left.
      abstract boolean isRight()
      Returns whether this Either is a Right.
      Iterator<R> iterator()
      Returns an Iterator that allows us to perform intermediate, sequential operations known from Vavr's collection library.
      static <L,​R>
      Either<L,​R>      		 left​(L left)
      Constructs a Left Either.
      <U> Either<L,​U> map​(java.util.function.Function<? super R,​? extends U> mapper)
      Maps the value of this Either if it is a Right, performs no operation if this is a Left.
      <U> Either<U,​R> mapLeft​(java.util.function.Function<? super L,​? extends U> mapper)
      Maps the value of this Either if it is a Left, performs no operation if this is a Right.
      Either<L,​R> onLeft​(java.util.function.Consumer<? super L> action)
      Applies an action to this left value if this is a Left, otherwise nothing happens.
      Either<L,​R> onRight​(java.util.function.Consumer<? super R> action)
      Applies an action to this right value if this is a Right, otherwise nothing happens.
      Either<L,​R> orElse​(java.util.function.Supplier<Either<? extends L,​? extends R>> supplier)  
      static <L,​R>
      Either<L,​R>      		 right​(R right)
      Constructs a Right Either.
      java.util.stream.Stream<R> stream()
      Converts this Either to a Stream.
      Either<R,​L> swap()
      Converts a Left to a Right vice versa by wrapping the value in a new type.
      Option<R> toOption()
      Converts this Either to an Option.
      java.util.Optional<R> toOptional()
      Converts this Either to an Optional.
      abstract java.lang.String toString()
      Returns a string representation of this Either.
      Try<R> toTry​(java.util.function.Function<? super L,​? extends java.lang.Throwable> leftMapper)
      Converts this Either to a Try.
      <U> Either<L,​U> transform​(java.util.function.Function<? super L,​? extends Either<L,​? extends U>> ifLeft, java.util.function.Function<? super R,​? extends Either<L,​? extends U>> ifRight)
      Transforms this Either by applying either ifRight to this right value or ifLeft to this left value.

      • 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

      • left

        public static <L,​R> Either<L,​R> left​(L left)
        Constructs a Left Either.
        Type Parameters:
        L - Type of left value.
        R - Type of right value.
        Parameters:
        left - The value.
        Returns:
        A new Left instance.

      • right

        public static <L,​R> Either<L,​R> right​(R right)
        Constructs a Right Either.
        Type Parameters:
        L - Type of left value.
        R - Type of right value.
        Parameters:
        right - The value.
        Returns:
        A new Right instance.

      • cond

        public static <L,​R> Either<L,​R> cond​(boolean test,
                                                 java.util.function.Supplier<? extends L> leftSupplier,
                                                 java.util.function.Supplier<? extends R> rightSupplier)
        Conditionally returns either a Left or a Right, depending of the given test value.
        Type Parameters:
        L - type of a left value
        R - type of a right value
        Parameters:
        test - a boolean condition
        leftSupplier - left value supplier
        rightSupplier - right value supplier
        Returns:
        Either.right(rightSupplier.get()) if test is true, otherwise Either.left(leftSupplier.get())

      • collect

        public <T,​A> T collect​(java.util.stream.Collector<? super R,​A,​T> 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
        T - the result type of the reduction operation
        Parameters:
        collector - Collector performing reduction
        Returns:
        the reduction result of type T
        Throws:
        java.lang.NullPointerException - if the given collector is null

      • filterOrElse

        public Either<L,​R> filterOrElse​(java.util.function.Predicate<? super R> predicate,
                                      java.util.function.Function<? super R,​? extends L> zero)
        Filters this right-biased Either by testing a predicate. If the Either is a Right and the predicate doesn't match, the Either will be turned into a Left with contents computed by applying the filterVal function to the Either value.
        Parameters:
        predicate - A predicate
        zero - a function that transforms the right value to a left value, if it does not make it through the given filter predicate
        Returns:
        an Either instance
        Throws:
        java.lang.NullPointerException - if predicate is null

      • flatMap

        public <U> Either<L,​U> flatMap​(java.util.function.Function<? super R,​Either<L,​? extends U>> mapper)
        FlatMaps this right-biased Either.
        Type Parameters:
        U - Component type of the mapped right value
        Parameters:
        mapper - A mapper
        Returns:
        this as Either<L, U> if this is a Left, otherwise the right mapping result
        Throws:
        java.lang.NullPointerException - if mapper is null

      • fold

        public <U> U fold​(java.util.function.Function<? super L,​? extends U> ifLeft,
                  java.util.function.Function<? super R,​? extends U> ifRight)
        Folds either the left or the right side of this disjunction.
        Type Parameters:
        U - type of the folded value
        Parameters:
        ifLeft - maps the left value if this is a Left
        ifRight - maps the right value if this is a Right
        Returns:
        A value of type U

      • getLeft

        @Deprecated
public abstract L getLeft()
        Deprecated.
        Unsafe operation (but not marked for removal). Use fold(Function, Function) instead. An alternative is onLeft(Consumer).
        Gets the left value if this is a Left or throws if this is a Right.
        Returns:
        The left value.
        Throws:
        java.util.NoSuchElementException - if this is a Right.

      • getOrElse

        public R getOrElse​(R other)
        Gets the Right value or an alternate value, if the Either is a Left.
        Parameters:
        other - an alternative right value
        Returns:
        the right value, if the underlying Either is a Right or else the alternative Right value other

      • getOrElseGet

        public R getOrElseGet​(java.util.function.Function<? super L,​? extends R> other)
        Gets the Right value or an alternate value, if the Either is a Left.
        Parameters:
        other - a function which converts a Left value to an alternative Right value
        Returns:
        the right value, if the underlying Either is a Right or else the alternative Right value provided by other by applying the Left value.
        Throws:
        java.lang.NullPointerException - if other is null

      • getOrElseThrow

        public <X extends java.lang.Throwable> R getOrElseThrow​(java.util.function.Function<? super L,​X> exceptionProvider)
                                                 throws X extends java.lang.Throwable
        Gets the Right value or throws, if this Either is a Left.
        Type Parameters:
        X - a throwable type
        Parameters:
        exceptionProvider - a function which creates an exception based on a Left value
        Returns:
        the right value, if the underlying Either is a Right or else throws the exception provided by exceptionProvider by applying the Left value.
        Throws:
        X - if this Either is a Left
        X extends java.lang.Throwable

      • isLeft

        public abstract boolean isLeft()
        Returns whether this Either is a Left.
        Returns:
        true, if this is a Left, false otherwise

      • isRight

        public abstract boolean isRight()
        Returns whether this Either is a Right.
        Returns:
        true, if this is a Right, false otherwise

      • iterator

        public Iterator<R> 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<L>
        Specified by:
        iterator in interface java.lang.Iterable<L>
        Returns:
        an Iterator instance. It is not necessarily a new instance, like that returned by Iterator.empty().

      • map

        public <U> Either<L,​U> map​(java.util.function.Function<? super R,​? extends U> mapper)
        Maps the value of this Either if it is a Right, performs no operation if this is a Left. 
        
 // = Right("A")
 Either.right("a").map(String::toUpperCase);

 // = Left(1)
 Either.left(1).map(String::toUpperCase);
        Type Parameters:
        U - Component type of the mapped right value
        Parameters:
        mapper - A mapper
        Returns:
        a mapped Monad
        Throws:
        java.lang.NullPointerException - if mapper is null

      • mapLeft

        public <U> Either<U,​R> mapLeft​(java.util.function.Function<? super L,​? extends U> mapper)
        Maps the value of this Either if it is a Left, performs no operation if this is a Right. 
        
 // = Left(2)
 Either.left(1).mapLeft(i -> i + 1);

 // = Right("a")
 Either.right("a").mapLeft(i -> i + 1);
        Type Parameters:
        U - Component type of the mapped right value
        Parameters:
        mapper - A mapper
        Returns:
        a mapped Monad
        Throws:
        java.lang.NullPointerException - if mapper is null

      • onLeft

        public Either<L,​R> onLeft​(java.util.function.Consumer<? super L> action)
        Applies an action to this left value if this is a Left, otherwise nothing happens.
        Parameters:
        action - An action that takes a left value and performs a side-effect
        Returns:
        this Either
        Throws:
        java.lang.NullPointerException - if the given action is null

      • onRight

        public Either<L,​R> onRight​(java.util.function.Consumer<? super R> action)
        Applies an action to this right value if this is a Right, otherwise nothing happens.
        Parameters:
        action - An action that takes a right value and performs a side-effect
        Returns:
        this Either
        Throws:
        java.lang.NullPointerException - if the given action is null

      • orElse

        public Either<L,​R> orElse​(java.util.function.Supplier<Either<? extends L,​? extends R>> supplier)

      • stream

        public java.util.stream.Stream<R> stream()
        Converts this Either to a Stream.
        Returns:
        Stream.of(get() if this is a Right, otherwise Stream.empty()

      • swap

        public Either<R,​L> swap()
        Converts a Left to a Right vice versa by wrapping the value in a new type.
        Returns:
        a new Either

      • toOption

        public Option<R> toOption()
        Converts this Either to an Option.
        Returns:
        Option.some(get() if this is a Right, otherwise Option.none()

      • toOptional

        public java.util.Optional<R> toOptional()
        Converts this Either to an Optional.
        Returns:
        Optional.ofNullable(get()) if this is a Right, otherwise Optional.empty()

      • toTry

        public Try<R> toTry​(java.util.function.Function<? super L,​? extends java.lang.Throwable> leftMapper)
        Converts this Either to a Try.
        Parameters:
        leftMapper - a function that maps a left value to a Throwable
        Returns:
        Try.success(get() if this is a Right, otherwise Try.failure(leftMapper.apply(getLeft())
        Throws:
        java.lang.NullPointerException - if the given leftMapper is null

      • transform

        public <U> Either<L,​U> transform​(java.util.function.Function<? super L,​? extends Either<L,​? extends U>> ifLeft,
                                       java.util.function.Function<? super R,​? extends Either<L,​? extends U>> ifRight)
        Transforms this Either by applying either ifRight to this right value or ifLeft to this left value.
        Type Parameters:
        U - type of the transformed right value
        Parameters:
        ifLeft - maps the left value if this is a Left
        ifRight - maps the right value if this is a Right
        Returns:
        A new Either instance
        Throws:
        java.lang.NullPointerException - if one of the given ifRight or ifLeft is null

      • equals

        public abstract boolean equals​(java.lang.Object that)
        Checks if this Either 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 Right and the underlying values are equal or if this and that both are a Left and the underlying values are equal. Otherwise it returns false.

      • hashCode

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

      • toString

        public abstract java.lang.String toString()
        Returns a string representation of this Either.
        Overrides:
        toString in class java.lang.Object
        Returns:
        "Right(" + get() + ")" if this is a Right, otherwise "Left(" + getLeft() + ")"