Package io.atlassian.fugue

Class Eithers

java.lang.Object

io.atlassian.fugue.Eithers

public class Eithers
extends java.lang.Object

Utility functions for Eithers.

Since:

1.2

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Eithers()

Method Summary

Modifier and Type	Method	Description
static <L,R> Either<L,R>	cond(boolean predicate, L left, R right)	Creates an Either based on a boolean expression.
static <L,R> java.lang.Iterable<L>	filterLeft(java.lang.Iterable<Either<L,R>> it)	Takes an Iterable of eithers, and collects the left values of every either which has a left value
static <L,R> java.lang.Iterable<R>	filterRight(java.lang.Iterable<Either<L,R>> it)	Takes an Iterable of eithers, and collects the right values of every either which has a left value
static <X extends java.lang.Exception,A> A	getOrThrow(Either<X,A> either)	Simplifies extracting a value or throwing a checked exception from an Either.
static <L,R> java.util.function.Predicate<Either<L,R>>	isLeft()	A predicate that tests if the supplied either is a left.
static <L,R> java.util.function.Predicate<Either<L,R>>	isRight()	A predicate that tests if the supplied either is a right.
static <L,R> java.util.function.Function<Either<L,R>,Option<L>>	leftMapper()	A function that maps an either to an option of its left type.
static <T> T	merge(Either<T,T> either)	Extracts an object from an Either, regardless of the side in which it is stored, provided both sides contain the same type.
static <L,R> java.util.function.Function<Either<L,R>,Option<R>>	rightMapper()	A function that maps an either to an option of its right type.
static <L,R> Either<java.lang.Iterable<L>,R>	sequenceLeft(java.lang.Iterable<Either<L,R>> eithers)	Collect the left values if there are only lefts, otherwise return the first right encountered.
static <L,R,A,C> Either<C,R>	sequenceLeft(java.lang.Iterable<Either<L,R>> eithers, java.util.stream.Collector<L,A,C> collector)	Collect the left values if there are only lefts, otherwise return the first right encountered.
static <L,R> Either<L,java.lang.Iterable<R>>	sequenceRight(java.lang.Iterable<Either<L,R>> eithers)	Collect the right values if there are only rights, otherwise return the first left encountered.
static <L,R,A,C> Either<L,C>	sequenceRight(java.lang.Iterable<Either<L,R>> eithers, java.util.stream.Collector<R,A,C> collector)	Collect the right values if there are only rights, otherwise return the first left encountered.
static <L,R> java.util.function.Function<L,Either<L,R>>	toLeft()	Function to convert from an value to a Either.Left containing that value.
static <L,R> java.util.function.Function<L,Either<L,R>>	toLeft(java.lang.Class<L> leftType, java.lang.Class<R> rightType)	Function to convert from a value to a Either.Left containing that value.
static <L,R> java.util.function.Supplier<Either<L,R>>	toLeft(L l)	Supplier returning a Either.Left.
static <L,R> java.util.function.Supplier<Either<L,R>>	toLeft(L l, java.lang.Class<R> rightType)	Supplier returning a Either.Left.
static <L,R> java.util.function.Function<R,Either<L,R>>	toRight()	Function to convert from an value to a Either.Right.
static <L,R> java.util.function.Function<R,Either<L,R>>	toRight(java.lang.Class<L> leftType, java.lang.Class<R> rightType)	Function to convert from a value to a Either.Right containing that value.
static <L,R> java.util.function.Supplier<Either<L,R>>	toRight(java.lang.Class<L> leftType, R r)	Supplier returning a Either.Right.
static <L,R> java.util.function.Supplier<Either<L,R>>	toRight(R r)	Supplier returning a Either.Right.
static <LL,L extends LL,R> Either<LL,R>	upcastLeft(Either<L,R> e)	Upcasts an either of left type L to an either of left type LL, which is a super type of L, keeping the right type unchanged.
static <L,RR,R extends RR> Either<L,RR>	upcastRight(Either<L,R> e)	Upcasts an either of right type R to an either of right type RR, which is a super type of R, keeping the left type unchanged.

Methods inherited from class java.lang.Object

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

Constructor Detail

Eithers

private Eithers()

Method Detail

merge

public static <T> T merge(Either<T,T> either)

Extracts an object from an Either, regardless of the side in which it is stored, provided both sides contain the same type. This method will never return null.

Type Parameters:

T - the type for both the LHS and the RHS

Parameters:

either - use whichever side holds the value to return

Returns:

the value from whichever side holds it

cond

public static <L,R> Either<L,R> cond(boolean predicate,
                                                 L left,
                                                 R right)

Creates an Either based on a boolean expression. If predicate is true, a Right will be returned containing the supplied right value; if it is false, a Left will be returned containing the supplied left value.

Type Parameters:

L - the LHS type

R - the RHS type

Parameters:

predicate - if predicate is true, a Right will be returned if it is false, a Left will be returned containing the supplied left value.

left - the LHS value

right - the RHS value

Returns:

an either with the appropriately selected value

getOrThrow

public static <X extends java.lang.Exception,A> A getOrThrow(Either<X,A> either)
                                                            throws X extends java.lang.Exception

Simplifies extracting a value or throwing a checked exception from an Either.

Type Parameters:

A - the value type

X - the exception type

Parameters:

either - to extract from

Returns:

the value from the RHS

Throws:

X - the exception on the LHS

X extends java.lang.Exception

isLeft

public static <L,R> java.util.function.Predicate<Either<L,R>> isLeft()

A predicate that tests if the supplied either is a left.

Type Parameters:

L - the LHS type

R - the RHS type

Returns:

the predicate testing left-hand-sidedness

isRight

public static <L,R> java.util.function.Predicate<Either<L,R>> isRight()

A predicate that tests if the supplied either is a right.

Type Parameters:

L - the LHS type

R - the RHS type

Returns:

the predicate testing right-hand-sidedness

leftMapper

public static <L,R> java.util.function.Function<Either<L,R>,Option<L>> leftMapper()

A function that maps an either to an option of its left type. The Function will return a defined Option containing the either's left value if {Either#isLeft()} is true, an undefined Option otherwise.

Type Parameters:

L - the LHS type

R - the RHS type

Returns:

the function returning a defined option for left-hand-sided eithers

rightMapper

public static <L,R> java.util.function.Function<Either<L,R>,Option<R>> rightMapper()

A function that maps an either to an option of its right type. The Function will return a defined Option containing the either's right value if {Either#isRight()} is true, an undefined Option otherwise.

Type Parameters:

L - the LHS type

R - the RHS type

Returns:

the function returning a defined option for right-hand-sided eithers

toLeft

public static <L,R> java.util.function.Function<L,Either<L,R>> toLeft()

Function to convert from an value to a Either.Left containing that value.

Type Parameters:

L - left type.

R - right type.

Returns:

a Function returning a Either.Left.

toLeft

public static <L,R> java.util.function.Function<L,Either<L,R>> toLeft(java.lang.Class<L> leftType,
                                                                                        java.lang.Class<R> rightType)

Function to convert from a value to a Either.Left containing that value. Allows hinting the correct types.

Type Parameters:

L - left type.

R - right type.

Parameters:

leftType - expected left type.

rightType - expected right type.

Returns:

a Function returning a Either.Left.

toLeft

public static <L,R> java.util.function.Supplier<Either<L,R>> toLeft(L l)

Supplier returning a Either.Left.

Type Parameters:

L - left type.

R - right type.

Parameters:

l - value to return inside the left.

Returns:

a Supplier returning a Either.Left..

toLeft

public static <L,R> java.util.function.Supplier<Either<L,R>> toLeft(L l,
                                                                                java.lang.Class<R> rightType)

Supplier returning a Either.Left. Allows hinting the correct right type.

Type Parameters:

L - left type.

R - right type.

Parameters:

l - value to return inside the left.

rightType - type hint for the right type of the either.

Returns:

a Supplier returning a Either.Left.

toRight

public static <L,R> java.util.function.Function<R,Either<L,R>> toRight()

Function to convert from an value to a Either.Right. Allows hinting the correct types.

Type Parameters:

L - left type.

R - right type.

Returns:

a Function returning a Either.Right.

toRight

public static <L,R> java.util.function.Function<R,Either<L,R>> toRight(java.lang.Class<L> leftType,
                                                                                         java.lang.Class<R> rightType)

Function to convert from a value to a Either.Right containing that value. Allows hinting the correct types.

Type Parameters:

L - left type.

R - right type.

Parameters:

leftType - expected left type.

rightType - expected right type.

Returns:

a Function returning a Either.Right.

toRight

public static <L,R> java.util.function.Supplier<Either<L,R>> toRight(R r)

Supplier returning a Either.Right.

Type Parameters:

L - left type.

R - right type.

Parameters:

r - value to return inside the right.

Returns:

a Supplier returning a Either.Right..

toRight

public static <L,R> java.util.function.Supplier<Either<L,R>> toRight(java.lang.Class<L> leftType,
                                                                                 R r)

Supplier returning a Either.Right. Allows hinting the correct right type.

Type Parameters:

L - left type.

R - right type.

Parameters:

r - value to return inside the right.

leftType - type hint for the left type of the either.

Returns:

a Supplier returning a Either.Right.

upcastLeft

public static <LL,L extends LL,R> Either<LL,R> upcastLeft(Either<L,R> e)

Upcasts an either of left type L to an either of left type LL, which is a super type of L, keeping the right type unchanged.

Type Parameters:

L - the base type to upcast

LL - the super type of the contained left type

R - the contained right type

Parameters:

e - the source either

Returns:

an either of left type LL and right type R

Since:

2.0

upcastRight

public static <L,RR,R extends RR> Either<L,RR> upcastRight(Either<L,R> e)

Upcasts an either of right type R to an either of right type RR, which is a super type of R, keeping the left type unchanged.

Type Parameters:

L - the contained left type

R - the base type to upcast

RR - the super type of the contained right type

Parameters:

e - the source either

Returns:

an either of left type L and right type RR

Since:

2.0

filterLeft

public static <L,R> java.lang.Iterable<L> filterLeft(java.lang.Iterable<Either<L,R>> it)

Takes an Iterable of eithers, and collects the left values of every either which has a left value

Type Parameters:

L - the LHS type

R - the RHS type

Parameters:

it - iterable of eithers to filter and transform from

Returns:

the left values contained in the contents of it

filterRight

public static <L,R> java.lang.Iterable<R> filterRight(java.lang.Iterable<Either<L,R>> it)

Takes an Iterable of eithers, and collects the right values of every either which has a left value

Type Parameters:

L - the LHS type

R - the RHS type

Parameters:

it - iterable of eithers to filter and transform from

Returns:

the right values contained in the contents of it

sequenceRight

public static <L,R> Either<L,java.lang.Iterable<R>> sequenceRight(java.lang.Iterable<Either<L,R>> eithers)

Collect the right values if there are only rights, otherwise return the first left encountered.

Type Parameters:

L - the LHS type

R - the RHS type

Parameters:

eithers - an Iterable of either values

Returns:

either the iterable of right values, or the first left encountered.

sequenceRight

public static <L,R,A,C> Either<L,C> sequenceRight(java.lang.Iterable<Either<L,R>> eithers,
                                                                          java.util.stream.Collector<R,A,C> collector)

Collect the right values if there are only rights, otherwise return the first left encountered.

Type Parameters:

L - the LHS type

R - the RHS type

A - The intermediate accumulator type

C - The result type

Parameters:

eithers - an Iterable of either values

collector - result collector

Returns:

either the iterable of right values, or the first left encountered.

Since:

4.6.0

sequenceLeft

public static <L,R> Either<java.lang.Iterable<L>,R> sequenceLeft(java.lang.Iterable<Either<L,R>> eithers)

Collect the left values if there are only lefts, otherwise return the first right encountered.

Type Parameters:

L - the LHS type

R - the RHS type

Parameters:

eithers - an Iterable of either values

Returns:

either the iterable of left values, or the first right encountered.

sequenceLeft

public static <L,R,A,C> Either<C,R> sequenceLeft(java.lang.Iterable<Either<L,R>> eithers,
                                                                         java.util.stream.Collector<L,A,C> collector)

Collect the left values if there are only lefts, otherwise return the first right encountered.

Type Parameters:

L - the LHS type

R - the RHS type

A - The intermediate accumulator type

C - The result type

Parameters:

eithers - an Iterable of either values

collector - result collector

Returns:

either the iterable of left values, or the first right encountered.

Since:

4.6.0