Package io.vavr.control

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:
Iterable<R>, Serializable, Value<R>
All Known Implementing Classes:
Either.Left, Either.Right
public interface Either<L,R> extends Value<R>, 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").
Author:
Daniel Dietrich

  • Field Details

  • Method Details

    • 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:
      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(Function<? super L,? extends X> leftMapper, 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(Function<? super L,? extends U> leftMapper, 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(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:
      NullPointerException - if eithers is null

    • traverse

      static <L, R, T> Either<Seq<L>,Seq<R>> traverse(Iterable<? extends T> values, 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:
      NullPointerException - if values or f is null.

    • sequenceRight

      static <L, R> Either<L,Seq<R>> sequenceRight(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:
      NullPointerException - if eithers is null

    • traverseRight

      static <L, R, T> Either<L,Seq<R>> traverseRight(Iterable<? extends T> values, 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:
      NullPointerException - if values or f is null.

    • getOrElseGet

      default R getOrElseGet(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(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 Throwable> R getOrElseThrow(Function<? super L,X> exceptionFunction) throws X
      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

    • 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(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:
      NullPointerException - if mapper is null

    • map

      default <U> Either<L,U> map(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:
      NullPointerException - if mapper is null

    • mapLeft

      default <U> Either<U,R> mapLeft(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:
      NullPointerException - if mapper is null

    • filter

      default Option<Either<L,R>> filter(Predicate<? super R> predicate)
      Filters this right-biased Either by testing a predicate.

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

    • filterOrElse

      default Either<L,R> filterOrElse(Predicate<? super R> predicate, 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:
      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:
      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(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 Iterable<L>
      Specified by:
      iterator in interface Value<L>
      Returns:
      A new Iterator

    • peek

      default Either<L,R> peek(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(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(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 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 Object
      Returns:
      The hashcode of this object

    • toString

      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 Object
      Returns:
      A String representation of this object