Package cms.util.maybe

Class Maybe<T>

java.lang.Object

cms.util.maybe.Maybe<T>

All Implemented Interfaces:

Iterable<T>, Collection<T>, Set<T>

public abstract class Maybe<T>
extends Object
implements Set<T>

An object that may contain a value of type T. Similar to Java's Optional class but uses a fast checked exception instead of a slow unchecked exception.

Constructor Summary

Constructors

Constructor	Description
Maybe()

Method Summary

Modifier and Type	Method	Description
static <T, U extends T> Maybe<T>	cast(Maybe<U> in)	Convert a Maybe<U> to a Maybe<T>, when T is a supertype of U.
boolean	containsAll(Collection<?> c)
static <T> Maybe<T>	from(T v)	Create a Maybe from a possibly null value v.
static <T, E extends Throwable> Maybe<T>	fromCatching(ThrowingSupplier<T,E> valueOrThrow, Class<? super E> exnClass)	Create a Maybe from the result of a computation, returning Maybes.None if the computation returns null or throws a particular exception.
static <T> Maybe<T>	fromOptional(Optional<? extends T> optional)	Create a Maybe from an Optional value.
abstract T	get()	Returns the contained value, if present.
static <T> T	getOptional(Optional<? extends T> optional)	Get the value in an Optional, if present; otherwise throw the checked exception NoMaybeValue.
abstract boolean	isPresent()	Returns whether a value is contained in this Maybe.
abstract Iterator<T>	iterator()	Provide an iterator that yields either one T or none, depending.
static <T> Maybe<T>	none()	Returns an empty Maybe.
abstract T	orElse(T other)	Returns the contained value, if any; otherwise, returns other.
abstract T	orElseGet(Supplier<? extends T> other)	Returns the contained value, if any; otherwise, returns other.get().
abstract Maybe<T>	orElseMaybe(Supplier<? extends Maybe<? extends T>> other)	Returns this if a value is contained; otherwise, returns other.get().
abstract <E extends Throwable> T	orElseThrow(Supplier<E> throwable)	Returns the contained value, if any; otherwise, throws the specified exception.
static <T> Maybe<T>	some(T v)	Creates a Maybe from a non-null argument.
abstract <U> Maybe<U>	then(Function<? super T,? extends U> f)	If a value v is present, returns a Maybe containing f(v), which must be non-null.
abstract void	thenDo(Consumer<? super T> cons)	Call cons on the contained value, if any.
abstract void	thenElse(Consumer<? super T> consThen, Runnable procElse)	If a value is contained, run consThen on the value; otherwise run procElse
abstract <U> Maybe<U>	thenMaybe(Function<? super T,? extends Maybe<? extends U>> f)	If a value v is present, returns f(v).
Optional<T>	toOptional()	Create an Optional from a Maybe

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.Set

add, addAll, clear, contains, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, spliterator, toArray, toArray

Constructor Details

Maybe

public Maybe()

Method Details

isPresent

public abstract boolean isPresent()

Returns whether a value is contained in this Maybe.

Returns:

whether a value is contained.

get

public abstract T get()
               throws NoMaybeValue

Returns the contained value, if present. Otherwise, throws the exception.

Returns:

the contained value

Throws:

NoMaybeValue - if no value is contained in this Maybe. This method is primarily useful for writing code that is supposed to perform side effects, e.g.:

 Maybe<T> m = ...
 try {
    ... m.get() ...
 } catch (NoMaybeValue e) {
    ...
 }
 

thenMaybe

public abstract <U> Maybe<U> thenMaybe(Function<? super T,? extends Maybe<? extends U>> f)

If a value v is present, returns f(v). Otherwise, returns an empty Maybe. (This is a monadic bind.) This method is useful for chaining together a series of Maybe accesses. For example, supposing T.foo() returns a Maybe:

 
 Maybe<T> mt = ...
 mt.thenMaybe(t -> t.foo().then(f -> ...))
   .orElse(...)
 

Type Parameters:

U - The type of the value that may be returned by the function f.

Parameters:

f - The function to be applied to the contained value, if any.

Returns:

the Maybe returned by f, if a value is contained in this Maybe. Otherwise, an empty Maybe.

then

public abstract <U> Maybe<U> then(Function<? super T,? extends U> f)

If a value v is present, returns a Maybe containing f(v), which must be non-null. Otherwise, returns an empty Maybe. (This is a monadic bind composed with a monadic unit.) This method can be used conveniently along with orElse to handle both maybe cases, e.g.:

 
 Maybe<T> mt = ...
 mt.then(t -> ...)
   .orElse(...)
 

Type Parameters:

U - The type of the value that may be returned by the function f.

Parameters:

f - The function to be applied to the contained value, if any.

Returns:

a Maybe containing the value f, if a value is contained in this Maybe. Otherwise, an empty Maybe.

orElse

public abstract T orElse(T other)

Returns the contained value, if any; otherwise, returns other. Note: since orElse is an ordinary method call, its argument is always computed, unlike a Java else statement. If the argument is expensive to compute or has side effects, orElseGet() should be used instead.

Parameters:

other - The value to be returned if no value is in this Maybe.

Returns:

The contained value, or an empty Maybe.

orElseGet

public abstract T orElseGet(Supplier<? extends T> other)

Returns the contained value, if any; otherwise, returns other.get().

Parameters:

other - The function to use when this Maybe is empty.

Returns:

the contained value or other.get().

orElseThrow

public abstract <E extends Throwable> T orElseThrow(Supplier<E> throwable)
                                             throws E

Returns the contained value, if any; otherwise, throws the specified exception.

Throws:

E

orElseMaybe

public abstract Maybe<T> orElseMaybe(Supplier<? extends Maybe<? extends T>> other)

Returns this if a value is contained; otherwise, returns other.get().

Parameters:

other - The function to use when this Maybe is empty.

Returns:

this or other.get().

thenDo

public abstract void thenDo(Consumer<? super T> cons)

Call cons on the contained value, if any.

Parameters:

cons - The function to send the contained value to.

thenElse

public abstract void thenElse(Consumer<? super T> consThen,
 Runnable procElse)

If a value is contained, run consThen on the value; otherwise run procElse

iterator

public abstract Iterator<T> iterator()

Provide an iterator that yields either one T or none, depending.

Specified by:

iterator in interface Collection<T>

Specified by:

iterator in interface Iterable<T>

Specified by:

iterator in interface Set<T>

containsAll

public boolean containsAll(Collection<?> c)

Specified by:

containsAll in interface Collection<T>

Specified by:

containsAll in interface Set<T>

from

public static <T> Maybe<T> from(T v)

Create a Maybe from a possibly null value v. The Maybe will contain a value if v is non-null.

Type Parameters:

T - The type of Maybe to be created.

Parameters:

v - The value to put into a Maybe, or null.

fromOptional

public static <T> Maybe<T> fromOptional(Optional<? extends T> optional)

Create a Maybe from an Optional value.

Type Parameters:

T - The type of the Maybe to be created.

Parameters:

optional - The Optional value.

Returns:

If the Optional contains a value, then Some of that value, otherwise None.

toOptional

public Optional<T> toOptional()

Create an Optional from a Maybe

getOptional

public static <T> T getOptional(Optional<? extends T> optional)
                         throws NoMaybeValue

Get the value in an Optional, if present; otherwise throw the checked exception NoMaybeValue. This method allows Optionals to be used as if they were Maybes.

Returns:

The value in the optional, if any

Throws:

NoMaybeValue - if no value is present.

fromCatching

public static <T,
E extends Throwable> Maybe<T> fromCatching(ThrowingSupplier<T,E> valueOrThrow,
 Class<? super E> exnClass)

Create a Maybe from the result of a computation, returning Maybes.None if the computation returns null or throws a particular exception. Note that this method only catches the specified exception. If the computation throws any other exception, it is propagated.

As an example, the following code:

 
 Maybe<Float> oldScoreClient;
 try {
     oldScoreClient = Maybe.some(Float.parseFloat(vals[5]));
 } catch (NumberFormatException e) {
     oldScoreClient = Maybe.none();
 }
 

could be rewritten as:

 final Maybe<Float> oldScoreClient = Maybe.fromCatching(() -> Float.parseFloat(vals[5]), NumberFormatException.class)
 

Type Parameters:

T - the type parameter of the resulting Maybe

E - the type of the exception being caught

Parameters:

valueOrThrow - a computation, represented by a ThrowingSupplier that either returns a value to store in this maybe or throws an exception.

exnClass - the exception that valueOrThrow might throw.

Returns:

a Maybes.Some instance containing the result of valueOrThrow, or Maybes.None if the valueOrThrow throws.

none

public static <T> Maybe<T> none()

Returns an empty Maybe.

some

public static <T> Maybe<T> some(T v)

Creates a Maybe from a non-null argument.

Parameters:

v - must be non-null

Throws:

IllegalArgumentException - if a null value is passed to it.

cast

public static <T,
U extends T> Maybe<T> cast(Maybe<U> in)

Convert a Maybe<U> to a Maybe<T>, when T is a supertype of U. This covariant subtyping is safe because Maybes are immutable.