Result (Result Library API)

Type Parameters:

S - the type of the success value

F - the type of the failure value
```
public interface Result<S,F>
```
Encapsulates a single non-null value, representing the outcome of an operation that can either succeed or fail.
- Successful results hold a value of type S, indicating that the operation has completed as intended.
- Failed results hold a value of type F, indicating that the operation did not complete as intended.
The exact definitions of success and failure depend on the semantics of the operation.
Author:

Guillermo Calvo

See Also:

Introduction, Getting Started

API Note:

Result is primarily, but not only, intended for use as a method return type to handle anticipated failures without throwing exceptions or returning null.

Impl Spec:

This is a value-based type; use of identity-sensitive operations on instances of Result should be avoided.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this `Result`.
`Result<S,F>`	`filter(Predicate<? super S> isAcceptable, Function<? super S,? extends F> mapper)` Transforms this successful `Result` into a failed one, based on the given condition.
`<S2,F2> Result<S2,F2>`	`flatMap(Function<? super S,? extends Result<? extends S2,? extends F2>> successMapper, Function<? super F,? extends Result<? extends S2,? extends F2>> failureMapper)` Transforms this `Result` into a different one.
`<F2> Result<S,F2>`	`flatMapFailure(Function<? super F,? extends Result<? extends S,? extends F2>> mapper)` Transforms this failed `Result` into a different one.
`<S2> Result<S2,F>`	`flatMapSuccess(Function<? super S,? extends Result<? extends S2,? extends F>> mapper)` Transforms this successful `Result` into a different one.
`Optional<F>`	`getFailure()` Returns this `Result`'s failure value as a possibly-empty `Optional`.
`Optional<S>`	`getSuccess()` Returns this `Result`'s success value as a possibly-empty `Optional`.
`boolean`	`hasFailure()` Checks if this `Result` is failed.
`int`	`hashCode()` Returns the hash code of this `Result`'s value.
`boolean`	`hasSuccess()` Checks if this `Result` is successful.
`Result<S,F>`	`ifFailure(Consumer<? super F> action)` Performs the given action with this `Result`'s failure value.
`Result<S,F>`	`ifSuccess(Consumer<? super S> action)` Performs the given action with this `Result`'s success value.
`Result<S,F>`	`ifSuccessOrElse(Consumer<? super S> successAction, Consumer<? super F> failureAction)` Performs either of the given actions with this `Result`'s value.
`<S2,F2> Result<S2,F2>`	`map(Function<? super S,? extends S2> successMapper, Function<? super F,? extends F2> failureMapper)` Transforms this `Result`'s success or failure value.
`<F2> Result<S,F2>`	`mapFailure(Function<? super F,? extends F2> mapper)` Transforms this `Result`'s failure value.
`<S2> Result<S2,F>`	`mapSuccess(Function<? super S,? extends S2> mapper)` Transforms this `Result`'s success value.
`S`	`orElse(S other)` Returns this `Result`'s success value, or the alternative one.
`S`	`orElseMap(Function<? super F,? extends S> mapper)` Returns this `Result`'s success value, or maps its failure value.
`Result<S,F>`	`recover(Predicate<? super F> isRecoverable, Function<? super F,? extends S> mapper)` Transforms this failed `Result` into a successful one, based on the given condition.
`Stream<F>`	`streamFailure()` Returns this `Result`'s failure value as a possibly-empty `Stream`.
`Stream<S>`	`streamSuccess()` Returns this `Result`'s success value as a possibly-empty `Stream`.
`String`	`toString()` Returns a string representation of this `Result`.

- Method Detail
  - hasSuccess
```
boolean hasSuccess()
```
    Checks if this Result is successful.
```
  
 Result<Integer, String> r = getResult();
 boolean x = r.hasSuccess();
 
```
    Returns:
    
    if this Result is successful, true; otherwise, false
    
    See Also:
    
    hasFailure()
  - hasFailure
```
boolean hasFailure()
```
    Checks if this Result is failed.
```
  
 Result<Integer, String> r = getResult();
 boolean x = r.hasFailure();
 
```
    Returns:
    
    if this Result is failed, true; otherwise, false
    
    See Also:
    
    hasSuccess()
  - getSuccess
```
Optional<S> getSuccess()
```
    Returns this Result's success value as a possibly-empty Optional.
```
  
 Result<Integer, String> r = getResult();
 Optional<Integer> x = r.getSuccess();
 
```
    Returns:
    
    if this Result is successful, an Optional containing its value; otherwise, an empty Optional
    
    See Also:
    
    getFailure()
  - getFailure
```
Optional<F> getFailure()
```
    Returns this Result's failure value as a possibly-empty Optional.
```
  
 Result<Integer, String> r = getResult();
 Optional<String> x = r.getFailure();
 
```
    Returns:
    
    if this Result is failed, an Optional containing its value; otherwise, an empty Optional
    
    See Also:
    
    getSuccess()
  - orElse
```
S orElse(S other)
```
    Returns this Result's success value, or the alternative one.
```
  
 Result<Integer, String> r = getResult();
 int x = r.orElse(8);
 
```
    Parameters:
    
    other - the alternative success value; may be null
    
    Returns:
    
    if this Result is successful, its value; otherwise other
    
    See Also:
    
    orElseMap(Function)
  - orElseMap
```
S orElseMap(Function<? super F,? extends S> mapper)
```
    Returns this Result's success value, or maps its failure value.
    If this Result is failed, mapper will be applied to its value to produce an alternative success value.
```
  
 Result<Integer, String> r = getResult();
 int x = r.orElseMap(f -> 8);
 
```
    Parameters:
    
    mapper - the mapping Function that produces the alternative success value; may return null
    
    Returns:
    
    if this Result is successful, its value; otherwise the value produced by mapper
    
    Throws:
    
    NullPointerException - if this Result is failed and mapper is null
    
    See Also:
    
    orElse(Object)
  - streamSuccess
```
Stream<S> streamSuccess()
```
    Returns this Result's success value as a possibly-empty Stream.
```
  
 Result<Integer, String> r = getResult();
 Stream<Integer> x = r.streamSuccess();
 
```
    Returns:
    
    If this Result is successful, a sequential Stream containing only its value; otherwise an empty Stream
  - streamFailure
```
Stream<F> streamFailure()
```
    Returns this Result's failure value as a possibly-empty Stream.
```
  
 Result<Integer, String> r = getResult();
 Stream<String> x = r.streamFailure();
 
```
    Returns:
    
    if this Result is failed, a sequential Stream containing only its value; otherwise an empty Stream
  - ifSuccess
```
Result<S,F> ifSuccess(Consumer<? super S> action)
```
    Performs the given action with this Result's success value.
    If this Result is successful, performs action with its value; otherwise does nothing.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.ifSuccess(System.out::println);
 
```
    Parameters:
    
    action - the Consumer to be applied to this Result's success value
    
    Returns:
    
    this Result
    
    Throws:
    
    NullPointerException - if this Result is successful and action is null
    
    See Also:
    
    ifFailure(Consumer), ifSuccessOrElse(Consumer, Consumer)
  - ifFailure
```
Result<S,F> ifFailure(Consumer<? super F> action)
```
    Performs the given action with this Result's failure value.
    If this Result is failed, performs action with its value; otherwise does nothing.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.ifFailure(System.err::println);
 
```
    Parameters:
    
    action - the Consumer to be applied to this Result's failure value
    
    Returns:
    
    this Result
    
    Throws:
    
    NullPointerException - if this Result is failed and action is null
    
    See Also:
    
    ifSuccess(Consumer), ifSuccessOrElse(Consumer, Consumer)
  - ifSuccessOrElse
```
Result<S,F> ifSuccessOrElse(Consumer<? super S> successAction,
                            Consumer<? super F> failureAction)
```
    Performs either of the given actions with this Result's value.
    If this Result is successful, performs successAction; otherwise performs failureAction.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.ifSuccessOrElse(System.out::println, System.err::println);
 
```
    Parameters:
    
    successAction - the Consumer to be applied to this Result's success value
    
    failureAction - the Consumer to be applied to this Result's failure value
    
    Returns:
    
    this Result
    
    Throws:
    
    NullPointerException - if this Result is successful and successAction is null; or if it is failed and failureAction is null
    
    See Also:
    
    ifFailure(Consumer), ifSuccess(Consumer)
  - filter
```
Result<S,F> filter(Predicate<? super S> isAcceptable,
                   Function<? super S,? extends F> mapper)
```
    Transforms this successful Result into a failed one, based on the given condition.
    If this is a successful Result whose value does not satisfy isAcceptable, mapper will be applied to the value to produce a failure value.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.filter(s -> s < 3, s -> "E");
 
```
    Parameters:
    
    isAcceptable - the Predicate to apply to this Result's success value
    
    mapper - the mapping Function that produces the failure value
    
    Returns:
    
    if this is a successful Result whose value is deemed not acceptable, a new failed Result holding the value produced by mapper; otherwise, this Result
    
    Throws:
    
    NullPointerException - if this Result is successful and isAcceptable is null; or if its success value is not acceptable and mapper is null or returns null
    
    See Also:
    
    recover(Predicate, Function)
  - recover
```
Result<S,F> recover(Predicate<? super F> isRecoverable,
                    Function<? super F,? extends S> mapper)
```
    Transforms this failed Result into a successful one, based on the given condition.
    If this is a failed Result whose value satisfies isRecoverable, mapper will be applied to the value to produce a success value.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, String> x = r.recover("B"::equals, f -> 5);
 
```
    Parameters:
    
    isRecoverable - the Predicate to apply to this Result's failure value
    
    mapper - the mapping Function that produces the success value
    
    Returns:
    
    if this is a failed Result whose value is deemed recoverable, a new successful Result holding the value produced by mapper; otherwise, this Result
    
    Throws:
    
    NullPointerException - if this Result is failed and isRecoverable is null; or if its failure value is recoverable and mapper is null or returns null
    
    See Also:
    
    filter(Predicate, Function)
  - mapSuccess
```
<S2> Result<S2,F> mapSuccess(Function<? super S,? extends S2> mapper)
```
    Transforms this Result's success value.
    If this Result is successful, mapper will be applied to its value to produce a new one, which may differ in type.
```
  
 Result<Integer, String> r = getResult();
 Result<Fruit, String> x = r.mapSuccess(s -> CHERRIES);
 
```
    Type Parameters:
    
    S2 - the type of the value returned by mapper
    
    Parameters:
    
    mapper - the mapping Function that produces the new success value
    
    Returns:
    
    if this is a successful Result, a new successful Result holding the value produced by mapper; otherwise, this Result
    
    Throws:
    
    NullPointerException - if this Result is successful and mapper is null or returns null
    
    See Also:
    
    map(Function, Function), mapFailure(Function)
  - mapFailure
```
<F2> Result<S,F2> mapFailure(Function<? super F,? extends F2> mapper)
```
    Transforms this Result's failure value.
    If this Result is failed, mapper will be applied to its value to produce a new one, which may differ in type.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, Suit> x = r.mapFailure(f -> CLUBS);
 
```
    Type Parameters:
    
    F2 - the type of the value returned by mapper
    
    Parameters:
    
    mapper - the mapping Function that produces the new failure value
    
    Returns:
    
    if this is a failed Result, a new failed Result holding the value produced by mapper; otherwise, this Result
    
    Throws:
    
    NullPointerException - if this Result is failed and mapper is null or returns null
    
    See Also:
    
    map(Function, Function), mapSuccess(Function)
  - map
```
<S2,F2> Result<S2,F2> map(Function<? super S,? extends S2> successMapper,
                          Function<? super F,? extends F2> failureMapper)
```
    Transforms this Result's success or failure value.
    If this is Result is successful, successMapper will be applied to its value to produce a new one. Otherwise, failureMapper will be applied to its failure value to produce a new one.
    Both success and failure values may differ in type.
```
  
 Result<Integer, String> r = getResult();
 Result<Fruit, Suit> x = r.map(s -> CHERRIES, f -> CLUBS);
 
```
    Type Parameters:
    
    S2 - the type of the value returned by successMapper
    
    F2 - the type of the value returned by failureMapper
    
    Parameters:
    
    successMapper - the mapping Function that produces the new success value
    
    failureMapper - the mapping Function that produces the new failure value
    
    Returns:
    
    if this is a successful Result, a new successful Result holding the value produced by successMapper; otherwise, a new failed Result holding the value produced by failureMapper
    
    Throws:
    
    NullPointerException - if this result is successful and successMapper is null or returns null; or if this Result is failed and failureMapper is null or returns null
    
    See Also:
    
    mapFailure(Function), mapSuccess(Function)
  - flatMapSuccess
```
<S2> Result<S2,F> flatMapSuccess(Function<? super S,? extends Result<? extends S2,? extends F>> mapper)
```
    Transforms this successful Result into a different one.
    If this Result is successful, mapper will be applied to its value to produce a new Result, which may now hold either a success or a failure value. New success value may differ in type.
```
  
 Result<Integer, String> r = getResult();
 Result<Fruit, String> x = r.flatMapSuccess(s -> s < 3 ? success(CHERRIES) : failure("E"));
 
```
    Type Parameters:
    
    S2 - the success type of the Result returned by mapper
    
    Parameters:
    
    mapper - the mapping Function that produces a new Result
    
    Returns:
    
    if this Result is successful, a new Result produced by mapper; otherwise, this Result
    
    Throws:
    
    NullPointerException - if this Result is successful and mapper is null or returns null
    
    See Also:
    
    flatMap(Function, Function), flatMapFailure(Function)
  - flatMapFailure
```
<F2> Result<S,F2> flatMapFailure(Function<? super F,? extends Result<? extends S,? extends F2>> mapper)
```
    Transforms this failed Result into a different one.
    If this Result is failed, mapper will be applied to its value to produce a new Result, which may now hold either a success or a failure value. New failure value may differ in type.
```
  
 Result<Integer, String> r = getResult();
 Result<Integer, Suit> x = r.flatMapFailure(f -> f.equals("B") ? success(5) : failure(CLUBS));
 
```
    Type Parameters:
    
    F2 - the failure type of the Result returned by mapper
    
    Parameters:
    
    mapper - the mapping Function that produces a new Result
    
    Returns:
    
    if this Result is failed, a new Result produced by mapper; otherwise, this Result
    
    Throws:
    
    NullPointerException - if this Result is failed and mapper is null or returns null
    
    See Also:
    
    flatMap(Function, Function), flatMapSuccess(Function)
  - flatMap
```
<S2,F2> Result<S2,F2> flatMap(Function<? super S,? extends Result<? extends S2,? extends F2>> successMapper,
                              Function<? super F,? extends Result<? extends S2,? extends F2>> failureMapper)
```
    Transforms this Result into a different one.
    If this Result is successful, successMapper will be applied to its value to produce a new Result; otherwise, failureMapper will be applied to its value to produce a new Result.
    The new Result may now hold either a success or a failure value. Both may differ in type.
```
  
 Result<Integer, String> r = getResult();
 Result<Fruit, Suit> x = r.flatMap(s -> s < 3 ? success(CHERRIES) : failure(SPADES),
     f -> f.equals("B") ? success(WATERMELON) : failure(CLUBS));
 
```
    Type Parameters:
    
    S2 - the success type of the Result returned by successMapper and failureMapper
    
    F2 - the failure type of the Result returned by successMapper and failureMapper
    
    Parameters:
    
    successMapper - the mapping Function that produces a new Result if this Result is successful
    
    failureMapper - the mapping Function that produces a new Result if this Result is failed
    
    Returns:
    
    the Result produced by either successMapper or failureMapper
    
    Throws:
    
    NullPointerException - if this Result is successful and successMapper is null or returns null; or if this Result is failed and failureMapper is null or returns null
    
    See Also:
    
    flatMapFailure(Function), flatMapSuccess(Function)
  - equals
```
boolean equals(Object obj)
```
    Indicates whether some other object is "equal to" this Result.
    The other object is considered equal if:
    - it is also a Result and;
    - both objects are instances of the same class and;
    - their values are "equal to" each other via equals().
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    obj - the object to be tested for equality
    
    Returns:
    
    true if the other object is "equal to" this object; otherwise false
    
    See Also:
    
    hashCode()
  - hashCode
```
int hashCode()
```
    Returns the hash code of this Result's value.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    hash code value of this Result's value
  - toString
```
String toString()
```
    Returns a string representation of this Result.
    The exact presentation format is unspecified and may vary between implementations and versions.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of this Result
    
    Impl Spec:
    
    The returned string should be suitable for debugging and must include the string representation of its value. Successful and failed Result instances must be unambiguously differentiable.

Interface Result<S,F>

Method Summary

Method Detail

hasSuccess

hasFailure

getSuccess

getFailure

orElse

orElseMap

streamSuccess

streamFailure

ifSuccess

ifFailure

ifSuccessOrElse

filter

recover

mapSuccess

mapFailure

map

flatMapSuccess

flatMapFailure

flatMap

equals

hashCode

toString