Package com.jnape.palatable.lambda.adt

Class Maybe<A>

java.lang.Object

com.jnape.palatable.lambda.adt.Maybe<A>

Type Parameters:

A - the optional parameter type

All Implemented Interfaces:

CoProduct2<Unit,A,Maybe<A>>, Applicative<A,Maybe<?>>, Functor<A,Maybe<?>>, Monad<A,Maybe<?>>, MonadError<Unit,A,Maybe<?>>, MonadRec<A,Maybe<?>>, Traversable<A,Maybe<?>>

Direct Known Subclasses:

Maybe.Just, Maybe.Nothing

public abstract class Maybe<A>
extends java.lang.Object
implements CoProduct2<Unit,A,Maybe<A>>, MonadError<Unit,A,Maybe<?>>, MonadRec<A,Maybe<?>>, Traversable<A,Maybe<?>>

The optional type, representing a potentially absent value. This is lambda's analog of Optional, supporting all the usual suspects like Functor, Applicative, Traversable, etc.

See Also:

Optional

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static class	Maybe.Just<A>
private static class	Maybe.Nothing<A>

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Maybe()

Method Summary

Modifier and Type	Method	Description
Maybe<A>	catchError(Fn1<? super Unit,? extends Monad<A,Maybe<?>>> recoveryFn)	Catch any thrown errors inside the Monad and resume normal operations.
<B> Maybe<B>	discardL(Applicative<B,Maybe<?>> appB)	Sequence both this Applicative and appB, discarding this Applicative's result and returning appB.
<B> Maybe<A>	discardR(Applicative<B,Maybe<?>> appB)	Sequence both this Applicative and appB, discarding appB's result and returning this Applicative.
<B> Choice3<Unit,A,B>	diverge()	Diverge this coproduct by introducing another possible type that it could represent.
Maybe<A>	filter(Fn1<? super A,? extends java.lang.Boolean> predicate)	If this value is present and satisfies predicate, return just the value; otherwise, return nothing.
<B> Maybe<B>	flatMap(Fn1<? super A,? extends Monad<B,Maybe<?>>> f)	Chain dependent computations that may continue or short-circuit based on previous results.
<B> Maybe<B>	fmap(Fn1<? super A,? extends B> fn)	Covariantly transmute this functor's parameter using the given mapping function.
static <A> Maybe<A>	fromEither(Either<?,A> either)	Convenience static factory method for creating a Maybe from an Either.
static <A> Maybe<A>	fromOptional(java.util.Optional<? extends A> optional)	Convenience static factory method for creating a Maybe from an Optional.
Choice2<A,Unit>	invert()	Swap the type parameters.
static <A> Maybe<A>	just(A a)	Lift a non-null value into Maybe.
<B> Lazy<Maybe<B>>	lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Maybe<?>>> lazyAppFn)	Terminate early if this is a Maybe.Nothing; otherwise, continue the zip.
static <A> Maybe<A>	maybe(A a)	Lift a potentially null value into Maybe.
static <A> Maybe<A>	nothing()	Return nothing.
A	orElse(A other)	If the value is present, return it; otherwise, return other.
A	orElseGet(Fn0<A> otherFn0)	If the value is present, return it; otherwise, return the value supplied by otherSupplier.
<E extends java.lang.Throwable> A	orElseThrow(Fn0<? extends E> throwableSupplier)	If the value is present, return it; otherwise, throw the Throwable supplied by throwableSupplier.
Maybe<A>	peek(Fn1<? super A,? extends IO<?>> effect)	Deprecated. in favor of matching into an IO and explicitly running it
Tuple2<Maybe<Unit>,Maybe<A>>	project()	Project this coproduct onto a product, such that the index in the product that corresponds to this coproduct's value is present, while the other indices are absent.
<B> Maybe<B>	pure(B b)	Lift the value into the Maybe monad
static Pure<Maybe<?>>	pureMaybe()	The canonical Pure instance for Maybe.
Maybe<A>	throwError(Unit unit)	Throw an error value of type E into the monad.
<L> Either<L,A>	toEither(Fn0<L> lFn0)	If this value is absent, return the value supplied by lSupplier wrapped in Either.left.
java.util.Optional<A>	toOptional()	Convert to Optional.
<B> Maybe<B>	trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Maybe<?>>> fn)	Given some operation yielding a RecursiveResult inside this MonadRec, internally trampoline the operation until it yields a termination instruction.
<B,App extends Applicative<?,App>,TravB extends Traversable<B,Maybe<?>>,AppTrav extends Applicative<TravB,App>> AppTrav	traverse(Fn1<? super A,? extends Applicative<B,App>> fn, Fn1<? super TravB,? extends AppTrav> pure)	Apply fn to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
<B> Maybe<B>	zip(Applicative<Fn1<? super A,? extends B>,Maybe<?>> appFn)	Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.jnape.palatable.lambda.adt.coproduct.CoProduct2

embed, match, projectA, projectB

Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

coerce

Constructor Detail

Maybe

private Maybe()

Method Detail

orElseGet

public final A orElseGet(Fn0<A> otherFn0)

If the value is present, return it; otherwise, return the value supplied by otherSupplier.

Parameters:

otherFn0 - the supplier for the other value

Returns:

this value, or the supplied other value

orElse

public final A orElse(A other)

If the value is present, return it; otherwise, return other.

Parameters:

other - the other value

Returns:

this value, or the other value

orElseThrow

public final <E extends java.lang.Throwable> A orElseThrow(Fn0<? extends E> throwableSupplier)
                                                    throws E extends java.lang.Throwable

If the value is present, return it; otherwise, throw the Throwable supplied by throwableSupplier.

Type Parameters:

E - the Throwable type

Parameters:

throwableSupplier - the supplier of the potentially thrown Throwable

Returns:

the value, if present

Throws:

E - the throwable, if the value is absent

E extends java.lang.Throwable

filter

public final Maybe<A> filter(Fn1<? super A,? extends java.lang.Boolean> predicate)

If this value is present and satisfies predicate, return just the value; otherwise, return nothing.

Parameters:

predicate - the predicate to apply to the possibly absent value

Returns:

maybe the present value that satisfied the predicate

throwError

public Maybe<A> throwError(Unit unit)

Throw an error value of type E into the monad.

Specified by:

throwError in interface MonadError<Unit,A,Maybe<?>>

Parameters:

unit - the error type

Returns:

the monad

catchError

public Maybe<A> catchError(Fn1<? super Unit,? extends Monad<A,Maybe<?>>> recoveryFn)

Catch any thrown errors inside the Monad and resume normal operations.

Specified by:

catchError in interface MonadError<Unit,A,Maybe<?>>

Parameters:

recoveryFn - the catch function

Returns:

the recovered Monad

toEither

public final <L> Either<L,A> toEither(Fn0<L> lFn0)

If this value is absent, return the value supplied by lSupplier wrapped in Either.left. Otherwise, wrap the value in Either.right and return it.

Type Parameters:

L - the left parameter type

Parameters:

lFn0 - the supplier for the left value

Returns:

this value wrapped in an Either.right, or an Either.left around the result of lSupplier

toOptional

public final java.util.Optional<A> toOptional()

Convert to Optional.

Returns:

the Optional

pure

public final <B> Maybe<B> pure(B b)

Lift the value into the Maybe monad

Specified by:

pure in interface Applicative<A,Maybe<?>>

Specified by:

pure in interface Monad<A,Maybe<?>>

Specified by:

pure in interface MonadError<Unit,A,Maybe<?>>

Specified by:

pure in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the value type

Parameters:

b - the value

Returns:

Just b

fmap

public final <B> Maybe<B> fmap(Fn1<? super A,? extends B> fn)

Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.

If the value is present, return just(A) fn applied to the value; otherwise, return nothing().

Specified by:

fmap in interface Applicative<A,Maybe<?>>

Specified by:

fmap in interface Functor<A,Maybe<?>>

Specified by:

fmap in interface Monad<A,Maybe<?>>

Specified by:

fmap in interface MonadError<Unit,A,Maybe<?>>

Specified by:

fmap in interface MonadRec<A,Maybe<?>>

Specified by:

fmap in interface Traversable<A,Maybe<?>>

Type Parameters:

B - the new parameter type

Parameters:

fn - the mapping function

Returns:

a functor over B (the new parameter type)

zip

public final <B> Maybe<B> zip(Applicative<Fn1<? super A,? extends B>,Maybe<?>> appFn)

Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

Specified by:

zip in interface Applicative<A,Maybe<?>>

Specified by:

zip in interface Monad<A,Maybe<?>>

Specified by:

zip in interface MonadError<Unit,A,Maybe<?>>

Specified by:

zip in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the resulting applicative parameter type

Parameters:

appFn - the other applicative instance

Returns:

the mapped applicative

lazyZip

public <B> Lazy<Maybe<B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Maybe<?>>> lazyAppFn)

Terminate early if this is a Maybe.Nothing; otherwise, continue the zip.

Specified by:

lazyZip in interface Applicative<A,Maybe<?>>

Specified by:

lazyZip in interface Monad<A,Maybe<?>>

Specified by:

lazyZip in interface MonadError<Unit,A,Maybe<?>>

Specified by:

lazyZip in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the result type

Parameters:

lazyAppFn - the lazy other applicative instance

Returns:

the zipped Maybe

See Also:

Maybe, Either

discardL

public final <B> Maybe<B> discardL(Applicative<B,Maybe<?>> appB)

Sequence both this Applicative and appB, discarding this Applicative's result and returning appB. This is generally useful for sequentially performing side-effects.

Specified by:

discardL in interface Applicative<A,Maybe<?>>

Specified by:

discardL in interface Monad<A,Maybe<?>>

Specified by:

discardL in interface MonadError<Unit,A,Maybe<?>>

Specified by:

discardL in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the type of the returned Applicative's parameter

Parameters:

appB - the other Applicative

Returns:

appB

discardR

public final <B> Maybe<A> discardR(Applicative<B,Maybe<?>> appB)

Sequence both this Applicative and appB, discarding appB's result and returning this Applicative. This is generally useful for sequentially performing side-effects.

Specified by:

discardR in interface Applicative<A,Maybe<?>>

Specified by:

discardR in interface Monad<A,Maybe<?>>

Specified by:

discardR in interface MonadError<Unit,A,Maybe<?>>

Specified by:

discardR in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the type of appB's parameter

Parameters:

appB - the other Applicative

Returns:

this Applicative

flatMap

public final <B> Maybe<B> flatMap(Fn1<? super A,? extends Monad<B,Maybe<?>>> f)

Chain dependent computations that may continue or short-circuit based on previous results.

Specified by:

flatMap in interface Monad<A,Maybe<?>>

Specified by:

flatMap in interface MonadError<Unit,A,Maybe<?>>

Specified by:

flatMap in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the resulting monad parameter type

Parameters:

f - the dependent computation over A

Returns:

the new monad instance

trampolineM

public <B> Maybe<B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Maybe<?>>> fn)

Given some operation yielding a RecursiveResult inside this MonadRec, internally trampoline the operation until it yields a termination instruction.

Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.

Specified by:

trampolineM in interface MonadRec<A,Maybe<?>>

Type Parameters:

B - the ultimate resulting carrier type

Parameters:

fn - the function to internally trampoline

Returns:

the trampolined MonadRec

See Also:

for a basic implementation, for a implementation, for an implementation leveraging an already stack-safe , for a implementation

diverge

public <B> Choice3<Unit,A,B> diverge()

Diverge this coproduct by introducing another possible type that it could represent. As no morphisms can be provided mapping current types to the new type, this operation merely acts as a convenience method to allow the use of a more convergent coproduct with a more divergent one; that is, if a CoProduct3<String, Integer, Boolean> is expected, a CoProduct2<String, Integer> should suffice.

Generally, we use inheritance to make this a non-issue; however, with coproducts of differing magnitudes, we cannot guarantee variance compatibility in one direction conveniently at construction time, and in the other direction, at all. A CoProduct2 could not be a CoProduct3 without specifying all type parameters that are possible for a CoProduct3 - more specifically, the third possible type - which is not necessarily known at construction time, or even useful if never used in the context of a CoProduct3. The inverse inheritance relationship - CoProduct3 < CoProduct2 - is inherently unsound, as a CoProduct3 cannot correctly implement CoProduct2.match(com.jnape.palatable.lambda.functions.Fn1<? super A, ? extends R>, com.jnape.palatable.lambda.functions.Fn1<? super B, ? extends R>), given that the third type C is always possible.

For this reason, there is a diverge method supported between all CoProduct types of single magnitude difference.

Specified by:

diverge in interface CoProduct2<Unit,A,Maybe<A>>

Type Parameters:

B - the additional possible type of this coproduct

Returns:

a CoProduct3<A, B, C>

project

public Tuple2<Maybe<Unit>,Maybe<A>> project()

Project this coproduct onto a product, such that the index in the product that corresponds to this coproduct's value is present, while the other indices are absent.

Specified by:

project in interface CoProduct2<Unit,A,Maybe<A>>

Returns:

a product of the coproduct projection

invert

public Choice2<A,Unit> invert()

Swap the type parameters.

Specified by:

invert in interface CoProduct2<Unit,A,Maybe<A>>

Returns:

The inverted coproduct

peek

@Deprecated
public final Maybe<A> peek(Fn1<? super A,? extends IO<?>> effect)

Deprecated.

in favor of matching into an IO and explicitly running it

If this value is present, accept it by consumer; otherwise, do nothing.

Parameters:

effect - the consumer

Returns:

the same Maybe instance

traverse

public final <B,App extends Applicative<?,App>,TravB extends Traversable<B,Maybe<?>>,AppTrav extends Applicative<TravB,App>> AppTrav traverse(Fn1<? super A,? extends Applicative<B,App>> fn,
                                                                                                                                                                                  Fn1<? super TravB,? extends AppTrav> pure)

Description copied from interface: Traversable

Apply fn to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.

Specified by:

traverse in interface Traversable<A,Maybe<?>>

Type Parameters:

B - the resulting element type

App - the result applicative type

TravB - this Traversable instance over B

AppTrav - the full inferred resulting type from the traversal

Parameters:

fn - the function to apply

pure - the applicative pure function

Returns:

the traversed Traversable, wrapped inside an applicative

fromEither

public static <A> Maybe<A> fromEither(Either<?,A> either)

Convenience static factory method for creating a Maybe from an Either. If either is a right value, wrap the value in a just and return it; otherwise, return nothing().

Type Parameters:

A - the potential right value

Parameters:

either - the either instance

Returns:

"Just" the right value, or nothing

fromOptional

public static <A> Maybe<A> fromOptional(java.util.Optional<? extends A> optional)

Convenience static factory method for creating a Maybe from an Optional.

Type Parameters:

A - the optional parameter type

Parameters:

optional - the optional

Returns:

the equivalent Maybe instance

maybe

public static <A> Maybe<A> maybe(A a)

Lift a potentially null value into Maybe. If a is not null, returns just(a); otherwise, returns nothing().

Type Parameters:

A - the value parameter type

Parameters:

a - the potentially null value

Returns:

"Just" the value, or nothing

just

public static <A> Maybe<A> just(A a)

Lift a non-null value into Maybe. This differs from maybe(A) in that the value *must* be non-null; if it is null, a NullPointerException is thrown.

Type Parameters:

A - the value parameter type

Parameters:

a - the non-null value

Returns:

"Just" the value

Throws:

java.lang.NullPointerException - if a is null

nothing

public static <A> Maybe<A> nothing()

Return nothing.

Type Parameters:

A - the type of the value, if there was one

Returns:

nothing

pureMaybe

public static Pure<Maybe<?>> pureMaybe()

The canonical Pure instance for Maybe.

Returns:

the Pure instance