Package org.storynode.pigeon.result

Class Result<T,E>

java.lang.Object
org.storynode.pigeon.result.Result<T,E>
Type Parameters:
T - The type of the ok value
E - The type of the error value
All Implemented Interfaces:
SafelyWrapped<T>, Wrapped<T>
Direct Known Subclasses:
Err, Ok
public abstract class Result<T,E> extends Object implements SafelyWrapped<T>
A type representing the outcome of some operation, which value can be some value or some error but not neither nor both at the same time.

Examples

Known variant construction

An Ok result with the value "Hello world" 
 Result.ok("Hello world")
An Err result with the error value set to 45D 
 Result.err(45D)

Construct by execution

Construct a result with the outcome of a http request 
 Result.of(() -> httpGet("https://www.wikipedia.com")).map(Response:getBody)
This would result in an Err result with its error value set to the instance of the exception caught when running the provided function 
 Result.of(() -> 8 / 0)
Since:
1.0.0
Author:
Andrea Coronese

  • Constructor Summary

    Constructors
    Constructor
    Description
    Result()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object other)
    static <T, E> @NotNull Result<T,E>
    err(E error)
    Constructs an error variant of a Result
    static <T, E> @NotNull Result<T,E>
    error(E error)
    Constructs an error variant of a Result
    abstract <U> Result<U,E>
    flatMap(@NotNull Function<? super T,? extends Result<U,E>> fn)
    Like Option.map(Function) but does not re-wrap the result of the provided mapping function to a Result
    Result<T,E>
    ifError(Consumer<E> whenError)
    Executes the provided function if this contains an error
    Result<T,E>
    ifOk(Consumer<T> whenOk)
    Executes the provided function if this contains a value
    abstract Result<T,E>
    ifOkOrElse(Consumer<T> whenOk, Consumer<E> whenError)
    Executes whenOk if this contains a value, whenError otherwise.
    boolean
    isErr()
    Whether this Result is an error
    boolean
    isErrAnd(Predicate<E> predicate)
    Returns true if the result contains an error and that error satisfies a predicate
    abstract boolean
    isOk()
    Whether this Result is ok, meaning it contains a value and not an error
    boolean
    isOkAnd(Predicate<T> predicate)
    Returns true if the result contains a value and that value satisfies a predicate
    abstract <U> Result<U,E>
    map(@NotNull Function<? super T,? extends U> fn)
    Maps a Result<T, E> to Result<U, E> by applying a function to a contained value, leaving a result that contains an error untouched.
    abstract <U> Result<T,U>
    mapError(Function<? super E,? extends U> fn)
    Maps a Result<T, E> to Result<T, U> by applying a function to a contained error, leaving a result that contains a value untouched.
    static <T> @NotNull Result<T,? extends Throwable>
    of(ThrowingSupplier<T> fn)
    Constructs a new Result by using the provided function return value.
    static <T, E> @NotNull Result<T,E>
    ok(T inner)
    Constructs an ok variant of a Result.
    T
    orElse(T defaultValue)
    Unwraps the contained value, or returns a default one if this contains an error
    abstract T
    orElseGet(Supplier<T> defaultValueSupplier)
    Unwraps the contained value, or returns a default one if this contains an error
    Pair<T,E>
    toTuple()
    Converts this result to a Pair tuple having the value and the error as fields
    abstract @NotNull Option<T>
    tryUnwrap()
    The non-throwing variant of Wrapped.unwrap().
    abstract @NotNull Option<E>
    tryUnwrapError()
    The non-throwing variant of unwrapError().
    abstract T
    unwrap()
    Unwraps and return the inner value, if present.
    abstract E
    unwrapError()
    Unwraps and return the inner error, if present.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Result

      public Result()

  • Method Details

    • ok

      @Contract(value="_ -> new", pure=true) @NotNull public static <T, E> @NotNull Result<T,E> ok(@NotNull T inner)
      Constructs an ok variant of a Result.
      Type Parameters:
      T - The type of the ok value
      E - The type of the error value
      Parameters:
      inner - The value of the result for the ok state
      Returns:
      The constructed result

    • err

      @Contract(value="_ -> new", pure=true) @NotNull public static <T, E> @NotNull Result<T,E> err(@NotNull E error)
      Constructs an error variant of a Result
      Type Parameters:
      T - The type of the ok value
      E - The type of the error value
      Parameters:
      error - The value of the result for the error state
      Returns:
      The constructed result

    • error

      @Contract(value="_ -> new", pure=true) @NotNull public static <T, E> @NotNull Result<T,E> error(@NotNull E error)
      Constructs an error variant of a Result
      Type Parameters:
      T - The type of the ok value
      E - The type of the error value
      Parameters:
      error - The value of the result for the error state
      Returns:
      The constructed result

    • of

      @NotNull public static <T> @NotNull Result<T,? extends Throwable> of(ThrowingSupplier<T> fn)
      Constructs a new Result by using the provided function return value. If the supplier completes exceptionally, the Result will contain the caught exception as error
      Type Parameters:
      T - The type of the contained value
      Parameters:
      fn - The function to execute to obtain the value of the result
      Returns:
      A Result with a value or an error, depending on the function execution

    • isOk

      public abstract boolean isOk()
      Whether this Result is ok, meaning it contains a value and not an error
      Returns:
      true if this contains an ok value, false if it contains an error

    • unwrap

      public abstract T unwrap() throws UnwrapException
      Unwraps and return the inner value, if present. Throws an error if this result contains an error. If you need a non throwing version of this method use tryUnwrap()
      Specified by:
      unwrap in interface Wrapped<T>
      Returns:
      The inner value
      Throws:
      UnwrapException - if this contains an error

    • unwrapError

      public abstract E unwrapError()
      Unwraps and return the inner error, if present. Throws an error if this result contains a value. If you need a non throwing version of this method use [#tryUnwrapError()]
      Returns:
      The inner error

    • orElseGet

      public abstract T orElseGet(Supplier<T> defaultValueSupplier)
      Unwraps the contained value, or returns a default one if this contains an error
      Parameters:
      defaultValueSupplier - The supplier for the value to return in place of the error
      Returns:
      The contained value or the default one, depending on which is appropriate

    • tryUnwrap

      @NotNull public abstract @NotNull Option<T> tryUnwrap()
      The non-throwing variant of Wrapped.unwrap(). This is guaranteed to never throw and to always return a non-null value.

      The non-throwing variant of Wrapped.unwrap(). This is guaranteed to never throw and to always return a non-null value.

      Specified by:
      tryUnwrap in interface SafelyWrapped<T>
      Returns:
      An Option containing the value, or empty if there is none or if an error would be raised while unwrapping said value.

    • tryUnwrapError

      @NotNull public abstract @NotNull Option<E> tryUnwrapError()
      The non-throwing variant of unwrapError(). This is guaranteed to never throw and to always return a non-null value.
      Returns:
      An Option containing the error, or empty if there is none

    • map

      public abstract <U> Result<U,E> map(@NotNull @NotNull Function<? super T,? extends U> fn)
      Maps a Result<T, E> to Result<U, E> by applying a function to a contained value, leaving a result that contains an error untouched. This can be used to compose the result of two functions.

      Example

       Result.ok(2).map(Math:sqrt) // Gets the square root of two as a Result
      Type Parameters:
      U - The type of the new value
      Parameters:
      fn - The function to apply to the value
      Returns:
      The mapped Result

    • flatMap

      public abstract <U> Result<U,E> flatMap(@NotNull @NotNull Function<? super T,? extends Result<U,E>> fn)
      Like Option.map(Function) but does not re-wrap the result of the provided mapping function to a Result
      Type Parameters:
      U - The type of the mapped Ok value
      Parameters:
      fn - The mapping function to apply
      Returns:
      The mapped value

    • mapError

      public abstract <U> Result<T,U> mapError(Function<? super E,? extends U> fn)
      Maps a Result<T, E> to Result<T, U> by applying a function to a contained error, leaving a result that contains a value untouched. This can be used to compose the result of two functions
      Type Parameters:
      U - The type of the new error
      Parameters:
      fn - The function to apply to the error
      Returns:
      The mapped Result

    • ifOkOrElse

      public abstract Result<T,E> ifOkOrElse(Consumer<T> whenOk, Consumer<E> whenError)
      Executes whenOk if this contains a value, whenError otherwise.
      Parameters:
      whenOk - The function to execute when this contains a value
      whenError - The function to execute when this contains an error
      Returns:
      this instance (for chaining)

    • isOkAnd

      public boolean isOkAnd(Predicate<T> predicate)
      Returns true if the result contains a value and that value satisfies a predicate
      Parameters:
      predicate - The predicate to satisfy
      Returns:
      If the value is present and satisfies the predicate

    • isErr

      public boolean isErr()
      Whether this Result is an error
      Returns:
      true if this contains an error, false if it contains a value

    • isErrAnd

      public boolean isErrAnd(Predicate<E> predicate)
      Returns true if the result contains an error and that error satisfies a predicate
      Parameters:
      predicate - The predicate to satisfy
      Returns:
      If the error is present and satisfies the predicate

    • orElse

      public T orElse(T defaultValue)
      Unwraps the contained value, or returns a default one if this contains an error
      Parameters:
      defaultValue - The value to return in place of the error
      Returns:
      The contained value or the default one, depending on which is appropriate

    • ifOk

      public Result<T,E> ifOk(Consumer<T> whenOk)
      Executes the provided function if this contains a value
      Parameters:
      whenOk - The function to execute
      Returns:
      this instance (for chaining)

    • ifError

      public Result<T,E> ifError(Consumer<E> whenError)
      Executes the provided function if this contains an error
      Parameters:
      whenError - The function to execute
      Returns:
      this instance (for chaining)

    • toTuple

      public Pair<T,E> toTuple()
      Converts this result to a Pair tuple having the value and the error as fields
      Returns:
      The constructed tuple

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object