Either (Functional Extensions Library 4.5.1 API)

java.lang.Object
- io.atlassian.fugue.Either<L,R>

All Implemented Interfaces:

Serializable
```
public abstract class Either<L,R>
extends Object
implements 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

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`Either.LeftProjection` A left projection of an either value.
`static interface`	`Either.Projection<A,B,L,R>`
`class`	`Either.RightProjection` A right projection of an either value.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`<X> Either<L,X>`	`ap(Either<L,Function<R,X>> either)` Function application on this projection's value.
`<X> Either<L,X>`	`apply(Either<L,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(Function<? super L,? extends LL> ifLeft, Function<? super R,? extends RR> ifRight)` Map the given functions across the appropriate side.
`boolean`	`exists(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(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`.
`<X,LL extends L> Either<L,X>`	`flatMap(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(Function<? super L,V> ifLeft, 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(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(Consumer<? super R> effect)` Perform the given side-effect for the contained element if it is a right
`void`	`foreach(Effect<? super R> effect)` Deprecated. use `forEach(Consumer)` instead
`R`	`getOr(Supplier<? extends R> supplier)` Get the value if it is a right or call the supplier and return its value if not.
`R`	`getOrElse(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(Supplier<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 Throwable> R`	`getOrThrow(Supplier<X> ifUndefined)` Get the contained value or throws the supplied throwable if left
`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(Function<? super L,X> f)` Map the given function across the left hand side value if it is one.
`L`	`leftOr(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(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(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(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.
`Optional<R>`	`toOptional()` Convert this Either to an `Optional`.
`Stream<R>`	`toStream()` Convert this Either to a `Stream`.
`R`	`valueOr(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

- 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(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(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(Supplier<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 Throwable> R getOrThrow(Supplier<X> ifUndefined)
                                         throws X extends 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 Throwable
    
    Since:
    
    2.3
  - map
```
public final <X> Either<L,X> map(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(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(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(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
  - 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(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(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(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(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(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(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
  - toOptional
```
public final 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 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,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,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(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(Function<? super L,V> ifLeft,
                           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(Function<? super L,? extends LL> ifLeft,
                                            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

Class Either<L,R>

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

left

right

left

right

getOr

getOrElse

getOrElse

getOrNull

getOrError

getOrThrow

map

flatMap

exists

forall

foreach

forEach

orElse

orElse

valueOr

rightOr

leftOr

filter

toOptional

toOption

toStream

sequence

apply

ap

leftMap

isLeft

isRight

swap

fold

bimap