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>
```
Represents either the success or failure of an operation, including an associated value in each case.
On the one hand, a result object conveys one of these two mutually-exclusive states:
- Success: the operation completed entirely.
- Failure: the operation could not get through.
On the other hand, it also holds a non-null value whose meaning totally depends on the semantics defined by the operation:
- A successful result wraps a value of type S.
- A failed result wraps a value of type F.
Result state can be determined via hasSuccess() or hasFailure(). Additional methods to unwrap the included value are provided, such as orElse() (return an alternative success value if the operation failed) and ifSuccess() (execute a block of code if the operation succeeded).
Author:

Guillermo Calvo

See Also:

com.leakyabstractions.result.api

API Note:

Result is primarily, but not only, intended for use as a method return type whenever failure is expected and recoverable, and where using null is likely to cause errors. A variable whose type is Result should never itself be null; it should always point to a Result instance.

Impl Spec:
This is a value-based type. Classes that implement Result:
- MUST declare only final instance fields (though these may contain references to mutable objects);
- MUST have implementations of equals, hashCode, and toString which are computed solely from the values of the class's instance fields (and the members of the objects they reference), not from the instance's identity;
- MUST treat instances as freely substitutable when equal, meaning that interchanging any two instances x and y that are equal according to equals() produces no visible change in the behavior of the class's methods;
- SHOULD NOT perform any synchronization using an instance's monitor;
- MUST NOT declare (or has deprecated any) accessible constructors;
- MUST NOT provide any instance creation mechanism that promises a unique identity on each method call - in particular, any factory method's contract must allow for the possibility that if two independently-produced instances are equal according to equals(), they may also be equal according to ==;
- MUST be final, and extend either Object or a hierarchy of abstract classes that declare no instance fields or instance initializers and whose constructors are empty.

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)` If this is a successful result whose value does not match the given predicate, returns a new failed result with a value produced by the given mapping function; otherwise returns this result.
`<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)` Returns a new result produced by the appropriate `Result`-bearing mapping function.
`<F2> Result<S,F2>`	`flatMapFailure(Function<? super F,? extends Result<? extends S,? extends F2>> mapper)` If this is a failed result, returns a new result produced by the given, `Result`-bearing mapping function; otherwise returns a successful result with this result's success value.
`<S2> Result<S2,F>`	`flatMapSuccess(Function<? super S,? extends Result<? extends S2,? extends F>> mapper)` If this is a successful result, returns a new result produced by the given, `Result`-bearing mapping function; otherwise returns a failed result with this result's failure value.
`Optional<F>`	`getFailure()` If this is a failed result, returns an optional containing its failure value; otherwise returns an empty optional.
`Optional<S>`	`getSuccess()` If this is a successful result, returns an optional containing its success value; otherwise returns an empty optional.
`boolean`	`hasFailure()` If this is a failed result, returns `true`; otherwise `false`.
`int`	`hashCode()` Returns the hash code of this result's success or failure value.
`boolean`	`hasSuccess()` If this is a successful result, returns `true`; otherwise `false`.
`Result<S,F>`	`ifFailure(Consumer<? super F> action)` If this is a failed result, performs the given action with its failure value; otherwise does nothing.
`Result<S,F>`	`ifSuccess(Consumer<? super S> action)` If this is a successful result, performs the given action with its success value; otherwise does nothing.
`Result<S,F>`	`ifSuccessOrElse(Consumer<? super S> successAction, Consumer<? super F> failureAction)` If this is a successful result, performs the given success action; otherwise performs the given failure action.
`<S2,F2> Result<S2,F2>`	`map(Function<? super S,? extends S2> successMapper, Function<? super F,? extends F2> failureMapper)` Returns a new result with the value produced by the appropriate mapping function.
`<F2> Result<S,F2>`	`mapFailure(Function<? super F,? extends F2> mapper)` If this is a failed result, returns a new failed result with the value produced by the given mapping function; otherwise returns a successful result with this result's success value.
`<S2> Result<S2,F>`	`mapSuccess(Function<? super S,? extends S2> mapper)` If this is a successful result, returns a new successful result with the value produced by the given mapping function; otherwise returns a failed result with this result's failure value.
`S`	`orElse(S other)` If this is a successful result, returns its success value; otherwise returns `other`.
`S`	`orElseMap(Function<? super F,? extends S> mapper)` If this is a successful result, returns its success value; otherwise returns the value produced by the given mapping function.
`Result<S,F>`	`recover(Predicate<? super F> isRecoverable, Function<? super F,? extends S> mapper)` If this is a failed result whose value matches the given predicate, returns a new successful result with a value produced by the given mapping function; otherwise returns this result.
`Stream<F>`	`streamFailure()` If this is a failed result, returns a sequential stream containing only its failure value; otherwise returns an empty stream.
`Stream<S>`	`streamSuccess()` If this is a successful result, returns a sequential stream containing only its success value; otherwise returns an empty stream.
`String`	`toString()` Returns a non-empty string representation of this result suitable for debugging.

- Method Detail
  - hasSuccess
```
boolean hasSuccess()
```
    If this is a successful result, returns true; otherwise false.
```
  
 void testHasSuccess(Result<Integer, String> result) {
   final boolean x = result.hasSuccess();
 }
 
```
    Returns:
    
    true if successful; otherwise false
    
    See Also:
    
    hasFailure()
  - hasFailure
```
boolean hasFailure()
```
    If this is a failed result, returns true; otherwise false.
```
  
 void testHasFailure(Result<Integer, String> result) {
   boolean x = result.hasFailure();
 }
 
```
    Returns:
    
    true if failed; otherwise false
    
    See Also:
    
    hasSuccess()
  - getSuccess
```
Optional<S> getSuccess()
```
    If this is a successful result, returns an optional containing its success value; otherwise returns an empty optional.
```
  
 void testGetSuccess(Result<Integer, String> result) {
   Optional<Integer> x = result.getSuccess();
 }
 
```
    Returns:
    
    this result's success value as an optional if successful; otherwise an empty optional.
    
    See Also:
    
    getFailure()
  - getFailure
```
Optional<F> getFailure()
```
    If this is a failed result, returns an optional containing its failure value; otherwise returns an empty optional.
```
  
 void testGetFailure(Result<Integer, String> result) {
   Optional<String> x = result.getFailure();
 }
 
```
    Returns:
    
    this result's failure value as an optional if failed; otherwise an empty optional.
    
    See Also:
    
    getSuccess()
  - orElse
```
S orElse(S other)
```
    If this is a successful result, returns its success value; otherwise returns other.
```
  
 void testOrElse(Result<Integer, String> result) {
   Integer other = 8;
   Integer x = result.orElse(other);
 }
 
```
    Parameters:
    
    other - the possibly-null alternative success value
    
    Returns:
    
    this result's success value if successful; otherwise other
    
    See Also:
    
    orElseMap(Function)
  - orElseMap
```
S orElseMap(Function<? super F,? extends S> mapper)
```
    If this is a successful result, returns its success value; otherwise returns the value produced by the given mapping function.
    The mapping function will be applied to this result's failure value to produce an alternative success value.
```
  
 void testOrElseMap(Result<Integer, String> result) {
   Function<String, Integer> mapper = f -> 8;
   Integer x = result.orElseMap(mapper);
 }
 
```
    Parameters:
    
    mapper - the mapping function that produces the possibly-null alternative success value
    
    Returns:
    
    this result's success value if successful; otherwise the value produced by the mapping function
    
    Throws:
    
    NullPointerException - if this is a failed result and mapper is null
    
    See Also:
    
    orElse(Object)
  - streamSuccess
```
Stream<S> streamSuccess()
```
    If this is a successful result, returns a sequential stream containing only its success value; otherwise returns an empty stream.
```
  
 void testStreamSuccess(Result<Integer, String> result) {
   Stream<Integer> x = result.streamSuccess();
 }
 
```
    Returns:
    
    this result's success value as a stream if successful; otherwise an empty stream.
  - streamFailure
```
Stream<F> streamFailure()
```
    If this is a failed result, returns a sequential stream containing only its failure value; otherwise returns an empty stream.
```
  
 void testStreamFailure(Result<Integer, String> result) {
   Stream<String> x = result.streamFailure();
 }
 
```
    Returns:
    
    this result's failure value as a stream if failed; otherwise an empty stream.
  - ifSuccess
```
Result<S,F> ifSuccess(Consumer<? super S> action)
```
    If this is a successful result, performs the given action with its success value; otherwise does nothing.
```
  
 void testIfSuccess(Result<Integer, String> result) {
   Consumer<Integer> task = s -> {};
   Result<Integer, String> x = result.ifSuccess(task);
 }
 
```
    Parameters:
    
    action - the action to be applied to this result's success value
    
    Returns:
    
    this result
    
    Throws:
    
    NullPointerException - if this is a successful result and action is null
    
    See Also:
    
    ifFailure(Consumer), ifSuccessOrElse(Consumer, Consumer)
  - ifFailure
```
Result<S,F> ifFailure(Consumer<? super F> action)
```
    If this is a failed result, performs the given action with its failure value; otherwise does nothing.
```
  
 void testIfFailure(Result<Integer, String> result) {
   Consumer<Integer> task = f -> {};
   Result<Integer, String> x = result.ifFailure(task);
 }
 
```
    Parameters:
    
    action - the action to be applied to this result's failure value
    
    Returns:
    
    this result
    
    Throws:
    
    NullPointerException - if this is a failed result and action is null
    
    See Also:
    
    ifSuccess(Consumer), ifSuccessOrElse(Consumer, Consumer)
  - ifSuccessOrElse
```
Result<S,F> ifSuccessOrElse(Consumer<? super S> successAction,
                            Consumer<? super F> failureAction)
```
    If this is a successful result, performs the given success action; otherwise performs the given failure action.
```
  
 void testIfSuccessOrElse(Result<Integer, String> result) {
   Consumer<Integer> task1 = s -> {};
   Consumer<String> task2 = f -> {};
   Result<Integer, String> x = result.ifSuccessOrElse(task1, task2);
 }
 
```
    Parameters:
    
    successAction - the action to be applied to this result's success value
    
    failureAction - the action to be applied to this result's failure value
    
    Returns:
    
    this result
    
    Throws:
    
    NullPointerException - if this is a successful result 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)
```
    If this is a successful result whose value does not match the given predicate, returns a new failed result with a value produced by the given mapping function; otherwise returns this result.
    The mapping function will be applied to this result's success value to produce the failure value.
```
  
 void testFilter(Result<Integer, String> result) {
   Predicate<Integer> isAcceptable = s -> s < 3;
   Function<Integer, String< mapper = s -> "E";
   Result<Integer, String> x = result.filter(isAcceptable, mapper);
 }
 
```
    Parameters:
    
    isAcceptable - the predicate to apply to this result's success value
    
    mapper - the mapping function that produces the failure value
    
    Returns:
    
    a new failed result with the value produced by mapper if this is a successful result whose value does not match the given predicate; otherwise this result
    
    Throws:
    
    NullPointerException - if this is a successful result 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)
```
    If this is a failed result whose value matches the given predicate, returns a new successful result with a value produced by the given mapping function; otherwise returns this result.
    The mapping function will be applied to this result's failure value to produce the success value.
```
  
 void testRecover(Result<Integer, String> result) {
   Predicate<String> isRecoverable = "B"::equals;
   Function<String, Integer> mapper = f -> 5;
   Result<Integer, String> x = result.recover(isRecoverable, mapper);
 }
 
```
    Parameters:
    
    isRecoverable - the predicate to apply to this result's failure value
    
    mapper - the mapping function that produces the success value
    
    Returns:
    
    a new successful result with the value produced by mapper if this is a failed result whose value matches the given predicate; otherwise this result
    
    Throws:
    
    NullPointerException - if this is a failed result 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)
```
    If this is a successful result, returns a new successful result with the value produced by the given mapping function; otherwise returns a failed result with this result's failure value.
    The mapping function will be applied to this result's success value to produce the new success value. The type of the new success value may be different from this result's.
```
  
 void testMapSuccess(Result<Integer, String> result) {
   Function<Integer, Fruit> mapper = s -> CHERRIES;
   Result<Fruit, String> x = result.mapSuccess(mapper);
 }
 
```
    Type Parameters:
    
    S2 - the type of the value returned by mapper
    
    Parameters:
    
    mapper - the mapping function that produces the new success value
    
    Returns:
    
    a new successful result with the value produced by mapper if this is a successful result; otherwise a failed result with this result's failure value
    
    Throws:
    
    NullPointerException - if this is a successful result 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)
```
    If this is a failed result, returns a new failed result with the value produced by the given mapping function; otherwise returns a successful result with this result's success value.
    The mapping function will be applied to this result's failure value to produce the new failure value. The type of the new failure value may be different from this result's.
```
  
 void testMapFailure(Result<Integer, String> result) {
   Function<String, Suit> mapper = f -> CLUBS;
   Result<Integer, Suit> x = result.mapFailure(mapper);
 }
 
```
    Type Parameters:
    
    F2 - the type of the value returned by mapper
    
    Parameters:
    
    mapper - the mapping function that produces the new failure value
    
    Returns:
    
    a new failed result with the value produced by mapper if this is a failed result; otherwise a successful result with this result's success value
    
    Throws:
    
    NullPointerException - if this is a failed result 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)
```
    Returns a new result with the value produced by the appropriate mapping function.
    Depending on this result's state, one of the two given functions will be applied to its success or failure value to produce a new value. The types of the new success/failure values may be different from this result's.
```
  
 void testMap(Result<Integer, String> result) {
   Function<Integer, Fruit> mapper1 = s -> CHERRIES;
   Function<String, Suit> mapper2 = f -> CLUBS;
   Result<Fruit, Suit> x = result.map(mapper1, mapper2);
 }
 
```
    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 a success value
    
    failureMapper - the mapping function that produces a failure value
    
    Returns:
    
    a new result with a value produced by either successMapper or failureMapper
    
    Throws:
    
    NullPointerException - if this is a successful result and successMapper is null or returns null; or if this is a failed result 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)
```
    If this is a successful result, returns a new result produced by the given, Result-bearing mapping function; otherwise returns a failed result with this result's failure value.
    The mapping function will be applied to this result's success value to produce a new result. State and success type may be different from this result's.
```
  
 void testFlatMapSuccess(Result<Integer, String> result) {
   Function<Integer, Result<Fruit, String>> mapper =
       s -> s < 3 ? Results.success(CHERRIES) : Results.failure("E");
   Result<Fruit, String> x = result.flatMapSuccess(mapper);
 }
 
```
    Type Parameters:
    
    S2 - the success type of the result returned by mapper
    
    Parameters:
    
    mapper - the mapping function that produces a new result
    
    Returns:
    
    the result produced by mapper if this is a successful result; otherwise a failed result with this result's failure value.
    
    Throws:
    
    NullPointerException - if this is a successful result 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)
```
    If this is a failed result, returns a new result produced by the given, Result-bearing mapping function; otherwise returns a successful result with this result's success value.
    The mapping function will be applied to this result's failure value to produce a new result. State and failure type may be different from this result's.
```
  
 void testFlatMapFailure(Result<Integer, String> result) {
   Function<String, Result<Integer, Suit>> mapper =
       f -> f.equals("B") ? Results.success(5) : Results.failure(CLUBS);
   Result<Integer, Suit> x = result.flatMapFailure(mapper);
 }
 
```
    Type Parameters:
    
    F2 - the failure type of the result returned by mapper
    
    Parameters:
    
    mapper - the mapping function that produces a new result
    
    Returns:
    
    the result produced by mapper if this is a failed result; otherwise a successful result with this result's success value.
    
    Throws:
    
    NullPointerException - if this is a failed result 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)
```
    Returns a new result produced by the appropriate Result-bearing mapping function.
    Depending on this result's state, one of the two given functions will be applied to its success or failure value to produce a new result. State and types may be different from this result's.
```
  
 void testFlatMap(Result<Integer, String> result) {
   Function<Integer, Result<Fruit, Suit>> mapper1 =
       s -> s < 3 ? success(CHERRIES) : failure(SPADES);
   Function<String, Result<Fruit, Suit>> mapper2 =
       f -> f.equals("B") ? success(WATERMELON) : failure(CLUBS);
   Result<Fruit, Suit> x = result.flatMap(mapper1, mapper2);
 }
 
```
    Type Parameters:
    
    S2 - the success type of the result returned by the given functions
    
    F2 - the failure type of the result returned by the given functions
    
    Parameters:
    
    successMapper - the mapping function that produces a new result if this is a successful result
    
    failureMapper - the mapping function that produces a new result if this is a failed result
    
    Returns:
    
    the result produced by either successMapper or failureMapper
    
    Throws:
    
    NullPointerException - if this is a successful result and successMapper is null or returns null; or if this is a failed result 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 success or failure value.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    hash code value of this result's success or failure value
  - toString
```
String toString()
```
    Returns a non-empty string representation of this result suitable for debugging.
    The exact presentation format is unspecified and may vary between implementations and versions.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    the string representation of this instance
    
    Impl Spec:
    
    The returned string must include the string representation of its success or failure value. Successful and failed results 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