Module foxcapades.lib.opt

Package io.foxcapades.lib.opt

Interface NonNullOption<T>

Type Parameters:

T - Type of the wrapped value.

All Superinterfaces:

Option<T>

All Known Implementing Classes:

EmptyNonNull, FullNonNullOption

public interface NonNullOption<T>
extends Option<T>

Non-Null Option

Option type that does not permit null values.

Method Summary

Modifier and Type	Method	Description
@NotNull NonNullOption<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 NonNullOption<T>	ifEmpty(@NotNull Runnable fn)	Executes the given Runnable if and only if this Option is empty.
@NotNull NonNullOption<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 NonNullOption<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 NonNullOption<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.
@NotNull NullableOption<T>	toNullable()	Converts this NonNullOption into an instance of NullableOption.
@NotNull NullableOption<T>	toNullable(boolean emptyToNull)	Converts this NonNullOption into an instance of NullableOption.
T	unwrap()	Attempts to unwrap this Option's value.
@NotNull NonNullOption<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.

Methods inherited from interface io.foxcapades.lib.opt.Option

valueEquals

Method Details

isPresent

@Contract(pure=true)
boolean isPresent()

Tests whether this Option contains a value.

IMPORTANT: Implementations of this interface do not allow wrapping null values.

Specified by:

isPresent in interface Option<T>

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: Implementations of this interface do not allow wrapping null values.

Specified by:

isEmpty in interface Option<T>

Returns:

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

unwrap

@NotNull
T unwrap()
  throws UnwrapException

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

IMPORTANT: Implementations of this interface do not allow wrapping null values.

Specified by:

unwrap in interface Option<T>

Returns:

The value wrapped by this Option.

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: Implementations of this interface do not allow wrapping null values.

Specified by:

or in interface Option<T>

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: Implementations of this interface do not allow wrapping null values.

Specified by:

orGet in interface Option<T>

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: Implementations of this interface do not allow wrapping null values.

Specified by:

orThrow in interface Option<T>

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: Implementations of this interface do not allow wrapping null values.

Specified by:

orElseThrow in interface Option<T>

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.

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 NonNullOption<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.

IMPORTANT: Implementations of this interface do not allow wrapping null values.

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.

Specified by:

map in interface Option<T>

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 NonNullOption<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: Implementations of this interface do not allow wrapping null values.

Specified by:

map in interface Option<T>

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 are 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: Implementations of this interface do not allow wrapping null values.

Specified by:

flatMap in interface Option<T>

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: Implementations of this interface do not allow wrapping null values.

Specified by:

flatMap in interface Option<T>

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: Implementations of this interface do not allow wrapping null values.

Specified by:

stream in interface Option<T>

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 NonNullOption<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: Implementations of this interface do not allow wrapping null values.

Specified by:

ifPresent in interface Option<T>

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 NonNullOption<T> ifEmpty(@NotNull
 @NotNull Runnable fn)

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

IMPORTANT: Implementations of this interface do not allow wrapping null values.

Specified by:

ifEmpty in interface Option<T>

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 NonNullOption<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: Implementations of this interface do not allow wrapping null values.

Specified by:

with in interface Option<T>

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(value="_ -> this",
          pure=true)
@NotNull NonNullOption<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.

IMPORTANT: Implementations of this interface do not allow wrapping null values.

Specified by:

filter in interface Option<T>

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.

toNullable

@NotNull
@Contract(pure=true)
@NotNull NullableOption<T> toNullable()

Converts this NonNullOption into an instance of NullableOption.

If the current Option is empty, the returned Option will also be empty.

This method is equivalent to calling toNullable(false).

Returns:

A NullableOption that is either empty or wrapping the same value as this Option.

toNullable

@NotNull
@Contract(pure=true)
@NotNull NullableOption<T> toNullable(boolean emptyToNull)

Converts this NonNullOption into an instance of NullableOption.

If the current option is not empty, the returned Option will wrap the same value as this Option.

If the current option is empty, either a new NullableOption wrapping null or an empty Option will be returned depending on the value of emptyToNull.

If emptyToNull == true && this.isEmpty(), then a NullableOption that is not-empty, wrapping the value null will be returned.

If emptyToNull == false && this.isEmpty(), then an empty option will be returned.

Parameters:

emptyToNull - Flag indicating whether an empty option instance should be converted to a null wrapping option or an empty option.

Returns:

A new option that will be wrapping this option's value, null, or will be empty.