Module foxcapades.lib.opt
Package io.foxcapades.lib.opt

Interface NullableOption<T>

Type Parameters:
T - Type of the represented/wrapped value.
All Superinterfaces:
Option<T>
All Known Implementing Classes:
EmptyNullable, FullNullableOption, NullOption
public interface NullableOption<T> extends Option<T>
Nullable Option NullableOption represents and immutable wraps a single, nullable value that may or may not exist.

Nullability

Implementations of this interface allow wrapping null values. This means this Option type has 3 states.
  • Value is present and not null.
  • Value is present and null.
  • Value is absent.

For methods on this interface that accept Function or Consumer arguments, the passed functions should be prepared to handle a null input value.

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull NullableOption<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 NullableOption<T>
    ifEmpty​(@NotNull Runnable fn)
    Executes the given Runnable if and only if this Option is empty.
    @NotNull NullableOption<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
    isNull()
    Tests whether the wrapped value is null.
    boolean
    isPresent()
    Tests whether this Option contains a value.
    <R> @NotNull NullableOption<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 NullableOption<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 NonNullOption<T>
    toNonNullable()
    Converts this Option to a NonNullOption.
    T
    unwrap()
    Attempts to unwrap this Option's value.
    @NotNull NullableOption<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

    • isNull

      @Contract(pure=true) boolean isNull()
      Tests whether the wrapped value is null.

      A return value of true means that this Option is not empty and the value it wraps is null.

      A return value of false may mean either that this Option is empty, or that the wrapped value is not null. To test if this is the case, isPresent() and/or isEmpty() should be used.

      Returns:
      true if this Option is both non-empty and is wrapping a null value. false if this option is empty, or is not wrapping a null value.

    • toNonNullable

      @NotNull @Contract(pure=true) @NotNull NonNullOption<T> toNonNullable()
      Converts this Option to a NonNullOption.

      The conversion happens as follows:

      Option conversion rules.
      This Value Returns
      Not-null Non-empty Option wrapping this Option's value.
      null Empty Option
      empty Empty Option
      Returns:
      A new NonNullOption which may be empty or non-empty based on the rules detailed above.

    • isPresent

      @Contract(pure=true) boolean isPresent()
      Tests whether this Option contains a value.

      IMPORTANT: Implementations of this interface allow wrapping null values. The return value of this method does not indicate whether the wrapped value is null. To check whether the wrapped value is null, use isNull().

      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 allow wrapping null values. The return value of this method does not indicate whether the wrapped value is null. To check whether the wrapped value is null, use isNull().

      Specified by:
      isEmpty in interface Option<T>
      Returns:
      true if this Option does not contain a value, otherwise false.

    • unwrap

      @Nullable @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: Implementations of this interface allow wrapping null values. This means the value returned may e null, and in that case, no UnwrapException will be thrown.

      Specified by:
      unwrap in interface Option<T>
      Returns:
      The value wrapped by this Option. This value may be null.
      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 allow wrapping null values. This means the other value will not be returned if this Option is wrapping a null value as null is a legal and expected possible value.

      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 allow wrapping null values. This means the given Supplier will not be called if the wrapped value is null as null is a legal and expected possible value.

      The given Supplier should be prepared to handle a null input.

      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

      @Nullable @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 allow wrapping null values. This means 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.

      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.
      Throws:
      E - Thrown if this Option is empty.
      NullPointerException - If the given Exception is null.

    • orElseThrow

      @Nullable @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 allow wrapping null values. This means 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.

      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 NullableOption<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 allow wrapping null values. This means the given Function should be prepared to accept null values.

      The given Function may null.

      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.
      Throws:
      NullPointerException - If the given Function is null.

    • map

      @NotNull @Contract(pure=true) <R> @NotNull NullableOption<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 allow wrapping null values. This means, if this Option is wrapping a null value, it will call the Function ifPresent, passing in the wrapped null value. In this case, ifEmpty will not be called.

      The passed Function ifPresent may return null, and should be prepared to accept a null input.

      If the called input function returns null, the output Option will be non-empty, wrapping a null value.

      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 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: Implementations of this interface allow wrapping null values. This means, if the wrapped value is null, the given Function will be called, and passed the wrapped null value.

      The given Function should be prepared to handle a null input.

      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 allow wrapping null values. This means, if this Option is wrapping a null value, it will call the Function ifPresent, passing in the wrapped null value instead of calling ifEmpty.

      The given Function ifPresent should be prepared to accept a null input value.

      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 allow wrapping null values. This means the single value in the returned Stream for non-empty Options may be null.

      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 NullableOption<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 allow wrapping null values. This means the given Consumer will be called if the Option is wrapping a null value passing in the wrapped null value.

      The given Consumer should be prepared to handle a null input.

      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 NullableOption<T> ifEmpty​(@NotNull @NotNull Runnable fn)
      Executes the given Runnable if and only if this Option is empty.

      IMPORTANT: Implementations of this interface allow wrapping null values. This means the given Runnable will not be called if this Option is wrapping a null value.

      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

      @NotNull @Contract(value="_, _ -> this", pure=true) @NotNull NullableOption<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 allow wrapping null values. This means if the wrapped value is null, the given function ifPresent will be called and passed the wrapped null value.

      If this Option is wrapping a null value, ifEmpty will not be called.

      The given Consumer ifPresent should be prepared to handle a null input value.

      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(pure=true) @NotNull NullableOption<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: Implementations of this interface allow wrapping null values. This means Predicate will be called if the Option is wrapping a null value, and will be passed the wrapped null.

      The given Predicate should be prepared to handle a null input value.

      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.