Package org.javimmutable.collections

Class Maybe<T>

java.lang.Object

org.javimmutable.collections.Maybe<T>

All Implemented Interfaces:

Serializable, Iterable<T>, IStreamable<T>, SplitableIterable<T>

public abstract class Maybe<T>
extends Object
implements IStreamable<T>, Serializable

Used to handle cases when a value may or may not exist. The value of a Maybe can be null but the notNull() method can be used to change a null value into an empty NotNull when desired. Alternatively, nullToEmpty() can be used to convert a null value into an empty Maybe. Provides a variety of utility methods to allow call chaining.

See Also:

• Serialized Form

Method Summary

Modifier and Type	Method	Description
abstract Maybe<T>	apply(Proc0 absentAction)	Invokes absentAction if this is empty.
abstract Maybe<T>	apply(Proc1<? super T> presentAction)	Invokes presentAction with this value if this is full.
abstract <E extends Exception> Maybe<T>	applyThrows(Proc0Throws<E> absentAction)	Invokes absentAction if this is empty.
abstract <E extends Exception> Maybe<T>	applyThrows(Proc1Throws<? super T,E> presentAction)	Invokes presentAction with this value if this is full.
static <T> Maybe<T>	cast(Class<T> klass, Object valueOrNull)	Determine if the object is an instance of the specified Class or a subclass.
static <T> Maybe<T>	empty()	Returns a Maybe with no value.
static <T> Maybe<T>	first(Iterable<? extends T> collection)	Returns a Maybe containing the first value of the collection.
static <T> Maybe<T>	first(Iterable<? extends T> collection, Func1<? super T,Boolean> predicate)	Returns a Maybe containing the first value of the collection for which the predicate returns true.
abstract <A> Maybe<A>	flatMap(Func0<Maybe<A>> absentMapping, Func1<? super T,Maybe<A>> presentMapping)	Produce a Maybe based on this one.
abstract Maybe<T>	flatMap(Func0<Maybe<T>> absentMapping)	Produce a Maybe based on this one.
abstract <A> Maybe<A>	flatMap(Func1<? super T,Maybe<A>> presentMapping)	Produce a Maybe based on this one.
abstract <A, E extends Exception> Maybe<A>	flatMapThrows(Func0Throws<Maybe<A>,E> absentMapping, Func1Throws<? super T,Maybe<A>,E> presentMapping)	Produce a Maybe based on this one.
abstract <E extends Exception> Maybe<T>	flatMapThrows(Func0Throws<Maybe<T>,E> absentMapping)	Produce a Maybe based on this one.
abstract <A, E extends Exception> Maybe<A>	flatMapThrows(Func1Throws<? super T,Maybe<A>,E> presentMapping)	Produce a Maybe based on this one.
abstract T	get(T absentValue)	Gets this value.
abstract T	getOr(Func0<? extends T> absentMapping)	Gets this value.
abstract T	getOrNull()	Gets this value.
abstract boolean	isEmpty()	Returns true if this has no value
abstract boolean	isFull()	Returns true if this has a value
abstract Maybe<T>	map(Func0<? extends T> absentMapping)	Produce a full Maybe.
abstract <U> Maybe<U>	map(Func0<? extends U> absentMapping, Func1<? super T,? extends U> presentMapping)	Produce a full Maybe.
abstract <U> Maybe<U>	map(Func1<? super T,? extends U> presentMapping)	Produce a Maybe that is empty if this is empty or else contains the result of passing this value to the given mapping function.
abstract <E extends Exception> Maybe<T>	mapThrows(Func0Throws<? extends T,E> absentMapping)	Produce a full Maybe.
abstract <U, E extends Exception> Maybe<U>	mapThrows(Func0Throws<? extends U,E> absentMapping, Func1Throws<? super T,? extends U,E> presentMapping)	Produce a full Maybe.
abstract <U, E extends Exception> Maybe<U>	mapThrows(Func1Throws<? super T,? extends U,E> presentMapping)	Produce a Maybe that is empty if this is empty or else contains the result of passing this value to the given mapping function.
abstract <U> U	match(U absentValue, Func1<? super T,U> presentMapping)	Gets a value based on this value.
abstract <U> U	matchOr(Func0<U> absentMapping, Func1<? super T,U> presentMapping)	Gets a value based on this value.
abstract <U, E extends Exception> U	matchOrThrows(Func0Throws<U,E> absentMapping, Func1Throws<? super T,U,E> presentMapping)	Gets a value based on this value.
abstract <U, E extends Exception> U	matchThrows(U absentValue, Func1Throws<? super T,U,E> presentMapping)	Gets a value based on this value.
abstract NotNull<T>	notNull()	If this empty or has a null value returns NotNull.empty(), otherwise returns a NotNull containing the same value as this.
abstract Maybe<T>	nullToEmpty()	If this empty or has a null value returns empty(), otherwise returns this.
static <T> Maybe<T>	of(T valueOrNull)	Returns a Maybe containing the value.
abstract Maybe<T>	reject(java.util.function.Predicate<? super T> predicate)	Returns this if this is full and predicate returns false.
abstract Maybe<T>	select(java.util.function.Predicate<? super T> predicate)	Returns this if this is full and predicate returns true.
abstract T	unsafeGet()	Gets this value.
abstract <E extends Exception> T	unsafeGet(Func0<E> absentExceptionMapping)	Gets this value.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.javimmutable.collections.IStreamable

getSpliteratorCharacteristics, iterator, parallelStream, spliterator, stream

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface org.javimmutable.collections.SplitableIterable

forEachThrows, indexedForEach, indexedForEachThrows, reduce, reduceThrows

Method Details

empty

@Nonnull
public static <T> Maybe<T> empty()

Returns a Maybe with no value. All empty Maybes share a common instance.

of

@Nonnull
public static <T> Maybe<T> of(@Nullable
 T valueOrNull)

Returns a Maybe containing the value. Null is a valid value.

cast

public static <T> Maybe<T> cast(@Nonnull
 Class<T> klass,
 @Nullable
 Object valueOrNull)

Determine if the object is an instance of the specified Class or a subclass. If the object is null, returns a Maybe containing null. If the object is not null but not of the correct class, returns an empty Holder. Otherwise returns a Holder containing the value cast to the target type.

Type Parameters:

T - type of the class

Parameters:

klass - class to cast the object to

valueOrNull - object to be case

Returns:

a Maybe

first

@Nonnull
public static <T> Maybe<T> first(@Nonnull
 Iterable<? extends T> collection)

Returns a Maybe containing the first value of the collection. If the collection is empty an empty Maybe is returned.

first

@Nonnull
public static <T> Maybe<T> first(@Nonnull
 Iterable<? extends T> collection,
 @Nonnull
 Func1<? super T,Boolean> predicate)

Returns a Maybe containing the first value of the collection for which the predicate returns true. If the collection is empty or predicate always returns false an empty Maybe is returned.

notNull

@Nonnull
public abstract NotNull<T> notNull()

If this empty or has a null value returns NotNull.empty(), otherwise returns a NotNull containing the same value as this.

nullToEmpty

@Nonnull
public abstract Maybe<T> nullToEmpty()

If this empty or has a null value returns empty(), otherwise returns this.

map

@Nonnull
public abstract Maybe<T> map(@Nonnull
 Func0<? extends T> absentMapping)

Produce a full Maybe. If this Maybe is full it is returned. Otherwise the absentMapping function is called to provide a value for the result Maybe.

Parameters:

absentMapping - produces value if this is empty

Returns:

a full Maybe

map

@Nonnull
public abstract <U> Maybe<U> map(@Nonnull
 Func1<? super T,? extends U> presentMapping)

Produce a Maybe that is empty if this is empty or else contains the result of passing this value to the given mapping function.

Parameters:

presentMapping - maps this value to new value

Returns:

a possibly empty Maybe

map

@Nonnull
public abstract <U> Maybe<U> map(@Nonnull
 Func0<? extends U> absentMapping,
 @Nonnull
 Func1<? super T,? extends U> presentMapping)

Produce a full Maybe. If this is empty the absentMapping function is called to provide a value. Otherwise the presentMapping function is called to produce a new value based on this value.

Parameters:

absentMapping - produces value when this is empty

presentMapping - maps this value to new value

Returns:

a full Maybe

mapThrows

@Nonnull
public abstract <E extends Exception> Maybe<T> mapThrows(@Nonnull
 Func0Throws<? extends T,E> absentMapping)
                                                  throws E

Produce a full Maybe. If this Maybe is full it is returned. Otherwise the absentMapping function is called to provide a value for the result Maybe.

Parameters:

absentMapping - produces value if this is empty

Returns:

a full Maybe

Throws:

E

mapThrows

@Nonnull
public abstract <U,
E extends Exception> Maybe<U> mapThrows(@Nonnull
 Func1Throws<? super T,? extends U,E> presentMapping)
                                                     throws E

Produce a Maybe that is empty if this is empty or else contains the result of passing this value to the given mapping function.

Parameters:

presentMapping - maps this value to new value

Returns:

a possibly empty Maybe

Throws:

E

mapThrows

@Nonnull
public abstract <U,
E extends Exception> Maybe<U> mapThrows(@Nonnull
 Func0Throws<? extends U,E> absentMapping,
 @Nonnull
 Func1Throws<? super T,? extends U,E> presentMapping)
                                                     throws E

Produce a full Maybe. If this is empty the absentMapping function is called to provide a value. Otherwise the presentMapping function is called to produce a new value based on this value.

Parameters:

absentMapping - produces value when this is empty

presentMapping - maps this value to new value

Returns:

a full Maybe

Throws:

E

flatMap

@Nonnull
public abstract Maybe<T> flatMap(@Nonnull
 Func0<Maybe<T>> absentMapping)

Produce a Maybe based on this one. If this is empty absentMapping is called to produce a new Maybe. Otherwise this is returned.

Parameters:

absentMapping - produce new Maybe if this is empty

Returns:

a Maybe

flatMap

@Nonnull
public abstract <A> Maybe<A> flatMap(@Nonnull
 Func1<? super T,Maybe<A>> presentMapping)

Produce a Maybe based on this one. If this is full its value is passed to presentMapping to produce a new Maybe. Otherwise this is returned.

Parameters:

presentMapping - produce a new Maybe from this value

Returns:

a Maybe

flatMap

@Nonnull
public abstract <A> Maybe<A> flatMap(@Nonnull
 Func0<Maybe<A>> absentMapping,
 @Nonnull
 Func1<? super T,Maybe<A>> presentMapping)

Produce a Maybe based on this one. If this is full its value is passed to presentMapping to produce a new Maybe. Otherwise absentMapping is called to produce a new Maybe..

Parameters:

absentMapping - produce a new Maybe when this is empty

presentMapping - produce a new Maybe from this value

Returns:

a Maybe

flatMapThrows

@Nonnull
public abstract <E extends Exception> Maybe<T> flatMapThrows(@Nonnull
 Func0Throws<Maybe<T>,E> absentMapping)
                                                      throws E

Produce a Maybe based on this one. If this is empty absentMapping is called to produce a new Maybe. Otherwise this is returned.

Parameters:

absentMapping - produce new Maybe if this is empty

Returns:

a Maybe

Throws:

E

flatMapThrows

@Nonnull
public abstract <A,
E extends Exception> Maybe<A> flatMapThrows(@Nonnull
 Func1Throws<? super T,Maybe<A>,E> presentMapping)
                                                         throws E

Produce a Maybe based on this one. If this is full its value is passed to presentMapping to produce a new Maybe. Otherwise this is returned.

Parameters:

presentMapping - produce a new Maybe from this value

Returns:

a Maybe

Throws:

E

flatMapThrows

@Nonnull
public abstract <A,
E extends Exception> Maybe<A> flatMapThrows(@Nonnull
 Func0Throws<Maybe<A>,E> absentMapping,
 @Nonnull
 Func1Throws<? super T,Maybe<A>,E> presentMapping)
                                                         throws E

Produce a Maybe based on this one. If this is full its value is passed to presentMapping to produce a new Maybe. Otherwise absentMapping is called to produce a new Maybe..

Parameters:

absentMapping - produce a new Maybe when this is empty

presentMapping - produce a new Maybe from this value

Returns:

a Maybe

Throws:

E

select

@Nonnull
public abstract Maybe<T> select(@Nonnull
 java.util.function.Predicate<? super T> predicate)

Returns this if this is full and predicate returns true. Otherwise an empty Maybe is returned.

Parameters:

predicate - determines whether to accept this value

Returns:

a Maybe

reject

@Nonnull
public abstract Maybe<T> reject(@Nonnull
 java.util.function.Predicate<? super T> predicate)

Returns this if this is full and predicate returns false. Otherwise an empty Maybe is returned.

Parameters:

predicate - determines whether to reject this value

Returns:

a Maybe

apply

@Nonnull
public abstract Maybe<T> apply(@Nonnull
 Proc0 absentAction)

Invokes absentAction if this is empty.

Parameters:

absentAction - action to call if this is empty

Returns:

this

apply

@Nonnull
public abstract Maybe<T> apply(@Nonnull
 Proc1<? super T> presentAction)

Invokes presentAction with this value if this is full.

Parameters:

presentAction - action to call if this is full

Returns:

this

applyThrows

@Nonnull
public abstract <E extends Exception> Maybe<T> applyThrows(@Nonnull
 Proc0Throws<E> absentAction)
                                                    throws E

Invokes absentAction if this is empty.

Parameters:

absentAction - action to call if this is empty

Returns:

this

Throws:

E

applyThrows

@Nonnull
public abstract <E extends Exception> Maybe<T> applyThrows(@Nonnull
 Proc1Throws<? super T,E> presentAction)
                                                    throws E

Invokes presentAction with this value if this is full.

Parameters:

presentAction - action to call if this is full

Returns:

this

Throws:

E

unsafeGet

public abstract T unsafeGet()

Gets this value. Throws NoSuchElementException if this is empty.

Returns:

this value

Throws:

NoSuchElementException - if this is empty

unsafeGet

public abstract <E extends Exception> T unsafeGet(@Nonnull
 Func0<E> absentExceptionMapping)
                                           throws E

Gets this value. Calls absentExceptionMapping to get an exception to throw if this is empty.

Returns:

this value

Throws:

E - an exception produced by mapping if this is empty

get

public abstract T get(T absentValue)

Gets this value. If this is empty returns absentValue instead.

Parameters:

absentValue - value to return if this is empty

getOrNull

public abstract T getOrNull()

Gets this value. If this is empty returns null.

getOr

public abstract T getOr(@Nonnull
 Func0<? extends T> absentMapping)

Gets this value. If this is empty returns result of calling absentMapping instead.

Parameters:

absentMapping - function to generate value to return if this is empty

match

public abstract <U> U match(U absentValue,
 @Nonnull
 Func1<? super T,U> presentMapping)

Gets a value based on this value. If this is empty absentValue is returned. Otherwise this value is passed to presentMapping to obtain a return value.

Parameters:

absentValue - value to return if this is empty

presentMapping - function to map this value into return value

Returns:

a value

matchOr

public abstract <U> U matchOr(@Nonnull
 Func0<U> absentMapping,
 @Nonnull
 Func1<? super T,U> presentMapping)

Gets a value based on this value. If this is empty absentMapping is called to obtain a return value. Otherwise this value is passed to presentMapping to obtain a return value.

Parameters:

absentMapping - function to produce a value to return if this is empty

presentMapping - function to map this value into return value

Returns:

a value

matchThrows

public abstract <U,
E extends Exception> U matchThrows(U absentValue,
 @Nonnull
 Func1Throws<? super T,U,E> presentMapping)
                                                throws E

Gets a value based on this value. If this is empty absentValue is returned. Otherwise this value is passed to presentMapping to obtain a return value.

Parameters:

absentValue - value to return if this is empty

presentMapping - function to map this value into return value

Returns:

a value

Throws:

E

matchOrThrows

public abstract <U,
E extends Exception> U matchOrThrows(@Nonnull
 Func0Throws<U,E> absentMapping,
 @Nonnull
 Func1Throws<? super T,U,E> presentMapping)
                                                  throws E

Gets a value based on this value. If this is empty absentMapping is called to obtain a return value. Otherwise this value is passed to presentMapping to obtain a return value.

Parameters:

absentMapping - function to produce a value to return if this is empty

presentMapping - function to map this value into return value

Returns:

a value

Throws:

E

isEmpty

public abstract boolean isEmpty()

Returns true if this has no value

isFull

public abstract boolean isFull()

Returns true if this has a value