Interface Result<Value,Error>

Type Parameters:
Value - the type of the value contained in a successful result
Error - the type of the error contained in an erroneous result
All Known Implementing Classes:
Result.Err, Result.Ok
@NullMarked public sealed interface Result<Value,Error> permits Result.Ok<Value,Error>, Result.Err<Value,Error>
A generic sealed interface representing a result type that can either be a successful value (Result.Ok) or an error (Result.Err). This is a common functional programming construct that allows for handling both success and error cases in a unified type.

This interface is NullMarked: all types are non-null by default. Ok.value is guaranteed non-null; use Option inside the value type to model an optional successful result.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Result.Err<Value,Error>
    Represents an erroneous result containing an error of type Error.
    static final record 
    Result.Ok<Value,Error>
    Represents a successful result containing a value of type Value.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <Value,Error>
    Result<Value,Error>
    err(Error error)
    Creates a Result instance representing an erroneous result with the given error value.
    static <Value,Error>
    Result<Value,Error>
    err(Error error, Class<Value> classValueIgnored)
    Deprecated, for removal: This API element is subject to removal in a future version.
    This overload exists only as a type-inference aid and is no longer needed.
    default Result<Value,Error>
    filter(Predicate<Value> predicate, Error errorIfFalse)
    Filters the current result based on the specified predicate.
    default Result<Value,Error>
    filter(Predicate<Value> predicate, Function<Value,Error> errorIfFalse)
    Filters the current result by applying a given predicate to its value.
    default <NewValue> Result<NewValue,Error>
    flatMap(Function<Value, Result<NewValue,Error>> mapper)
    Applies the given mapping function to the value of a successful Result instance and returns the resulting Result.
    default <E2> Result<Value,E2>
    flatMapError(Function<Error, Result<Value,E2>> mapper)
    Applies a function to the error of an erroneous result and returns the produced Result.
    default <Folded> Folded
    fold(Function<Value,Folded> onSuccess, Function<Error,Folded> onError)
    Transforms the current Result instance into a value of type Folded by applying one of the provided functions based on the state of the instance.
    static <V,E> Result<V,E>
    fromOption(Option<? extends V> opt, E errorIfNone)
    Converts an Option to a Result.
    static <V> Result<V, Throwable>
    fromTry(Try<V> t)
    Converts a Try instance into a Result instance.
    default Value
    get()
    Retrieves the value contained within this Result instance if it represents a successful result.
    default Error
    getError()
    Retrieves the error value of the current instance if it is an Err.
    default Value
    getOrElse(Value fallback)
    Returns the value contained in this Result instance if it represents a successful result.
    default Value
    getOrElseGet(Supplier<Value> fallbackSupplier)
    Retrieves the value contained within this Result instance if it represents a successful result.
    default Value
    getOrElseGetWithError(Function<Error,Value> errorMapper)
    Returns the value of this Ok, or applies errorMapper to the contained error and returns the result.
    default @Nullable Value
    getOrNull()
    Retrieves the value contained within this Result instance if it represents a successful result, or returns null if it represents an erroneous result.
    default Value
    getOrThrow(Function<Error, ? extends RuntimeException> exceptionMapper)
    Retrieves the value of the current Result instance if it represents a successful result, or throws a custom exception mapped from the contained error if it represents an erroneous result.
    default boolean
    isError()
    Checks if the current instance represents an erroneous result.
    default boolean
    isOk()
    Checks if the current instance represents a successful result.
    default <NewValue> Result<NewValue,Error>
    map(Function<Value,NewValue> mapper)
    Transforms the value of a successful Result instance using the provided mapping function.
    default <NewError> Result<Value,NewError>
    mapError(Function<Error,NewError> mapper)
    Transforms the error value of an erroneous Result instance using the provided mapping function.
    default void
    match(Consumer<Value> onSuccess, Consumer<Error> onError)
    Executes one of the provided Consumer functions based on the state of the Result.
    static <Value,Error>
    Result<Value,Error>
    ok(Value value)
    Creates a Result instance representing a successful result with the given value.
    static <Value,Error>
    Result<Value,Error>
    ok(Value value, Class<Error> errorClassIgnored)
    Deprecated, for removal: This API element is subject to removal in a future version.
    This overload exists only as a type-inference aid and is no longer needed.
    default Result<Value,Error>
    or(Supplier<Result<Value,Error>> fallback)
    Returns this Result if it is Ok; otherwise evaluates the given supplier and returns its result.
    default Result<Value,Error>
    peek(Consumer<Value> action)
    Executes the given action if the current Result instance represents a successful result.
    default Result<Value,Error>
    peekError(Consumer<Error> action)
    Executes the given action if the current Result instance represents an erroneous result.
    default Result<Value,Error>
    recover(Function<Error,Value> rescue)
    Converts an erroneous Result into a successful one by applying the given rescue function to the contained error.
    default <E2> Result<Value,E2>
    recoverWith(Function<Error, Result<Value,E2>> rescue)
    Converts an erroneous Result into a new Result by applying the given rescue function to the contained error.
    static <V,E> Result<List<V>,E>
    sequence(Iterable<Result<V,E>> results)
    Transforms an iterable of Result<V, E> into a single Result<List<V>, E>.
    static <V,E> Result<List<V>,E>
    sequence(Stream<Result<V,E>> results)
    Transforms a stream of Result<V, E> into a single Result<List<V>, E>.
    default Result<Error,Value>
    swap()
    Swaps the Ok and Err channels of this Result.
    default Option<Value>
    toOption()
    Converts the current instance into an Option<Value>.
    default Try<Value>
    toTry(Function<? super Error, ? extends Throwable> errorToThrowable)
    Converts the current result into a Try instance.
    static <A,B,E> Result<List<B>,E>
    traverse(Iterable<A> values, Function<? super A, Result<B,E>> mapper)
    Maps each element of an iterable through mapper and collects the results into a Result<List<B>, E>.
    static <A,B,E> Result<List<B>,E>
    traverse(Stream<A> values, Function<? super A, Result<B,E>> mapper)
    Maps each element of a stream through mapper and collects the results into a Result<List<B>, E>.

  • Method Details

    • ok

      static <Value,Error> Result<Value,Error> ok(Value value)
      Creates a Result instance representing a successful result with the given value. This method is used to indicate that a computation or action has succeeded.
      Type Parameters:
      Value - the type of the value contained in the successful result
      Error - the type of the error that would be contained in an erroneous result
      Parameters:
      value - the non-null value to encapsulate in the successful result
      Returns:
      a Result instance of type Ok<Value, Error> containing the provided value
      Throws:
      NullPointerException - if value is null

    • ok

      @Deprecated(forRemoval=true) static <Value,Error> Result<Value,Error> ok(Value value, Class<Error> errorClassIgnored)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This overload exists only as a type-inference aid and is no longer needed. Use ok(Object) with an explicit type witness or a typed variable instead: Result.<Value, Error>ok(value) or Result<Value, Error> r = Result.ok(value)
      Creates an instance of Ok representing a successful result.
      Type Parameters:
      Value - the type of the value in the success case
      Error - the type of the error in the error case
      Parameters:
      value - the value to be wrapped in the Ok instance
      errorClassIgnored - the class object of the error type, ignored in this method
      Returns:
      an Ok instance containing the provided value

    • err

      static <Value,Error> Result<Value,Error> err(Error error)
      Creates a Result instance representing an erroneous result with the given error value. This method is used to indicate that a computation or action has failed.
      Type Parameters:
      Value - the type of the value that would be contained in a successful result, unused here
      Error - the type of the error contained in the erroneous result
      Parameters:
      error - the non-null error value to encapsulate in the erroneous result
      Returns:
      a Result instance of type Err<Value, Error> containing the provided error
      Throws:
      NullPointerException - if error is null

    • err

      @Deprecated(forRemoval=true) static <Value,Error> Result<Value,Error> err(Error error, Class<Value> classValueIgnored)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This overload exists only as a type-inference aid and is no longer needed. Use err(Object) with an explicit type witness or a typed variable instead: Result.<Value, Error>err(error) or Result<Value, Error> r = Result.err(error)
      Creates and returns a new result instance representing an error state.
      Type Parameters:
      Value - The type of the value that would have been contained in a success state.
      Error - The type of the error being represented.
      Parameters:
      error - The error to be encapsulated in the result.
      classValueIgnored - The ignored class type of the value, typically used for type inference.
      Returns:
      A result instance representing an error state containing the provided error.

    • isError

      default boolean isError()
      Checks if the current instance represents an erroneous result.
      Returns:
      true if the current instance is of type Err, indicating an error; false otherwise.

    • isOk

      default boolean isOk()
      Checks if the current instance represents a successful result.
      Returns:
      true if the current instance is of type Ok, indicating success; false otherwise.

    • get

      default Value get()
      Retrieves the value contained within this Result instance if it represents a successful result. If the instance represents an erroneous result, this method throws a NoSuchElementException.
      Returns:
      the non-null value contained in the successful result
      Throws:
      NoSuchElementException - if the instance represents an erroneous result

    • getError

      default Error getError()
      Retrieves the error value of the current instance if it is an Err. If the instance is an Ok, calling this method will throw a NoSuchElementException.
      Returns:
      the error value of the instance if it is an Err.
      Throws:
      NoSuchElementException - if the instance is an Ok.

    • map

      default <NewValue> Result<NewValue,Error> map(Function<Value,NewValue> mapper)
      Transforms the value of a successful Result instance using the provided mapping function. If the Result instance represents an error, the error remains unchanged.
      Type Parameters:
      NewValue - the type of the value after applying the mapping function
      Parameters:
      mapper - the function to apply to the value of the successful result
      Returns:
      a new Result instance, containing the mapped value if the original instance was successful, or the same error if the original instance was an error

    • mapError

      default <NewError> Result<Value,NewError> mapError(Function<Error,NewError> mapper)
      Transforms the error value of an erroneous Result instance using the provided mapping function. If the Result instance represents success, the value remains unchanged.
      Type Parameters:
      NewError - the type of the error after applying the mapping function
      Parameters:
      mapper - the function to apply to the error of the erroneous result
      Returns:
      a new Result instance, containing the transformed error if the original instance was an error, or the same value if the original instance was successful

    • flatMap

      default <NewValue> Result<NewValue,Error> flatMap(Function<Value, Result<NewValue,Error>> mapper)
      Applies the given mapping function to the value of a successful Result instance and returns the resulting Result. If the instance represents an error, the error is propagated without applying the mapping function.
      Type Parameters:
      NewValue - the type of the value in the resulting Result after applying the mapping function
      Parameters:
      mapper - the function to apply to the value of the successful Result to produce a new Result
      Returns:
      a new Result instance returned by applying the mapping function to the value if the original instance was successful, or the same error if the original instance was an error

    • match

      default void match(Consumer<Value> onSuccess, Consumer<Error> onError)
      Executes one of the provided Consumer functions based on the state of the Result. If this instance represents a successful result (of type Ok), the onSuccess function will be executed with the value contained in the result. If this instance represents an erroneous result (of type Err), the onError function will be executed with the error contained in the result.
      Parameters:
      onSuccess - a Consumer that accepts the value contained in a successful result
      onError - a Consumer that accepts the error contained in an erroneous result

    • peek

      default Result<Value,Error> peek(Consumer<Value> action)
      Executes the given action if the current Result instance represents a successful result. If the instance is of type Ok, the provided action is applied to the contained value. In both cases, the original Result instance is returned unchanged.
      Parameters:
      action - a Consumer that accepts the value contained in a successful result
      Returns:
      the original Result instance

    • peekError

      default Result<Value,Error> peekError(Consumer<Error> action)
      Executes the given action if the current Result instance represents an erroneous result. If the instance is of type Err, the provided action is applied to the contained error value. In both cases, the original Result instance is returned unchanged.
      Parameters:
      action - a Consumer that accepts the error contained in an erroneous result
      Returns:
      the original Result instance

    • getOrElse

      default Value getOrElse(Value fallback)
      Returns the value contained in this Result instance if it represents a successful result. If the instance represents an erroneous result, the provided fallback value is returned instead.
      Parameters:
      fallback - the fallback value to return if this instance is an erroneous result
      Returns:
      the value contained in a successful result, or the fallback value if this instance represents an error

    • getOrElseGet

      default Value getOrElseGet(Supplier<Value> fallbackSupplier)
      Retrieves the value contained within this Result instance if it represents a successful result. If the instance represents an erroneous result, the value provided by the given Supplier is returned instead.
      Parameters:
      fallbackSupplier - a Supplier that provides the fallback value to use if this instance represents an error
      Returns:
      the value contained in a successful result, or the value provided by fallbackSupplier if this instance represents an error

    • getOrThrow

      default Value getOrThrow(Function<Error, ? extends RuntimeException> exceptionMapper)
      Retrieves the value of the current Result instance if it represents a successful result, or throws a custom exception mapped from the contained error if it represents an erroneous result.
      Parameters:
      exceptionMapper - a function that maps the error value of an erroneous result to a RuntimeException to be thrown
      Returns:
      the value contained in the successful result
      Throws:
      RuntimeException - the exception produced by exceptionMapper if the instance represents an error

    • getOrNull

      default @Nullable Value getOrNull()
      Retrieves the value contained within this Result instance if it represents a successful result, or returns null if it represents an erroneous result.
      Returns:
      the value contained in the successful result, or null if this instance represents an error

    • fold

      default <Folded> Folded fold(Function<Value,Folded> onSuccess, Function<Error,Folded> onError)
      Transforms the current Result instance into a value of type Folded by applying one of the provided functions based on the state of the instance. If the current instance represents a successful result (of type Ok), the onSuccess function is applied to the contained value. If the current instance represents an erroneous result (of type Err), the onError function is applied to the contained error.
      Type Parameters:
      Folded - the type of the value returned by the provided functions
      Parameters:
      onSuccess - a function to apply to the value of a successful result
      onError - a function to apply to the error of an erroneous result
      Returns:
      the result of applying the appropriate function, as a value of type Folded

    • filter

      default Result<Value,Error> filter(Predicate<Value> predicate, Error errorIfFalse)
      Filters the current result based on the specified predicate. If the result is an instance of Ok and the predicate returns false for the value, a new error result is returned with the specified error value. If the current result does not match Ok or the predicate evaluates to true, the current result is returned unchanged.
      Parameters:
      predicate - the condition to test the value of the result
      errorIfFalse - the error to return if the predicate evaluates to false
      Returns:
      the current result if it is not an Ok instance or the predicate evaluates to true, otherwise a new error result with the specified error value

    • filter

      default Result<Value,Error> filter(Predicate<Value> predicate, Function<Value,Error> errorIfFalse)
      Filters the current result by applying a given predicate to its value. If the result is of type Ok and the predicate evaluates to false, the method transforms it into an Err with the error provided by the errorIfFalse function. If the predicate evaluates to true or the result is already of type Err, the original result is returned.
      Parameters:
      predicate - the condition to be evaluated on the value wrapped by the Ok result.
      errorIfFalse - a function to generate an error if the predicate evaluates to false.
      Returns:
      a filtered result, returning the same instance if the predicate evaluates to true or the result is Err; otherwise, returns an Err with the provided error value.

    • recover

      default Result<Value,Error> recover(Function<Error,Value> rescue)
      Converts an erroneous Result into a successful one by applying the given rescue function to the contained error. If this instance is already Ok, it is returned unchanged.
      Parameters:
      rescue - a function that maps the error value to a recovery value; must not return null
      Returns:
      an Ok result with the recovered value, or the original Ok if already successful
      Throws:
      NullPointerException - if rescue is null or if rescue returns null

    • recoverWith

      default <E2> Result<Value,E2> recoverWith(Function<Error, Result<Value,E2>> rescue)
      Converts an erroneous Result into a new Result by applying the given rescue function to the contained error. Unlike recover(java.util.function.Function<Error, Value>), the rescue function may itself return an Err. If this instance is already Ok, it is returned as an Ok of the new error type.
      Type Parameters:
      E2 - the error type of the resulting Result
      Parameters:
      rescue - a function that maps the error to a new Result; must not return null
      Returns:
      the result of applying rescue to the error, or an Ok wrapping the original value
      Throws:
      NullPointerException - if rescue is null or if rescue returns null

    • or

      default Result<Value,Error> or(Supplier<Result<Value,Error>> fallback)
      Returns this Result if it is Ok; otherwise evaluates the given supplier and returns its result. The supplier is not called when this instance is Ok.
      Parameters:
      fallback - a lazy supplier of an alternative Result evaluated only on Err; must not return null
      Returns:
      this instance if Ok, or the result of fallback.get() if Err
      Throws:
      NullPointerException - if fallback is null or if fallback returns null

    • flatMapError

      default <E2> Result<Value,E2> flatMapError(Function<Error, Result<Value,E2>> mapper)
      Applies a function to the error of an erroneous result and returns the produced Result. If this instance is Ok, it is propagated unchanged (with a potentially different error type). This is the dual of flatMap(java.util.function.Function<Value, codes.domix.fun.Result<NewValue, Error>>): it operates on the error channel instead of the value channel.
      Type Parameters:
      E2 - the error type of the resulting Result
      Parameters:
      mapper - a function that maps the current error to a new Result; must not return null
      Returns:
      the mapped result for Err, or the original value wrapped as Ok for Ok
      Throws:
      NullPointerException - if mapper is null or if mapper returns null

    • swap

      default Result<Error,Value> swap()
      Swaps the Ok and Err channels of this Result. An Ok(value) becomes Err(value) and an Err(error) becomes Ok(error).
      Returns:
      a Result with the value and error channels exchanged

    • getOrElseGetWithError

      default Value getOrElseGetWithError(Function<Error,Value> errorMapper)
      Returns the value of this Ok, or applies errorMapper to the contained error and returns the result. Unlike getOrElseGet(Supplier), the fallback function receives the error value, which is useful for deriving a default from the error itself.

      This method is intentionally named differently from getOrElseGet(Supplier) to avoid overload ambiguity when passing a null literal or a Groovy/Kotlin closure.

      Parameters:
      errorMapper - a function that maps the error to a fallback value
      Returns:
      the contained value if Ok, or the result of errorMapper if Err

    • toOption

      default Option<Value> toOption()
      Converts the current instance into an Option<Value>. If the instance represents a successful result (Ok), the contained value is wrapped in an Option. If the instance represents an error (Err), an empty Option is returned.
      Returns:
      an Option<Value> containing the value if the instance is Ok, or an empty Option if the instance is Err.

    • toTry

      default Try<Value> toTry(Function<? super Error, ? extends Throwable> errorToThrowable)
      Converts the current result into a Try instance. If the current result represents a success, the returned Try will contain the success value. If the current result represents an error, the specified function is used to transform the error into a Throwable, and the resulting Try will represent a failure.
      Parameters:
      errorToThrowable - a Function that converts the error type to a Throwable. Must not return null.
      Returns:
      a Try instance representing a success or failure based on the state of the current result.
      Throws:
      NullPointerException - if errorToThrowable is null or if errorToThrowable.apply() returns null.

    • fromOption

      static <V,E> Result<V,E> fromOption(Option<? extends V> opt, E errorIfNone)
      Converts an Option to a Result.
      Type Parameters:
      V - The type of the value contained in the Option.
      E - The type of the error value used in the Result.
      Parameters:
      opt - The Option to convert. Must not be null.
      errorIfNone - The error value to return if the Option is empty.
      Returns:
      A Result that wraps the value from the Option if it is defined, or an error containing errorIfNone if the Option is empty.

    • fromTry

      static <V> Result<V, Throwable> fromTry(Try<V> t)
      Converts a Try instance into a Result instance.
      Type Parameters:
      V - the type of the value contained in the Try instance
      Parameters:
      t - the Try instance to be converted; must not be null
      Returns:
      a Result instance that represents either the success or failure of the given Try instance

    • sequence

      static <V,E> Result<List<V>,E> sequence(Iterable<Result<V,E>> results)
      Transforms an iterable of Result<V, E> into a single Result<List<V>, E>. If any element is an Err, that error is returned immediately (fail-fast). If all elements are Ok, returns Ok containing an unmodifiable list of values in encounter order.
      Type Parameters:
      V - the value type
      E - the error type
      Parameters:
      results - the iterable of results; must not be null and must not contain null elements
      Returns:
      Ok(List<V>) if all elements are Ok, or the first Err encountered
      Throws:
      NullPointerException - if results is null or contains a null element

    • sequence

      static <V,E> Result<List<V>,E> sequence(Stream<Result<V,E>> results)
      Transforms a stream of Result<V, E> into a single Result<List<V>, E>. If any element is an Err, that error is returned immediately (fail-fast) and the stream is closed. If all elements are Ok, returns Ok containing an unmodifiable list of values in encounter order.
      Type Parameters:
      V - the value type
      E - the error type
      Parameters:
      results - the stream of results; must not be null and must not contain null elements
      Returns:
      Ok(List<V>) if all elements are Ok, or the first Err encountered
      Throws:
      NullPointerException - if results is null or contains a null element

    • traverse

      static <A,B,E> Result<List<B>,E> traverse(Iterable<A> values, Function<? super A, Result<B,E>> mapper)
      Maps each element of an iterable through mapper and collects the results into a Result<List<B>, E>. Fails fast on the first Err returned by the mapper.
      Type Parameters:
      A - the input element type
      B - the mapped value type
      E - the error type
      Parameters:
      values - the iterable of input values; must not be null
      mapper - a function that maps each value to a Result; must not be null and must not return null
      Returns:
      Ok(List<B>) if all mappings succeed, or the first Err produced by the mapper
      Throws:
      NullPointerException - if values or mapper is null, or if the mapper returns null

    • traverse

      static <A,B,E> Result<List<B>,E> traverse(Stream<A> values, Function<? super A, Result<B,E>> mapper)
      Maps each element of a stream through mapper and collects the results into a Result<List<B>, E>. Fails fast on the first Err returned by the mapper; the stream is closed in all cases.
      Type Parameters:
      A - the input element type
      B - the mapped value type
      E - the error type
      Parameters:
      values - the stream of input values; must not be null
      mapper - a function that maps each value to a Result; must not be null and must not return null
      Returns:
      Ok(List<B>) if all mappings succeed, or the first Err produced by the mapper
      Throws:
      NullPointerException - if values or mapper is null, or if the mapper returns null