Interface Option<Value>

Type Parameters:
Value - The type of the optional value.
All Known Implementing Classes:
Option.None, Option.Some
public sealed interface Option<Value> permits Option.Some<Value>, Option.None<Value>
A sealed interface representing an optional value with two possible states: either a value is present ("Some") or absent ("None").

This interface provides a flexible alternative to Optional, integrating functional-style operations for working with optional values in a more expressive and composable manner.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Option.None<Value>
    Represents a variant of the Option type that signifies the absence of a value.
    static final record 
    Option.Some<Value>
    Represents a container object that holds a non-null value.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <V> List<V>
    collectPresent(Stream<Option<V>> options)
    Collects all present (non-empty) values from a stream of Option instances into a list.
    default Option<Value>
    filter(Predicate<? super Value> predicate)
    Filters the value of this Option based on the provided predicate.
    default <NewValue> Option<NewValue>
    flatMap(Function<? super Value, Option<NewValue>> mapper)
    Transforms the current Option value using the provided mapping function and flattens the result.
    default <Folded> Folded
    fold(Supplier<? extends Folded> onNone, Function<? super Value, ? extends Folded> onSome)
    Folds the current option into a single value by applying the appropriate function depending on whether the option is a Some or a None.
    static <V> Option<V>
    fromOptional(Optional<V> optional)
    Converts a given Optional instance into an Option instance.
    static <V,E> Option<V>
    fromResult(Result<? extends V, ? extends E> result)
    Converts a Result into an Option.
    static <V> Option<V>
    fromTry(Try<? extends V> t)
    Converts a Try instance into an Option.
    default Value
    get()
    Retrieves the value held by this Option instance if it is of type Some.
    default Value
    getOrElse(Value fallback)
    Retrieves the encapsulated value if this Option instance is of type Some, or returns the provided fallback value if this instance is of type None.
    default Value
    getOrElseGet(Supplier<? extends Value> fallbackSupplier)
    Retrieves the encapsulated value if this Option instance is of type Some, or computes and returns a fallback value supplied by the given fallbackSupplier if this instance is of type None.
    default Value
    getOrNull()
    Retrieves the encapsulated value if this Option instance is of type Some, or returns null if this instance is of type None.
    default Value
    getOrThrow(Supplier<? extends RuntimeException> exceptionSupplier)
    Retrieves the encapsulated value if this Option instance is of type Some.
    default boolean
    isDefined()
    Determines whether this instance represents a defined value.
    default boolean
    isEmpty()
    Checks if this Option instance represents the absence of a value.
    default <NewValue> Option<NewValue>
    map(Function<? super Value, ? extends NewValue> mapper)
    Transforms the current Option using the provided mapping function.
    static <A,B,R> Option<R>
    map2(Option<? extends A> a, Option<? extends B> b, BiFunction<? super A, ? super B, ? extends R> combiner)
    Combines the values of two Option instances using the provided combiner function.
    default void
    match(Runnable onNone, Consumer<? super Value> onSome)
    Executes one of the provided actions based on the state of this value.
    static <V> Option<V>
    none()
    Creates an instance of Option that represents the absence of a value.
    static <V> Option<V>
    ofNullable(V value)
    Creates an Option instance that encapsulates a given value.
    default Option<Value>
    peek(Consumer<? super Value> action)
    Applies the provided action to the value contained in this instance if it is of type Some.
    static <V> Collector<Option<? extends V>, ?, List<V>>
    presentValuesToList()
    Creates a collector that transforms a stream of Option objects into a list of values by extracting the present values and filtering out any absent values.
    static <V> Option<List<V>>
    sequence(Iterable<Option<V>> options)
    Transforms an iterable of Option<V> into a single Option<List<V>>.
    static <V> Option<List<V>>
    sequence(Stream<Option<V>> options)
    Converts a stream of Option objects into a single Option containing a List of values, if all Option instances in the stream are Option.Some.
    static <V> Option<V>
    some(V value)
    Creates a Option.Some instance that encapsulates the given non-null value.
    default Stream<Value>
    stream()
    Returns a stream representation of the current instance.
    default Optional<Value>
    toOptional()
    Converts the current instance of a value or none container into an Optional.
    default <TError> Result<Value,TError>
    toResult(TError errorIfNone)
    Converts the current option to a Result instance.
    default Try<Value>
    toTry(Supplier<? extends Throwable> exceptionSupplier)
    Converts the current instance to a Try instance.
    static <A,B> Option<List<B>>
    traverse(Iterable<A> values, Function<? super A, Option<B>> mapper)
    Transforms a collection of values of type A into an optional list of values of type B by applying a given mapping function to each element in the input collection.
    static <A,B> Option<List<B>>
    traverse(Stream<A> values, Function<? super A, Option<B>> mapper)
    Transforms a stream of values by applying a mapper function that returns an Option for each input value.
    static <A,B> Option<Tuple2<A,B>>
    zip(Option<? extends A> a, Option<? extends B> b)
    Combines two Option instances into a single Option containing a Tuple2 of the values if both options are non-empty.
    default <B> Option<Tuple2<Value,B>>
    zip(Option<? extends B> other)
    Combines the current Option instance with another Option instance into a single Option containing a Tuple2 of their values, if both options are non-empty.
    default <B,R> Option<R>
    zipWith(Option<? extends B> other, BiFunction<? super Value, ? super B, ? extends R> combiner)
    Combines the values of this Option with the values of another Option using a provided combining function.

  • Method Details

    • some

      static <V> Option<V> some(V value)
      Creates a Option.Some instance that encapsulates the given non-null value. Use ofNullable(Object) if the value may be null.
      Type Parameters:
      V - the type of the value to encapsulate
      Parameters:
      value - the non-null value to encapsulate
      Returns:
      a Some<V> wrapping the provided value
      Throws:
      NullPointerException - if value is null (enforced by Some(Object))

    • none

      static <V> Option<V> none()
      Creates an instance of Option that represents the absence of a value.
      Type Parameters:
      V - the type of the value that would be held by the Option, if present
      Returns:
      an Option instance that signifies no value is present

    • ofNullable

      static <V> Option<V> ofNullable(V value)
      Creates an Option instance that encapsulates a given value. If the value is null, it returns a None instance.
      Type Parameters:
      V - the type of the value to encapsulate
      Parameters:
      value - the value to be encapsulated; if null, a None instance is returned
      Returns:
      an Option containing the provided value if it is non-null, or a None instance if the value is null

    • fromOptional

      static <V> Option<V> fromOptional(Optional<V> optional)
      Converts a given Optional instance into an Option instance.
      Type Parameters:
      V - the type of the value that may be present in the Optional
      Parameters:
      optional - the Optional to be converted; if the Optional contains a value, a Some instance is returned, otherwise a None instance is returned
      Returns:
      an Option containing the value from the Optional if it is present, or an empty None instance if the Optional is empty

    • isDefined

      default boolean isDefined()
      Determines whether this instance represents a defined value.
      Returns:
      true if this instance is of type Some<?> and holds a value; false if it is of type None and does not hold a value.

    • isEmpty

      default boolean isEmpty()
      Checks if this Option instance represents the absence of a value.
      Returns:
      true if this instance is of type None<?>, indicating no value is present; false if this instance holds a value.

    • get

      default Value get()
      Retrieves the value held by this Option instance if it is of type Some. If the instance is of type None, a NoSuchElementException is thrown.
      Returns:
      the encapsulated value if this is an instance of Some
      Throws:
      NoSuchElementException - if this is an instance of None, indicating no value is present

    • getOrElse

      default Value getOrElse(Value fallback)
      Retrieves the encapsulated value if this Option instance is of type Some, or returns the provided fallback value if this instance is of type None.
      Parameters:
      fallback - the value to return if this instance is None
      Returns:
      the encapsulated value if this instance is a Some, or the specified fallback value if this instance is None

    • getOrElseGet

      default Value getOrElseGet(Supplier<? extends Value> fallbackSupplier)
      Retrieves the encapsulated value if this Option instance is of type Some, or computes and returns a fallback value supplied by the given fallbackSupplier if this instance is of type None.
      Parameters:
      fallbackSupplier - a Supplier that provides a fallback value if this instance represents the absence of a value
      Returns:
      the encapsulated value if this instance is a Some, or the fallback value computed by the fallbackSupplier if this instance is a None

    • getOrNull

      default Value getOrNull()
      Retrieves the encapsulated value if this Option instance is of type Some, or returns null if this instance is of type None.
      Returns:
      the encapsulated value if this instance is a Some, or null if this instance is a None.

    • getOrThrow

      default Value getOrThrow(Supplier<? extends RuntimeException> exceptionSupplier)
      Retrieves the encapsulated value if this Option instance is of type Some. If the instance is of type None, it throws an exception provided by the given exceptionSupplier.
      Parameters:
      exceptionSupplier - a Supplier that provides the exception to be thrown if this instance is of type None
      Returns:
      the encapsulated value if this instance is of type Some
      Throws:
      RuntimeException - if this instance is of type None, using the exception provided by exceptionSupplier

    • map

      default <NewValue> Option<NewValue> map(Function<? super Value, ? extends NewValue> mapper)
      Transforms the current Option using the provided mapping function. If the current Option is a Some, applies the provided mapper to its value. If the current Option is a None, returns None without applying the mapper.
      Type Parameters:
      NewValue - the type of the value in the resulting Option after transformation
      Parameters:
      mapper - the function to apply to the value if this Option is a Some
      Returns:
      a new Option containing the mapped value if this is a Some, or None if this is a None

    • flatMap

      default <NewValue> Option<NewValue> flatMap(Function<? super Value, Option<NewValue>> mapper)
      Transforms the current Option value using the provided mapping function and flattens the result. If the Option is empty (None), it remains empty. Otherwise, it applies the mapping function to the encapsulated value and returns the resulting Option.
      Type Parameters:
      NewValue - the type of the element contained in the resulting Option
      Parameters:
      mapper - the function to apply to the encapsulated value, which produces a new Option
      Returns:
      a new Option resulting from applying the mapping function and flattening
      Throws:
      NullPointerException - if the mapping function returns null

    • filter

      default Option<Value> filter(Predicate<? super Value> predicate)
      Filters the value of this Option based on the provided predicate. If this Option is a Some and the predicate evaluates to true, the Option is returned as-is. If the predicate evaluates to false, or this Option is a None, an empty Option is returned.
      Parameters:
      predicate - the predicate used to test the value inside this Option
      Returns:
      an Option containing the value if the predicate evaluates to true, otherwise an empty Option

    • peek

      default Option<Value> peek(Consumer<? super Value> action)
      Applies the provided action to the value contained in this instance if it is of type Some.
      Parameters:
      action - a Consumer that performs an operation on the contained value
      Returns:
      this instance after applying the provided action

    • fold

      default <Folded> Folded fold(Supplier<? extends Folded> onNone, Function<? super Value, ? extends Folded> onSome)
      Folds the current option into a single value by applying the appropriate function depending on whether the option is a Some or a None.
      Type Parameters:
      Folded - The type of the resulting value after folding.
      Parameters:
      onNone - A supplier to provide a value in case the option is None.
      onSome - A function to transform the value in case the option is Some.
      Returns:
      The folded value of type Folded resulting from applying the appropriate supplier or function.

    • match

      default void match(Runnable onNone, Consumer<? super Value> onSome)
      Executes one of the provided actions based on the state of this value. If the value is "Some", the provided consumer is executed with the inner value. If the value is "None", the provided runnable is executed.
      Parameters:
      onNone - the action to execute if the value is "None"
      onSome - the consumer to execute if the value is "Some", accepting the inner value

    • stream

      default Stream<Value> stream()
      Returns a stream representation of the current instance. If the instance is of type Some<Value>, the stream contains the value. If the instance is of type None<Value>, the stream is empty.

      Java 9+ Optional has stream(); this mirrors that. - Some(v) -> Stream.of(v) - None -> Stream.empty()

      Returns:
      a stream containing the value if present, or an empty stream if no value exists

    • toOptional

      default Optional<Value> toOptional()
      Converts the current instance of a value or none container into an Optional.
      Returns:
      an Optional containing the value if the instance is of type Some, or an empty Optional if the instance is of type None.

    • collectPresent

      static <V> List<V> collectPresent(Stream<Option<V>> options)
      Collects all present (non-empty) values from a stream of Option instances into a list.

      Equivalent to stream.flatMap(Option::stream).collect(toList()).

      Type Parameters:
      V - the type of the values inside the Option instances
      Parameters:
      options - a stream of Option instances
      Returns:
      a list containing all present values from the provided stream

    • presentValuesToList

      static <V> Collector<Option<? extends V>, ?, List<V>> presentValuesToList()
      Creates a collector that transforms a stream of Option objects into a list of values by extracting the present values and filtering out any absent values.
      Type Parameters:
      V - the type of the values inside the Option objects
      Returns:
      a Collector that collects present values into a List

    • sequence

      static <V> Option<List<V>> sequence(Iterable<Option<V>> options)
      Transforms an iterable of Option<V> into a single Option<List<V>>. If any element in the input iterable is None, this method returns Option.none(). If all elements are Some, the result is Option.some() containing a list of values.
      Type Parameters:
      V - The type of the values wrapped in the Option.
      Parameters:
      options - An iterable containing Option<V> elements to be transformed.
      Returns:
      Option.some() containing a list of values if all elements are Some, or Option.none() if any element is None.
      Throws:
      NullPointerException - If the options iterable is null or contains null elements.

    • sequence

      static <V> Option<List<V>> sequence(Stream<Option<V>> options)
      Converts a stream of Option objects into a single Option containing a List of values, if all Option instances in the stream are Option.Some. If the stream contains any Option.None, the result will be none().
      Type Parameters:
      V - the type of elements contained in the Option instances
      Parameters:
      options - a stream of Option elements to be sequenced
      Returns:
      an Option containing a List of values if all elements are Option.Some, or none() if any element in the stream is Option.None
      Throws:
      NullPointerException - if the stream or any of its elements is null

    • traverse

      static <A,B> Option<List<B>> traverse(Iterable<A> values, Function<? super A, Option<B>> mapper)
      Transforms a collection of values of type A into an optional list of values of type B by applying a given mapping function to each element in the input collection. If the mapping function returns a None for any element, this method returns Option.none().
      Type Parameters:
      A - the type of the elements in the input collection
      B - the type of the elements in the resulting optional list
      Parameters:
      values - the collection of input values to be transformed, must not be null
      mapper - the mapping function to apply to each element in the input collection, must not return null or Option.none() for valid outputs
      Returns:
      an Option containing a list of transformed values if all transformations succeed, or Option.none() if the mapping function produces a None for any element
      Throws:
      NullPointerException - if values or mapper is null, or if the mapping function returns null

    • traverse

      static <A,B> Option<List<B>> traverse(Stream<A> values, Function<? super A, Option<B>> mapper)
      Transforms a stream of values by applying a mapper function that returns an Option for each input value. If the mapper function returns None for any value, the entire result is None. Otherwise, returns a Some wrapping a list of mapped values.
      Type Parameters:
      A - the type of the input elements in the stream
      B - the type of the elements in the output List
      Parameters:
      values - the stream of input values to traverse
      mapper - the mapping function to transform each input value into an Option of the output type
      Returns:
      an Option containing a List of transformed values if all inputs are successfully mapped, or None if the mapper returns None for any value
      Throws:
      NullPointerException - if values or mapper is null, or if the mapper function returns null for any input

    • toResult

      default <TError> Result<Value,TError> toResult(TError errorIfNone)
      Converts the current option to a Result instance.
      Type Parameters:
      TError - the type of the error value.
      Parameters:
      errorIfNone - the error value to use if the current option is None.
      Returns:
      a Result containing the value if this is Some, or an error if this is None.

    • toTry

      default Try<Value> toTry(Supplier<? extends Throwable> exceptionSupplier)
      Converts the current instance to a Try instance.
      Parameters:
      exceptionSupplier - a supplier that provides the exception to be used when the current instance is None.
      Returns:
      a Try instance containing the value if the current instance is Some, or a failed Try with the supplied exception if the current instance is None.

    • fromResult

      static <V,E> Option<V> fromResult(Result<? extends V, ? extends E> result)
      Converts a Result into an Option.

      If the given result represents a successful value (i.e., isOk() returns true), the value is wrapped in an Option. Otherwise, Option.none() is returned.

      Type Parameters:
      V - the type of the value contained in the result
      E - the type of the error contained in the result
      Parameters:
      result - the Result to be converted, must not be null
      Returns:
      an Option containing the value from the result if it is successful, or an Option.none() if the result contains an error

    • fromTry

      static <V> Option<V> fromTry(Try<? extends V> t)
      Converts a Try instance into an Option. If the Try is successful, the resulting Option contains the value. If the Try is a failure, the resulting Option is empty.
      Type Parameters:
      V - the type of the value contained in the Try
      Parameters:
      t - the Try instance to convert, must not be null
      Returns:
      an Option containing the value if the Try is successful, or an empty Option if it is a failure

    • zip

      default <B> Option<Tuple2<Value,B>> zip(Option<? extends B> other)
      Combines the current Option instance with another Option instance into a single Option containing a Tuple2 of their values, if both options are non-empty.
      Type Parameters:
      B - the type of the value contained in the other Option
      Parameters:
      other - the other Option to combine with
      Returns:
      an Option containing a Tuple2 of the values from both options if both are non-empty, otherwise an empty Option

    • zipWith

      default <B,R> Option<R> zipWith(Option<? extends B> other, BiFunction<? super Value, ? super B, ? extends R> combiner)
      Combines the values of this Option with the values of another Option using a provided combining function.
      Type Parameters:
      B - the type of the value contained in the other Option
      R - the type of the result produced by the combining function
      Parameters:
      other - the other Option to combine with
      combiner - the function to combine the values from this Option and the other Option
      Returns:
      an Option containing the result of applying the combining function to the values, or an empty Option if either this Option or the other Option is empty

    • zip

      static <A,B> Option<Tuple2<A,B>> zip(Option<? extends A> a, Option<? extends B> b)
      Combines two Option instances into a single Option containing a Tuple2 of the values if both options are non-empty. If either option is empty, returns an empty Option.

      zip: Option<A> + Option<B> -> Option<Tuple2<A,B>>

      Type Parameters:
      A - the type of the value in the first Option
      B - the type of the value in the second Option
      Parameters:
      a - the first Option instance, must not be null
      b - the second Option instance, must not be null
      Returns:
      an Option containing a Tuple2 of the values if both options are non-empty, otherwise an empty Option
      Throws:
      NullPointerException - if either a or b is null

    • map2

      static <A,B,R> Option<R> map2(Option<? extends A> a, Option<? extends B> b, BiFunction<? super A, ? super B, ? extends R> combiner)
      Combines the values of two Option instances using the provided combiner function. If either Option is empty (None), the result is an empty Option. If both Options contain values, the combiner function is applied and the result is wrapped in an Option.
      Type Parameters:
      A - the type of the value contained in the first Option
      B - the type of the value contained in the second Option
      R - the type of the value contained in the resulting Option
      Parameters:
      a - the first Option, which may or may not contain a value
      b - the second Option, which may or may not contain a value
      combiner - the function used to combine the values of a and b if both are present
      Returns:
      an Option containing the result of applying the combiner function to the values of a and b, or an empty Option if either a or b is empty