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>, Value<R>, java.io.Serializable, java.lang.Iterable<R>
    Direct Known Subclasses:
    Either.Left, Either.Right
    public abstract class Either<L,​R>
extends java.lang.Object
implements Iterable<R>, Value<R>, java.io.Serializable
    Either represents a value of two possible types. An Either is either a Either.Left or a Either.Right.

    If the given Either is a Right and projected to a Left, the Left operations have no effect on the Right value.
    If the given Either is a Left and projected to a Right, the Right operations have no effect on the Left value.
    If a Left is projected to a Left or a Right is projected to a Right, the operations have an effect.

    Example: A compute() function, which results either in an Integer value (in the case of success) or in an error message of type String (in the case of failure). By convention the success case is Right and the failure is Left. 

     
 Either<String,Integer> value = compute().right().map(i -> i * 2).toEither();
    If the result of compute() is Right(1), the value is Right(2).
    If the result of compute() is Left("error"), the value is Left("error").
    See Also:
    Serialized Form

    • Method Detail

      • right

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

      • left

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

      • narrow

        public static <L,​R> Either<L,​R> narrow​(Either<? extends L,​? extends R> either)
        Narrows a widened Either<? extends L, ? extends R> to Either<L, R> by performing a type-safe cast. This is eligible because immutable/read-only collections are covariant.
        Type Parameters:
        L - Type of left value.
        R - Type of right value.
        Parameters:
        either - A Either.
        Returns:
        the given either instance as narrowed type Either<L, R>.

      • getLeft

        public abstract L getLeft()
        Returns the left value.
        Returns:
        The left value.
        Throws:
        java.util.NoSuchElementException - if this is a Right.

      • 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

      • left

        @Deprecated
public final Either.LeftProjection<L,​R> left()
        Deprecated.
        Either is right-biased. Use swap() instead of projections.
        Returns a LeftProjection of this Either.
        Returns:
        a new LeftProjection of this

      • right

        @Deprecated
public final Either.RightProjection<L,​R> right()
        Deprecated.
        Either is right-biased. Use swap() instead of projections.
        Returns a RightProjection of this Either.
        Returns:
        a new RightProjection of this

      • bimap

        public final <X,​Y> Either<X,​Y> bimap​(java.util.function.Function<? super L,​? extends X> leftMapper,
                                                 java.util.function.Function<? super R,​? extends Y> rightMapper)
        Maps either the left or the right side of this disjunction.
        Type Parameters:
        X - The new left type of the resulting Either
        Y - The new right type of the resulting Either
        Parameters:
        leftMapper - maps the left value if this is a Left
        rightMapper - maps the right value if this is a Right
        Returns:
        A new Either instance

      • fold

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

      • sequence

        public static <L,​R> Either<Seq<L>,​Seq<R>> sequence​(java.lang.Iterable<? extends Either<? extends L,​? extends R>> eithers)
        Reduces many Eithers into a single Either by transforming an Iterable<Either<L, R>> into a Either<Seq<L>, Seq<R>>.

        If any of the given Eithers is a Either.Left then sequence returns a Either.Left containing a non-empty Seq of all left values.

        If none of the given Eithers is a Either.Left then sequence returns a Either.Right containing a (possibly empty) Seq of all right values. 

        
 // = Right(Seq())
 Either.sequence(List.empty())

 // = Right(Seq(1, 2))
 Either.sequence(List.of(Either.right(1), Either.right(2)))

 // = Left(Seq("x"))
 Either.sequence(List.of(Either.right(1), Either.left("x")))
        Type Parameters:
        L - closure of all left types of the given Eithers
        R - closure of all right types of the given Eithers
        Parameters:
        eithers - An Iterable of Eithers
        Returns:
        An Either of a Seq of left or right values
        Throws:
        java.lang.NullPointerException - if eithers is null

      • traverse

        public static <L,​R,​T> Either<Seq<L>,​Seq<R>> traverse​(java.lang.Iterable<? extends T> values,
                                                                       java.util.function.Function<? super T,​? extends Either<? extends L,​? extends R>> mapper)
        Maps the values of an iterable to a sequence of mapped values into a single Either by transforming an Iterable<? extends T> into a Either<Seq<U>>.

        Type Parameters:
        L - The mapped left value type.
        R - The mapped right value type.
        T - The type of the given values.
        Parameters:
        values - An Iterable of values.
        mapper - A mapper of values to Eithers
        Returns:
        A Either of a Seq of results.
        Throws:
        java.lang.NullPointerException - if values or f is null.

      • sequenceRight

        public static <L,​R> Either<L,​Seq<R>> sequenceRight​(java.lang.Iterable<? extends Either<? extends L,​? extends R>> eithers)
        Reduces many Eithers into a single Either by transforming an Iterable<Either<L, R>> into a Either<L, Seq<R>>.

        If any of the given Eithers is a Either.Left then sequenceRight returns a Either.Left containing the first left value (in iteration order).

        If none of the given Eithers is a Either.Left then sequenceRight returns a Either.Right containing a (possibly empty) Seq of all right values. 

        
 // = Right(Seq())
 Either.sequenceRight(List.empty())

 // = Right(Seq(1, 2))
 Either.sequenceRight(List.of(Either.right(1), Either.right(2)))

 // = Left("x1")
 Either.sequenceRight(List.of(Either.right(1), Either.left("x1"), Either.left("x2")))
        Type Parameters:
        L - closure of all left types of the given Eithers
        R - closure of all right types of the given Eithers
        Parameters:
        eithers - An Iterable of Eithers
        Returns:
        An Either of either a Seq of right values or the first left value, if present.
        Throws:
        java.lang.NullPointerException - if eithers is null

      • traverseRight

        public static <L,​R,​T> Either<L,​Seq<R>> traverseRight​(java.lang.Iterable<? extends T> values,
                                                                       java.util.function.Function<? super T,​? extends Either<? extends L,​? extends R>> mapper)
        Maps the values of an iterable to a sequence of mapped values into a single Either by transforming an Iterable<? extends T> into a Either<Seq<U>>.

        Type Parameters:
        L - The mapped left value type.
        R - The mapped right value type.
        T - The type of the given values.
        Parameters:
        values - An Iterable of values.
        mapper - A mapper of values to Eithers
        Returns:
        A Either of a Seq of results.
        Throws:
        java.lang.NullPointerException - if values or f is null.

      • getOrElseGet

        public final R getOrElseGet​(java.util.function.Function<? super L,​? extends R> other)
        Gets the Right value or an alternate value, if the projected 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.

      • orElseRun

        public final void orElseRun​(java.util.function.Consumer<? super L> action)
        Runs an action in the case this is a projection on a Left value.
        Parameters:
        action - an action which consumes a Left value

      • getOrElseThrow

        public final <X extends java.lang.Throwable> R getOrElseThrow​(java.util.function.Function<? super L,​X> exceptionFunction)
                                                       throws X extends java.lang.Throwable
        Gets the Right value or throws, if the projected Either is a Left.
        Type Parameters:
        X - a throwable type
        Parameters:
        exceptionFunction - 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 exceptionFunction by applying the Left value.
        Throws:
        X - if the projected Either is a Left
        X extends java.lang.Throwable

      • swap

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

      • flatMap

        public final <U> Either<L,​U> flatMap​(java.util.function.Function<? super R,​? extends 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

      • map

        public final <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. 
        
 import static io.vavr.API.*;

 // = Right("A")
 Right("a").map(String::toUpperCase);

 // = Left(1)
 Left(1).map(String::toUpperCase);
        Specified by:
        map in interface Value<L>
        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 final <U> Either<U,​R> mapLeft​(java.util.function.Function<? super L,​? extends U> leftMapper)
        Maps the value of this Either if it is a Left, performs no operation if this is a Right. 
        
 import static io.vavr.API.*;

 // = Left(2)
 Left(1).mapLeft(i -> i + 1);

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

      • filter

        public final Option<Either<L,​R>> filter​(java.util.function.Predicate<? super R> predicate)
        Filters this right-biased Either by testing a predicate.

        Parameters:
        predicate - A predicate
        Returns:
        a new Option instance
        Throws:
        java.lang.NullPointerException - if predicate is null

      • filterNot

        public final Option<Either<L,​R>> filterNot​(java.util.function.Predicate<? super R> predicate)
        Filters this right-biased Either by testing a predicate.
        Parameters:
        predicate - A predicate
        Returns:
        a new Either
        Throws:
        java.lang.NullPointerException - if predicate is null

      • filterOrElse

        public final 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. 
        
 import static io.vavr.API.*;

 // = Left("bad: a")
 Right("a").filterOrElse(i -> false, val -> "bad: " + val);

 // = Right("a")
 Right("a").filterOrElse(i -> true, val -> "bad: " + val);
        Parameters:
        predicate - A predicate
        zero - A function that turns a right value into a left value if the right value does not make it through the filter.
        Returns:
        an Either instance
        Throws:
        java.lang.NullPointerException - if predicate is null

      • get

        public abstract R get()
        Gets the right value if this is a Right or throws if this is a Left.
        Specified by:
        get in interface Value<L>
        Returns:
        the right value
        Throws:
        java.util.NoSuchElementException - if this is a Left.

      • isEmpty

        public final boolean isEmpty()
        Description copied from interface: Value
        Checks, this Value is empty, i.e. if the underlying value is absent.
        Specified by:
        isEmpty in interface Value<L>
        Returns:
        false, if no underlying value is present, true otherwise.

      • orElse

        public final Either<L,​R> orElse​(Either<? extends L,​? extends R> other)

      • orElse

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

      • isAsync

        public final boolean isAsync()
        A right-biased Either's value is computed synchronously.
        Specified by:
        isAsync in interface Value<L>
        Returns:
        false

      • isLazy

        public final boolean isLazy()
        A right-biased Either's value is computed eagerly.
        Specified by:
        isLazy in interface Value<L>
        Returns:
        false

      • isSingleValued

        public final boolean isSingleValued()
        A right-biased Either is single-valued.
        Specified by:
        isSingleValued in interface Value<L>
        Returns:
        true

      • iterator

        public final Iterator<R> iterator()
        Description copied from interface: Iterable
        Returns a rich 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>
        Specified by:
        iterator in interface Value<L>
        Returns:
        an Iterator instance (that might be a singleton in the empty case)

      • peek

        public final Either<L,​R> peek​(java.util.function.Consumer<? super R> action)
        Description copied from interface: Value
        Performs the given action on the first element if this is an eager implementation. Performs the given action on all elements (the first immediately, successive deferred), if this is a lazy implementation.
        Specified by:
        peek in interface Value<L>
        Parameters:
        action - The action that will be performed on the element(s).
        Returns:
        this instance

      • peekLeft

        public final Either<L,​R> peekLeft​(java.util.function.Consumer<? super L> action)

      • toValidation

        public final Validation<L,​R> toValidation()
        Returns this as Validation.
        Returns:
        Validation.valid(get()) if this is right, otherwise Validation.invalid(getLeft()).