Package cms.util.maybe
Class Maybe<T>
- java.lang.Object
-
- cms.util.maybe.Maybe<T>
-
- All Implemented Interfaces:
java.lang.Iterable<T>
public abstract class Maybe<T> extends java.lang.Object implements java.lang.Iterable<T>
An object that may contain a value of typeT
. 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
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static <T,U extends T>
Maybe<T>cast(Maybe<U> in)
Convert aMaybe<U>
to aMaybe<T>
, whenT
is a supertype ofU
.static <T> Maybe<T>
from(T v)
Create a Maybe from a possibly null value v.static <T> Maybe<T>
fromOptional(java.util.Optional<T> optional)
Create aMaybe
from anOptional
value.abstract T
get()
Returns the contained value, if present.static <T> T
getOptional(java.util.Optional<T> optional)
Get the value in anOptional
, if present; otherwise throw the checked exceptionNoMaybeValue
.abstract boolean
isPresent()
Returns whether a value is contained in thisMaybe
.abstract java.util.Iterator<T>
iterator()
Provide an iterator that yields either oneT
or none, depending.static <T> Maybe<T>
none()
Returns an emptyMaybe
.abstract T
orElse(T other)
Returns the contained value, if any; otherwise, returnsother
.abstract T
orElseGet(java.util.function.Supplier<T> other)
Returns the contained value, if any; otherwise, returnsother.get()
.abstract Maybe<T>
orElseMaybe(java.util.function.Supplier<Maybe<T>> other)
Returns this if a value is contained; otherwise, returnsother.get()
.static <T> Maybe<T>
some(T v)
Creates aMaybe
from a non-null argument.abstract <U> Maybe<U>
then(java.util.function.Function<T,U> f)
If a valuev
is present, returns aMaybe
containingf(v)
, which must be non-null.abstract void
thenDo(java.util.function.Consumer<T> cons)
Callcons
on the contained value, if any.abstract <U> Maybe<U>
thenMaybe(java.util.function.Function<T,Maybe<U>> f)
If a valuev
is present, returnsf(v)
.java.util.Optional<T>
toOptional()
Create anOptional
from aMaybe
-
-
-
Method Detail
-
isPresent
public abstract boolean isPresent()
Returns whether a value is contained in thisMaybe
.- 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(java.util.function.Function<T,Maybe<U>> f)
If a valuev
is present, returnsf(v)
. Otherwise, returns an emptyMaybe
. (This is a monadic bind.) This method is useful for chaining together a series ofMaybe
accesses. For example, supposingT.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 functionf
.- Parameters:
f
- The function to be applied to the contained value, if any.- Returns:
- the
Maybe
returned byf
, if a value is contained in thisMaybe
. Otherwise, an emptyMaybe
.
-
then
public abstract <U> Maybe<U> then(java.util.function.Function<T,U> f)
If a valuev
is present, returns aMaybe
containingf(v)
, which must be non-null. Otherwise, returns an emptyMaybe
. (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 functionf
.- Parameters:
f
- The function to be applied to the contained value, if any.- Returns:
- a
Maybe
containing the valuef
, if a value is contained in thisMaybe
. Otherwise, an emptyMaybe
.
-
orElse
public abstract T orElse(T other)
Returns the contained value, if any; otherwise, returnsother
. Note: since orElse is an ordinary method call, its argument is always computed, unlike a Javaelse
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 thisMaybe
.- Returns:
- The contained value, or an empty
Maybe
.
-
orElseGet
public abstract T orElseGet(java.util.function.Supplier<T> other)
Returns the contained value, if any; otherwise, returnsother.get()
.- Parameters:
other
- The function to use when thisMaybe
is empty.- Returns:
- the contained value or
other.get()
.
-
orElseMaybe
public abstract Maybe<T> orElseMaybe(java.util.function.Supplier<Maybe<T>> other)
Returns this if a value is contained; otherwise, returnsother.get()
.- Parameters:
other
- The function to use when thisMaybe
is empty.- Returns:
- this or
other.get()
.
-
thenDo
public abstract void thenDo(java.util.function.Consumer<T> cons)
Callcons
on the contained value, if any.- Parameters:
cons
- The function to send the contained value to.
-
iterator
public abstract java.util.Iterator<T> iterator()
Provide an iterator that yields either oneT
or none, depending.- Specified by:
iterator
in interfacejava.lang.Iterable<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 ofMaybe
to be created.- Parameters:
v
- The value to put into aMaybe
, or null.
-
fromOptional
public static <T> Maybe<T> fromOptional(java.util.Optional<T> optional)
Create aMaybe
from anOptional
value.- Type Parameters:
T
- The type of the value inside theOptional
.- Parameters:
optional
- TheOptional
value.- Returns:
- If the
Optional
contains a value, then Some of that value, otherwise None.
-
toOptional
public java.util.Optional<T> toOptional()
Create anOptional
from aMaybe
-
getOptional
public static <T> T getOptional(java.util.Optional<T> optional) throws NoMaybeValue
Get the value in anOptional
, if present; otherwise throw the checked exceptionNoMaybeValue
. This method allowsOptional
s to be used as if they were Maybes.- Returns:
- The value in the optional, if any
- Throws:
NoMaybeValue
- if no value is present.
-
none
public static <T> Maybe<T> none()
Returns an emptyMaybe
.
-
some
public static <T> Maybe<T> some(T v)
Creates aMaybe
from a non-null argument.- Parameters:
v
- must be non-null- Throws:
java.lang.IllegalArgumentException
- if a null value is passed to it.
-
-