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

Record Class NullOption<T>

java.lang.Object
java.lang.Record
io.foxcapades.lib.opt.impl.NullOption<T>
Type Parameters:
T - Generic type of this option.
All Implemented Interfaces:
NullableOption<T>, Option<T>
public record NullOption<T>() extends Record implements NullableOption<T>
Singleton type representing a null option.

  • Constructor Summary

    Constructors
    Constructor
    Description
    NullOption()
    Creates an instance of a NullOption record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals​(Object o)
    Indicates whether some other object is "equal to" this one.
    @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>> ignored)
    Calls the given mapping Function ifPresent if this Option is not empty, otherwise calls the given Supplier ifEmpty.
    int
    hashCode()
    Returns a hash code value for this object.
    @NotNull NullableOption<T>
    ifEmpty​(@NotNull Runnable ignored)
    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.
    static <T> @NotNull NullableOption<T>
    instance()
    Returns the singleton NullOption instance.
    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> ignored)
    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.
    String
    toString()
    Returns a string representation of this record class.
    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 NullableOption<T>
    with​(@NotNull Consumer<? super T> ifPresent, @NotNull Runnable ignored)
    Executes the given Consumer ifPresent on the wrapped value if this Option is not empty, otherwise calls the given Runnable ifEmpty.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • NullOption

      public NullOption()
      Creates an instance of a NullOption record class.

  • Method Details

    • isNull

      public boolean isNull()
      Description copied from interface: NullableOption
      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, NullableOption.isPresent() and/or NullableOption.isEmpty() should be used.

      Specified by:
      isNull in interface NullableOption<T>
      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.

    • isPresent

      public boolean isPresent()
      Description copied from interface: NullableOption
      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 NullableOption.isNull().

      Specified by:
      isPresent in interface NullableOption<T>
      Specified by:
      isPresent in interface Option<T>
      Returns:
      true if this Option contains a value, otherwise false.

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: NullableOption
      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 NullableOption.isNull().

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

    • unwrap

      @Nullable public T unwrap() throws UnwrapException
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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 public T or​(@Nullable T other)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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 public T orGet​(@NotNull @NotNull Supplier<? extends T> fn)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • orThrow

      @Nullable public <E extends Throwable> T orThrow​(@NotNull E err)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • orElseThrow

      @Nullable public <E extends Throwable> T orElseThrow​(@NotNull @NotNull Supplier<? extends E> fn)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • map

      @NotNull public <R> @NotNull NullableOption<R> map​(@NotNull @NotNull Function<? super T,​? extends R> fn)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • map

      @NotNull public <R> @NotNull NullableOption<R> map​(@NotNull @NotNull Function<? super T,​? extends R> ifPresent, @NotNull @NotNull Supplier<? extends R> ignored)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

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

      This argument must not be null.

      Returns:
      A new Option of generic type R.

    • flatMap

      @NotNull public <R> @NotNull Option<R> flatMap​(@NotNull @NotNull Function<? super T,​? extends Option<? extends R>> fn)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • flatMap

      @NotNull public <R> @NotNull Option<R> flatMap​(@NotNull @NotNull Function<? super T,​? extends Option<? extends R>> ifPresent, @NotNull @NotNull Supplier<? extends Option<? extends R>> ignored)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

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

    • stream

      @NotNull public @NotNull Stream<T> stream()
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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 public @NotNull NullableOption<T> ifPresent​(@NotNull @NotNull Consumer<? super T> fn)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • ifEmpty

      @NotNull public @NotNull NullableOption<T> ifEmpty​(@NotNull @NotNull Runnable ignored)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      Specified by:
      ifEmpty in interface Option<T>
      Parameters:
      ignored - Runnable to call if this Option is empty.

      This argument must not be null.

      Returns:
      This Option instance.

    • with

      @NotNull public @NotNull NullableOption<T> with​(@NotNull @NotNull Consumer<? super T> ifPresent, @NotNull @NotNull Runnable ignored)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

      ignored - Runnable to call if this Option is empty.

      This argument must not be null.

      Returns:
      This Option instance.

    • filter

      @NotNull public @NotNull NullableOption<T> filter​(@NotNull @NotNull Predicate<? super T> fn)
      Description copied from interface: NullableOption
      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 NullableOption<T>
      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.

    • toNonNullable

      @NotNull public @NotNull NonNullOption<T> toNonNullable()
      Description copied from interface: NullableOption
      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
      Specified by:
      toNonNullable in interface NullableOption<T>
      Returns:
      A new NonNullOption which may be empty or non-empty based on the rules detailed above.

    • instance

      @NotNull public static <T> @NotNull NullableOption<T> instance()
      Returns the singleton NullOption instance.
      Type Parameters:
      T - Generic type of the returned option.
      Returns:
      The singleton NullOption instance.

    • valueEquals

      public boolean valueEquals​(@Nullable @Nullable Object value)
      Description copied from interface: Option
      Returns whether the value wrapped by this option equals the given input value.

      For empty options, this method will always return false.

      Specified by:
      valueEquals in interface Option<T>
      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.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals​(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.