Module foxcapades.lib.opt

Package io.foxcapades.lib.opt

Interface Option<T>

Type Parameters:

T - Type of the represented/wrapped value.

All Known Subinterfaces:

NonNullOption<T>, NullableOption<T>

All Known Implementing Classes:

EmptyNonNull, EmptyNullable, FullNonNullOption, FullNullableOption, FullOption, NullOption

public interface Option<T>

Option

Option represents and immutably wraps a single value that may or may not exist.

Nullability

The base Option type does not set any rules for whether implementing types may allow null values to be wrapped.

Implementations should detail their rules regarding null values.

For these implementations there are 3 states. Present containing a non-null value, present containing a null value, and empty.

Method Summary

Modifier and Type	Method	Description
@NotNull Option<T>	filter(@NotNull Predicate<? super T> fn)	Calls the given Predicate on the value wrapped by this Option, if this Option is not empty.
<R> @NotNull Option<R>	flatMap(@NotNull Function<? super T,? extends Option<? extends R>> fn)	Calls the given Function if this Option is not empty.
<R> @NotNull Option<R>	flatMap(@NotNull Function<? super T,? extends Option<? extends R>> ifPresent, @NotNull Supplier<? extends Option<? extends R>> ifEmpty)	Calls the given mapping Function ifPresent if this Option is not empty, otherwise calls the given Supplier ifEmpty.
@NotNull Option<T>	ifEmpty(@NotNull Runnable fn)	Executes the given Runnable if and only if this Option is empty.
@NotNull Option<T>	ifPresent(@NotNull Consumer<? super T> fn)	Executes the given Consumer with the value wrapped by this Option if this Option is not empty.
boolean	isEmpty()	Tests whether this Option does not contain a value.
boolean	isPresent()	Tests whether this Option contains a value.
<R> @NotNull Option<R>	map(@NotNull Function<? super T,? extends R> fn)	Calls the given Function on the value wrapped by this Option if and only if this Option is not empty.
<R> @NotNull Option<R>	map(@NotNull Function<? super T,? extends R> ifPresent, @NotNull Supplier<? extends R> ifEmpty)	Calls the given Function ifPresent if this Option is not empty, otherwise calls the given Supplier ifEmpty.
T	or(T other)	Returns either the value wrapped by this Option, if it is not empty, or the given value if this Option is empty.
<E extends Throwable> T	orElseThrow(@NotNull Supplier<? extends E> fn)	Returns the value wrapped by this Option if it is not empty, otherwise throws the Exception returned by the given Supplier.
T	orGet(@NotNull Supplier<? extends T> fn)	Returns either the value wrapped by this Option, if it is not empty, or the value returned by the given Supplier.
<E extends Throwable> T	orThrow(E err)	Returns the value wrapped by this Option if it is not empty, otherwise throws the given Exception value.
@NotNull Stream<T>	stream()	Creates a new Stream containing either one value, if this Option is not empty, or containing zero values if this Option is empty.
T	unwrap()	Attempts to unwrap this Option's value.
boolean	valueEquals(@Nullable Object value)	Returns whether the value wrapped by this option equals the given input value.
@NotNull Option<T>	with(@NotNull Consumer<? super T> ifPresent, @NotNull Runnable ifEmpty)	Executes the given Consumer ifPresent on the wrapped value if this Option is not empty, otherwise calls the given Runnable ifEmpty.

Method Details

isPresent

@Contract(pure=true)
boolean isPresent()

Tests whether this Option contains a value.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, a return value of true does not mean the value contained is not null. It simply means that a value is wrapped.

Implementers should detail their rules regarding null values.

Returns:

true if this Option contains a value, otherwise false.

isEmpty

@Contract(pure=true)
boolean isEmpty()

Tests whether this Option does not contain a value.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, a return value of false does not indicate whether the value wrapped is null, instead it simply means that no value whatsoever was wrapped.

Implementers should detail their rules regarding null values.

Returns:

true if this Option does not contain a value, otherwise false.

unwrap

@Contract(pure=true)
T unwrap()
  throws UnwrapException

Attempts to unwrap this Option's value. If this option is empty, this method throws an UnwrapException.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, this method will not throw an exception if the value returned is null. Instead it will only throw an exception if no value was set whatsoever.

Implementers should detail their rules regarding null values.

Returns:

The value wrapped by this Option. This value may be null depending on whether this implementation of Option allows null values.

Throws:

UnwrapException - If this method is called on an empty Option.

or

@Nullable
@Contract(pure=true)
T or(@Nullable
 T other)

Returns either the value wrapped by this Option, if it is not empty, or the given value if this Option is empty.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, the other value will not be returned if the Option is wrapping a null value as, for those implementations, null is a legal and expected possible value.

Implementers should detail their rules regarding null values.

Parameters:

other - Fallback value to return if this Option is empty.

This argument may be null.

Returns:

Either the value wrapped by this Option, or the value of other.

orGet

@Nullable
@Contract(pure=true)
T orGet(@NotNull
 @NotNull Supplier<? extends T> fn)

Returns either the value wrapped by this Option, if it is not empty, or the value returned by the given Supplier.

The given Supplier will not be called if this Option is not empty.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, the Supplier will not be called if the Option is wrapping a null value as, for those implementations, null is a legal and expected possible value.

Implementers should detail their rules regarding null values.

Parameters:

fn - Supplier for the fallback value.

This argument must not be null.

The value returned by the given Supplier may be null.

Returns:

Either the value wrapped by this Option, or the value returned by the given Supplier.

Throws:

NullPointerException - if the given Supplier is null.

orThrow

@Contract(pure=true)
<E extends Throwable> T orThrow(@NotNull
 E err)
                         throws E

Returns the value wrapped by this Option if it is not empty, otherwise throws the given Exception value.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, the given Exception will not be thrown if the wrapped value is null. Instead, the exception will only be thrown if this Option is wrapping no value whatsoever.

Implementers should detail their rules regarding null values.

Type Parameters:

E - Type of the Exception value that will be thrown if this Option is empty.

Parameters:

err - Exception to throw if this Option is empty.

This argument must not be null.

Returns:

The value wrapped by this Option. Individual implementations decide whether null values may be wrapped and returned.

Throws:

E - Thrown if this Option is empty.

NullPointerException - If the given Exception is null.

orElseThrow

@Contract(pure=true)
<E extends Throwable> T orElseThrow(@NotNull
 @NotNull Supplier<? extends E> fn)
                             throws E

Returns the value wrapped by this Option if it is not empty, otherwise throws the Exception returned by the given Supplier.

The given Supplier will not be called if this Option is not empty.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, the Supplier will not be called, and no Exception will be thrown if the wrapped value is null. Instead, the Supplier will be called and Exception thrown only if this Option is wrapping no value whatsoever.

Implementers should detail their rules regarding null values.

Type Parameters:

E - Type of the exception that will be returned by the given Supplier and thrown.

Parameters:

fn - Supplier for the Exception to throw if this Option is empty.

This argument must not be null.

This Supplier must not return null.

Returns:

The value wrapped by this Option. Individual implementations decide whether null values may be wrapped.

Throws:

E - If this Option is empty.

NullPointerException - if the given Supplier is null or if it returns null.

map

@Contract(pure=true)
@NotNull
<R> @NotNull Option<R> map(@NotNull
 @NotNull Function<? super T,? extends R> fn)

Calls the given Function on the value wrapped by this Option if and only if this Option is not empty.

If the given function returns null an empty Option will be returned. If the given function does not return null a new Option will be returned wrapping the result value of the call to the given Function.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, the given Function should be prepared to accept null values.

Implementers should detail their rules regarding null values.

Type Parameters:

R - The return type of the given mapping Function.

Parameters:

fn - Function to call on the value wrapped by this Option.

This argument must not be null

Returns:

A new Option of generic type R. This Option will be empty if the return value of fn was null, otherwise the returned Option will be wrapping the value returned by the given Function.

Throws:

NullPointerException - If the given Function is null.

map

@NotNull
@Contract(pure=true)
<R> @NotNull Option<R> map(@NotNull
 @NotNull Function<? super T,? extends R> ifPresent,
 @NotNull
 @NotNull Supplier<? extends R> ifEmpty)

Calls the given Function ifPresent if this Option is not empty, otherwise calls the given Supplier ifEmpty.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, if the Option is wrapping a null value, it will call the Function ifPresent, passing in the wrapped null value. This means, for those Option implementations, the Function passed as ifPresent should be prepared to handle null values.

Implementers should detail their rules regarding null values.

Type Parameters:

R - Generic type of the returned Option.

Parameters:

ifPresent - Mapping function to call on the value wrapped by this Option.

This argument must not be null.

This function will only be called if this Option is not empty.

ifEmpty - Value supplier to call when this Option is empty.

This argument must not be null.

Returns:

A new Option of generic type R.

Throws:

NullPointerException - If either of the given functions is null.

flatMap

@NotNull
@Contract(pure=true)
<R> @NotNull Option<R> flatMap(@NotNull
 @NotNull Function<? super T,? extends Option<? extends R>> fn)

Calls the given Function if this Option is not empty.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, if the wrapped value is null, the given Function will be called, and passed the wrapped null value. If the current implementation allows nulls, this Function should be prepared to handle null inputs.

Implementers should detail their rules regarding null values.

Type Parameters:

R - Generic type of the returned Option.

Parameters:

fn - Mapping function to call if this Option is not empty.

This argument must not be null.

This function must not return null

This function will not be called if this Option is empty.

Returns:

A new Option of generic type R.

Throws:

NullPointerException - if the given function is null or if the given function returns null.

flatMap

@NotNull
@Contract(pure=true)
<R> @NotNull Option<R> flatMap(@NotNull
 @NotNull Function<? super T,? extends Option<? extends R>> ifPresent,
 @NotNull
 @NotNull Supplier<? extends Option<? extends R>> ifEmpty)

Calls the given mapping Function ifPresent if this Option is not empty, otherwise calls the given Supplier ifEmpty. IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. For those implementations, if the Option is wrapping a null value, it will call the Function ifPresent, passing in the wrapped null value. This means, for those Option implementations, the Function passed as ifPresent should be prepared to handle null values.

Implementers should detail their rules regarding null values.

Type Parameters:

R - Generic type for the returned Option.

Parameters:

ifPresent - Mapping function to call if this Option is not empty.

This argument must not be null.

This function must not return null.

ifEmpty - Supplier function to call if this Option is empty.

This argument must not be null.

This value must not return null.

Returns:

A new Option of generic type R.

Throws:

NullPointerException - If ifPresent is null, ifEmpty is null, or if the called function returns null.

stream

@NotNull
@Contract(pure=true)
@NotNull Stream<T> stream()

Creates a new Stream containing either one value, if this Option is not empty, or containing zero values if this Option is empty.

IMPORTANT: Individual implementations of Option decide whether a null value may be wrapped. This means, for those implementations, the single value in the returned Stream for non-empty Options may be null.

Implementers should detail their rules regarding null values.

Returns:

A new Stream that may contain the value wrapped by this Option, if such a value exists, otherwise contains no values.

ifPresent

@NotNull
@Contract(value="_ -> this",
          pure=true)
@NotNull Option<T> ifPresent(@NotNull
 @NotNull Consumer<? super T> fn)

Executes the given Consumer with the value wrapped by this Option if this Option is not empty.

The given function will not be called if this Option is empty.

IMPORTANT: Individual Option implementations decide whether a null value may be wrapped. For those implementations, the given Consumer will be called if the Option is wrapping a null value. This means, for those implementations, the passed Consumer should be prepared to handle a null input.

Implementers should detail their rules regarding null values.

Parameters:

fn - Consumer to call on the wrapped value if this Option is not empty.

This argument must not be null.

Returns:

This Option instance.

Throws:

NullPointerException - If the given Consumer value is null.

ifEmpty

@NotNull
@Contract(value="_ -> this",
          pure=true)
@NotNull Option<T> ifEmpty(@NotNull
 @NotNull Runnable fn)

Executes the given Runnable if and only if this Option is empty.

IMPORTANT: Individual Option implementations decide whether a null value may be wrapped. For those implementations, if this Option is wrapping a null value, the given function will not be called.

Implementers should detail their rules regarding null values.

Parameters:

fn - Runnable to call if this Option is empty.

This argument must not be null.

Returns:

This Option instance.

Throws:

NullPointerException - if the given Runnable value is null.

with

@Contract(value="_, _ -> this",
          pure=true)
@NotNull
@NotNull Option<T> with(@NotNull
 @NotNull Consumer<? super T> ifPresent,
 @NotNull
 @NotNull Runnable ifEmpty)

Executes the given Consumer ifPresent on the wrapped value if this Option is not empty, otherwise calls the given Runnable ifEmpty.

IMPORTANT: Individual Option implementations decide whether a null value may be wrapped. For those implementations, if the wrapped value is null, the given function ifPresent will be called and passed the wrapped null value, null values are considered legal and possible valid values. This means, for those Option implementations, the given ifPresent function should be prepared to handle a null input.

Implementers should detail their rules regarding null values.

Parameters:

ifPresent - Consumer to call with the value wrapped by this Option if this Option is not empty.

This argument must not be null.

ifEmpty - Runnable to call if this Option is empty.

This argument must not be null.

Returns:

This Option instance.

Throws:

NullPointerException - If ifPresent is null, or if ifEmpty is null.

filter

@NotNull
@Contract(pure=true)
@NotNull Option<T> filter(@NotNull
 @NotNull Predicate<? super T> fn)

Calls the given Predicate on the value wrapped by this Option, if this Option is not empty.

The given Predicate will not be called if this Option is empty.

If the given Predicate returns true, this Option will be returned, otherwise an empty Option will be returned.

IMPORTANT: Individual Option implementations decide whether a null value may be wrapped. For those implementations, the given Predicate will be called if the Option is wrapping a null value, and will be passed the wrapped null. This means, for those implementations, the given Predicate should be prepared to handle a null input.

Implementers should detail their rules regarding null values.

Parameters:

fn - Predicate to apply to the value wrapped by this Option if this Option is not empty.

This value must not be null.

Returns:

This Option if the given Predicate returns true, otherwise an empty Option.

valueEquals

@Contract(pure=true)
boolean valueEquals(@Nullable
 @Nullable Object value)

Returns whether the value wrapped by this option equals the given input value.

For empty options, this method will always return false.

Parameters:

value - Value to compare against the wrapped value.

Returns:

Whether the given value equals the value wrapped by this option. If this option is empty, this value will always be false. If this option allows null values and is wrapping a null value, this method will only return true if the given input is also null.