Package io.atlassian.fugue

Class Either<L,​R>

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    Either.Left, Either.Right
    public abstract class Either<L,​R>
extends java.lang.Object
implements java.io.Serializable
    A class that acts as a container for a value of one of two types. An Either will be either Left or Right.

    Checking which type an Either is can be done by calling the @ isLeft() and isRight() methods.

    An Either can be used to express a success or failure case. By convention, Right is used to store the success value, (you can use the play on words "right" == "correct" as a mnemonic) and Left is used to store failure values (such as exceptions).

    While this class is public and abstract it does not expose a constructor as only the concrete Left and Right subclasses are meant to be used.

    Either is immutable, but does not force immutability on contained objects; if the contained objects are mutable then equals and hashcode methods should not be relied on.

    Since 2.2, there have been some right-biased methods added. With 2.3 the available right-biased methods has increased. The purpose of these is that you can do something like either.map(...) directly, which is identical to calling either.right().map(...).

    Since:
    1.0
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static long serialVersionUID  

    • Constructor Summary

      Constructors 
      Constructor Description
      Either()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      <X> Either<L,​X> ap​(Either<L,​java.util.function.Function<R,​X>> either)
      Function application on this projection's value.
      <X> Either<L,​X> apply​(Either<L,​java.util.function.Function<R,​X>> either)
      Deprecated.
      since 3.0 see ap(io.atlassian.fugue.Either<L, java.util.function.Function<R, X>>)
      abstract <LL,​RR>
      Either<LL,​RR>      		 bimap​(java.util.function.Function<? super L,​? extends LL> ifLeft, java.util.function.Function<? super R,​? extends RR> ifRight)
      Map the given functions across the appropriate side.
      boolean contains​(R elem)
      Tests whether the option contains a given value as an element.
      boolean exists​(java.util.function.Predicate<? super R> p)
      Return `true` if this is a right value and applying the predicate to the contained value returns true.
      Option<Either<L,​R>> filter​(java.util.function.Predicate<? super R> p)
      Returns None if this is a left or if the given predicate p does not hold for the contained value, otherwise, returns a right in Some.
      Either<L,​R> filterOrElse​(java.util.function.Predicate<? super R> p, java.util.function.Supplier<? extends L> orElseSupplier)
      Return a Right if this is a Right and the contained values satisfies the given predicate.
      <X,​LL extends L>
      Either<L,​X>      		 flatMap​(java.util.function.Function<? super R,​Either<LL,​X>> f)
      Binds the given function across the right hand side value if it is one.
      abstract <V> V fold​(java.util.function.Function<? super L,​V> ifLeft, java.util.function.Function<? super R,​V> ifRight)
      Applies the function to the wrapped value, applying ifLeft if this is a Left and ifRight if this is a Right.
      boolean forall​(java.util.function.Predicate<? super R> p)
      Returns true if it is a left or the result of the application of the given predicate on the contained value.
      void foreach​(Effect<? super R> effect)
      Deprecated.
      use forEach(Consumer) instead
      void forEach​(java.util.function.Consumer<? super R> effect)
      Perform the given side-effect for the contained element if it is a right
      (package private) L getLeft()  
      R getOr​(java.util.function.Supplier<? extends R> supplier)
      Get the value if it is a right or call the supplier and return its value if not.
      R getOrElse​(java.util.function.Supplier<? extends R> supplier)
      Deprecated.
      since 4.3, use getOr(Supplier) instead
      <X extends R>
      R      		 getOrElse​(X other)
      Get the value if it is a right, otherwise returns other.
      R getOrError​(java.util.function.Supplier<java.lang.String> msg)
      Get the contained value or throws an error with the supplied message if left.
      R getOrNull()
      Get the value if it is right or null if not.
      <X extends java.lang.Throwable>
      R      		 getOrThrow​(java.util.function.Supplier<X> ifUndefined)
      Get the contained value or throws the supplied throwable if left
      (package private) R getRight()  
      abstract boolean isLeft()
      Returns true if this either is a left, false otherwise.
      abstract boolean isRight()
      Returns true if this either is a right, false otherwise.
      Either.LeftProjection left()
      Projects this either as a left.
      static <L,​R>
      Either<L,​R>      		 left​(L left)
      left.
      <X> Either<X,​R> leftMap​(java.util.function.Function<? super L,​X> f)
      Map the given function across the left hand side value if it is one.
      L leftOr​(java.util.function.Function<R,​? extends L> rightTransformer)
      If this is a left return the contained value, else return the result of applying rightTransformer on right
      <X> Either<L,​X> map​(java.util.function.Function<? super R,​X> f)
      Map the given function across the right hand side value if it is one.
      Either<L,​R> orElse​(Either<? extends L,​? extends R> orElse)
      If this is a right, return the same right.
      Either<L,​R> orElse​(java.util.function.Supplier<? extends Either<? extends L,​? extends R>> orElse)
      If this is a right, return the same right.
      Either.RightProjection right()
      Projects this either as a right.
      static <L,​R>
      Either<L,​R>      		 right​(R right)
      right.
      R rightOr​(java.util.function.Function<L,​? extends R> leftTransformer)
      If this is a right return the contained value, else return the result of applying leftTransformer on left
      <X> Either<L,​X> sequence​(Either<L,​X> e)
      Will return the supplied Either if this one is right, otherwise this one if left.
      abstract Either<R,​L> swap()
      If this is a left, then return the left value in right, or vice versa.
      Option<R> toOption()
      Convert this Either to an Option.
      java.util.Optional<R> toOptional()
      Convert this Either to an Optional.
      java.util.stream.Stream<R> toStream()
      Convert this Either to a Stream.
      R valueOr​(java.util.function.Function<L,​? extends R> or)
      Deprecated.
      In favor of rightOr

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Either

        Either()

    • Method Detail

      • left

        public static <L,​R> Either<L,​R> left​(L left)

        left.

        Type Parameters:
        L - the LHS type
        R - the RHS type
        Parameters:
        left - the value to be stored, must not be null
        Returns:
        a Left containing the supplied value
        Since:
        1.0

      • right

        public static <L,​R> Either<L,​R> right​(R right)

        right.

        Type Parameters:
        L - the LHS type
        R - the RHS type
        Parameters:
        right - the value to be stored, must not be null
        Returns:
        a Right containing the supplied value
        Since:
        1.0

      • left

        public final Either.LeftProjection left()
        Projects this either as a left.
        Returns:
        A left projection of this either.

      • right

        public final Either.RightProjection right()
        Projects this either as a right.
        Returns:
        A right projection of this either.

      • getOr

        public final R getOr​(java.util.function.Supplier<? extends R> supplier)
        Get the value if it is a right or call the supplier and return its value if not.
        Parameters:
        supplier - called if this is a left
        Returns:
        the wrapped value or the value from the Supplier
        Since:
        4.3

      • getOrElse

        @Deprecated
public final R getOrElse​(java.util.function.Supplier<? extends R> supplier)
        Deprecated.
        since 4.3, use getOr(Supplier) instead
        Get the value if it is a right or call the supplier and return its value if not.
        Parameters:
        supplier - called if this is a left
        Returns:
        the wrapped value or the value from the Supplier
        Since:
        2.3

      • getOrElse

        public final <X extends R> R getOrElse​(X other)
        Get the value if it is a right, otherwise returns other.
        Type Parameters:
        X - default type
        Parameters:
        other - value to return if this is a left
        Returns:
        wrapped value if this is a right, otherwise returns other
        Since:
        2.3

      • getOrNull

        public final R getOrNull()
        Get the value if it is right or null if not.

        Although the use of null is discouraged, code written to use these must often interface with code that expects and returns nulls.

        Returns:
        the contained value or null
        Since:
        2.3

      • getOrError

        public final R getOrError​(java.util.function.Supplier<java.lang.String> msg)
        Get the contained value or throws an error with the supplied message if left.

        Used when absolutely sure this is a right.

        Parameters:
        msg - the message for the error.
        Returns:
        the contained value.
        Since:
        2.3

      • getOrThrow

        public final <X extends java.lang.Throwable> R getOrThrow​(java.util.function.Supplier<X> ifUndefined)
                                                   throws X extends java.lang.Throwable
        Get the contained value or throws the supplied throwable if left

        Used when absolutely sure this is a right.

        Type Parameters:
        X - exception type
        Parameters:
        ifUndefined - the supplier of the throwable.
        Returns:
        the contained value.
        Throws:
        X - the throwable the supplier creates if there is no value.
        X extends java.lang.Throwable
        Since:
        2.3

      • map

        public final <X> Either<L,​X> map​(java.util.function.Function<? super R,​X> f)
        Map the given function across the right hand side value if it is one.
        Type Parameters:
        X - the RHS type
        Parameters:
        f - The function to map .
        Returns:
        A new either value after mapping with the function applied if this is a Right.
        Since:
        2.2

      • flatMap

        public final <X,​LL extends L> Either<L,​X> flatMap​(java.util.function.Function<? super R,​Either<LL,​X>> f)
        Binds the given function across the right hand side value if it is one.
        Type Parameters:
        X - the RHS type
        LL - result type
        Parameters:
        f - the function to bind.
        Returns:
        A new either value after binding with the function applied if this is a Right.
        Since:
        2.2

      • exists

        public final boolean exists​(java.util.function.Predicate<? super R> p)
        Return `true` if this is a right value and applying the predicate to the contained value returns true.
        Parameters:
        p - the predicate to test.
        Returns:
        true if right and the predicate returns true for the right value, false otherwise.
        Since:
        2.3

      • forall

        public final boolean forall​(java.util.function.Predicate<? super R> p)
        Returns true if it is a left or the result of the application of the given predicate on the contained value.
        Parameters:
        p - The predicate function to test on the contained value.
        Returns:
        true if no value or returns the result of the application of the given function to the value.
        Since:
        2.3

      • contains

        public final boolean contains​(R elem)
        Tests whether the option contains a given value as an element.
        Parameters:
        elem - the element to test
        Returns:
        true if the option has an element that is equal to elem, false otherwise
        Since:
        6.1

      • foreach

        @Deprecated
public final void foreach​(Effect<? super R> effect)
        Deprecated.
        use forEach(Consumer) instead
        Perform the given side-effect for the contained element if it is a right
        Parameters:
        effect - the input to use for performing the effect on contained value.
        Since:
        2.3

      • forEach

        public final void forEach​(java.util.function.Consumer<? super R> effect)
        Perform the given side-effect for the contained element if it is a right
        Parameters:
        effect - the input to use for performing the effect on contained value.
        Since:
        3.1

      • orElse

        public final Either<L,​R> orElse​(Either<? extends L,​? extends R> orElse)
        If this is a right, return the same right. Otherwise, return orElse .
        Parameters:
        orElse - either to return if this is left
        Returns:
        this or orElse
        Since:
        2.3

      • orElse

        public final Either<L,​R> orElse​(java.util.function.Supplier<? extends Either<? extends L,​? extends R>> orElse)
        If this is a right, return the same right. Otherwise, return value supplied by orElse.
        Parameters:
        orElse - either to return if this is left
        Returns:
        this or orElse
        Since:
        2.3

      • valueOr

        @Deprecated
public final R valueOr​(java.util.function.Function<L,​? extends R> or)
        Deprecated.
        In favor of rightOr
        If this is a right return the contained value, else return the result of running function on left
        Parameters:
        or - Function to run if this is a left
        Returns:
        contained value of R or result of or
        Since:
        2.3
        See Also:
        rightOr(Function)

      • rightOr

        public final R rightOr​(java.util.function.Function<L,​? extends R> leftTransformer)
        If this is a right return the contained value, else return the result of applying leftTransformer on left
        Parameters:
        leftTransformer - Function to run on left if this is a left
        Returns:
        contained value of right or result of leftTransformer
        Since:
        3.2

      • leftOr

        public final L leftOr​(java.util.function.Function<R,​? extends L> rightTransformer)
        If this is a left return the contained value, else return the result of applying rightTransformer on right
        Parameters:
        rightTransformer - Function to run on right if this is a right
        Returns:
        contained value of left or result of rightTransformer
        Since:
        3.2

      • filter

        public final Option<Either<L,​R>> filter​(java.util.function.Predicate<? super R> p)
        Returns None if this is a left or if the given predicate p does not hold for the contained value, otherwise, returns a right in Some.
        Parameters:
        p - The predicate function to test on the right contained value.
        Returns:
        None if this is a left or if the given predicate p does not hold for the right contained value, otherwise, returns a right in Some.
        Since:
        2.3

      • filterOrElse

        public final Either<L,​R> filterOrElse​(java.util.function.Predicate<? super R> p,
                                            java.util.function.Supplier<? extends L> orElseSupplier)
        Return a Right if this is a Right and the contained values satisfies the given predicate. If this is a Right but the predicate is not satisfied, return a Left with the value provided by the orElseSupplier. Return a Left if this a Left with the contained value.
        Parameters:
        p - The predicate function to test on the right contained value.
        orElseSupplier - The supplier to execute when is a right, and predicate is unsatisfied
        Returns:
        a new Either that will be either the existing left/right or a left with result of orElseSupplier
        Since:
        4.7.0

      • toOptional

        public final java.util.Optional<R> toOptional()
        Convert this Either to an Optional. Returns with Optional.of(Object) if it is a right, otherwise Optional.empty().
        Returns:
        The right projection's value in of if it exists, otherwise empty.
        Since:
        4.0

      • toOption

        public final Option<R> toOption()
        Convert this Either to an Option. Returns Some with a value if it is a right, otherwise None.
        Returns:
        The right projection's value in Some if it exists, otherwise None.
        Since:
        2.6

      • toStream

        public final java.util.stream.Stream<R> toStream()
        Convert this Either to a Stream. Returns with Stream.of(Object) if it is a right, otherwise Stream.empty().
        Returns:
        The right projection's value in of if it exists, otherwise empty.
        Since:
        4.5.0

      • sequence

        public <X> Either<L,​X> sequence​(Either<L,​X> e)
        Will return the supplied Either if this one is right, otherwise this one if left.
        Type Parameters:
        X - the RHS type
        Parameters:
        e - The value to bind with.
        Returns:
        An either after binding through this projection.
        Since:
        2.6

      • apply

        @Deprecated
public <X> Either<L,​X> apply​(Either<L,​java.util.function.Function<R,​X>> either)
        Deprecated.
        since 3.0 see ap(io.atlassian.fugue.Either<L, java.util.function.Function<R, X>>)
        Given a right containing a function from the right type <R> to a new type <X> apply that function to the value inside this either. When any of the input values are left return that left value.
        Type Parameters:
        X - the RHS type
        Parameters:
        either - The either of the function to apply if this is a Right.
        Returns:
        The result of function application within either.
        Since:
        2.6

      • ap

        public <X> Either<L,​X> ap​(Either<L,​java.util.function.Function<R,​X>> either)
        Function application on this projection's value.
        Type Parameters:
        X - the RHS type
        Parameters:
        either - The either of the function to apply on this projection's value.
        Returns:
        The result of function application within either.
        Since:
        3.0

      • leftMap

        public final <X> Either<X,​R> leftMap​(java.util.function.Function<? super L,​X> f)
        Map the given function across the left hand side value if it is one.
        Type Parameters:
        X - the LHS type
        Parameters:
        f - The function to map.
        Returns:
        A new either value after mapping with the function applied if this is a Left.
        Since:
        2.2

      • isLeft

        public abstract boolean isLeft()
        Returns true if this either is a left, false otherwise.
        Returns:
        true if this either is a left, false otherwise.

      • isRight

        public abstract boolean isRight()
        Returns true if this either is a right, false otherwise.
        Returns:
        true if this either is a right, false otherwise.

      • swap

        public abstract Either<R,​L> swap()
        If this is a left, then return the left value in right, or vice versa.
        Returns:
        an Either that is a Left if this is a Right or a Right if this is a Left. The value remains the same.

      • fold

        public abstract <V> V fold​(java.util.function.Function<? super L,​V> ifLeft,
                           java.util.function.Function<? super R,​V> ifRight)
        Applies the function to the wrapped value, applying ifLeft if this is a Left and ifRight if this is a Right.
        Type Parameters:
        V - the destination type
        Parameters:
        ifLeft - the function to apply if this is a Left
        ifRight - the function to apply if this is a Right
        Returns:
        the result of the applies function

      • bimap

        public abstract <LL,​RR> Either<LL,​RR> bimap​(java.util.function.Function<? super L,​? extends LL> ifLeft,
                                                        java.util.function.Function<? super R,​? extends RR> ifRight)
        Map the given functions across the appropriate side.
        Type Parameters:
        LL - the LHS type
        RR - the RHS type
        Parameters:
        ifLeft - The function to map if this Either is a left.
        ifRight - The function to map if this Either is a right.
        Returns:
        A new either value after mapping with the appropriate function applied.
        Since:
        2.2

      • getLeft

        L getLeft()

      • getRight

        R getRight()