Interface 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 Superinterfaces:
    java.lang.Iterable<R>, java.io.Serializable, Value<R>
    All Known Implementing Classes:
    Either.Left, Either.Right

    public interface Either<L,​R>
    extends 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").
    • Method Detail

      • right

        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

        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

        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

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

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

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

        @Deprecated
        default 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
        default 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

        default <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

        default <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

        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

        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

        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

        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

        default 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

        default 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

        default <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

        default 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

        default <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

        default <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

        default <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

        default 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
      • filterOrElse

        default 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 zero 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

        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

        default 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

        default Either<L,​R> orElse​(Either<? extends L,​? extends R> other)
      • orElse

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

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

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

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

        default Iterator<R> iterator()
        Description copied from interface: Value
        Returns a rich io.vavr.collection.Iterator.
        Specified by:
        iterator in interface java.lang.Iterable<L>
        Specified by:
        iterator in interface Value<L>
        Returns:
        A new Iterator
      • peek

        default 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

        default Either<L,​R> peekLeft​(java.util.function.Consumer<? super L> action)
      • toValidation

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

        boolean equals​(java.lang.Object o)
        Description copied from interface: Value
        Clarifies that values have a proper equals() method implemented.

        See Object.equals(Object).

        Specified by:
        equals in interface Value<L>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - An object
        Returns:
        true, if this equals o, false otherwise
      • hashCode

        int hashCode()
        Description copied from interface: Value
        Clarifies that values have a proper hashCode() method implemented.

        See Object.hashCode().

        Specified by:
        hashCode in interface Value<L>
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        The hashcode of this object
      • toString

        java.lang.String toString()
        Description copied from interface: Value
        Clarifies that values have a proper toString() method implemented.

        See Object.toString().

        Specified by:
        toString in interface Value<L>
        Overrides:
        toString in class java.lang.Object
        Returns:
        A String representation of this object