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:
Wrapped<T>
Direct Known Subclasses:
Err, Ok
public abstract class Result<T,E> extends Object implements Wrapped<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
    abstract <U> Result<U,E>
    and(Result<U,E> res)
    Returns res if the result is Ok, otherwise returns the Err value of this.
    abstract <U> Result<U,E>
    andThen(Function<T,Result<U,E>> res)
    Like and(Result) but lazily evaluated.
    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, E extends Throwable>
    @NotNull Result<T,E>
    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.
    abstract 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 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, E extends Throwable> @NotNull Result<T,E> 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.
      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.
      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

    • 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)

    • orElse

      public abstract 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

    • 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

    • 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)

    • and

      public abstract <U> Result<U,E> and(Result<U,E> res)
      Returns res if the result is Ok, otherwise returns the Err value of this.
      Arguments passed to and are eagerly evaluated; if you are passing the result of a function call, it is recommended to use andThen(Function), which is lazily evaluated.
      Type Parameters:
      U - The type of the other result (if Ok)
      Parameters:
      res - The other result
      Returns:
      res if this is Ok, this error otherwise
      See Also:

    • andThen

      public abstract <U> Result<U,E> andThen(Function<T,Result<U,E>> res)
      Like and(Result) but lazily evaluated. The function is supplied the current value of the result if it's Ok
      Type Parameters:
      U - The type of the other result (if Ok)
      Parameters:
      res - The other result
      Returns:
      res if this is Ok, this error otherwise
      See Also:

    • 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