outcome/nz.adjmunro.outcome/Failure

Failure

class Failure<out Error>(val error: Error) : Outcome<Nothing, Error>

The failed variant of Outcome.

Carries the error value that describes why the operation did not succeed. component1 always returns null for a Failure; component2 always returns error.

Constructors

Failure

constructor(error: Error)

Properties

asFault

val <Error> Outcome<*, Error>.asFault: Fault<Error>

Converts any Outcome to a Fault by discarding the Success value (mapping it to Unit).

asMaybe

val <Ok> Outcome<Ok, *>.asMaybe: Maybe<Ok>

Converts any Outcome to a Maybe by discarding the Failure error (mapping it to Unit).

error

val error: Error

The error value describing the failure.

flatten

@get:JvmName(name = "flattenNestedFailureAlias")

val <Ok, Err, Oki : Ok, Oko : Ok> Outcome<Oko, Outcome<Oki, Err>>.flatten: Outcome<Ok, Err>

Property alias for flattenNestedFailure.

@get:JvmName(name = "flattenNestedBothAlias")

val <Ok, Err, Oks : Ok, Ers : Err, Okf : Ok, Erf : Err> Outcome<Outcome<Oks, Ers>, Outcome<Okf, Erf>>.flatten: Outcome<Ok, Err>

Property alias for flattenNestedBoth.

@get:JvmName(name = "flattenNestedSuccessAlias")

val <Ok, Err, Eri : Err, Ero : Err> Outcome<Outcome<Ok, Eri>, Ero>.flatten: Outcome<Ok, Err>

Property alias for flattenNestedSuccess.

toKotlinResult

val <Ok, Error> Outcome<Ok, Error>.toKotlinResult: KotlinResult<Ok>

Converts an Outcome to a KotlinResult.

Functions

andThen

inline fun <In, Out, Error> Outcome<In, Error>.andThen(catch: (throwable: Throwable) -> Outcome<Out, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: RaiseScope<Error>.(In) -> Out): Outcome<Out, Error>

Transforms the Success value of this Outcome, wrapping the result with outcome error-catching semantics.

inline fun <Ok, Error> Outcome<Ok, Error>.andThen(predicate: (Ok) -> Boolean, catch: (throwable: Throwable) -> Outcome<Ok, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: RaiseScope<Error>.(Ok) -> Ok): Outcome<Ok, Error>

Conditionally transforms the Success value, but only when predicate returns true. If predicate returns false, the Success is returned unchanged.

andThenOf

inline suspend fun <In, Out, Error> Outcome<In, Error>.andThenOf(catch: (throwable: Throwable) -> Outcome<Out, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: suspend RaiseScope<Error>.(In) -> Out): Outcome<Out, Error>

Transforms the Success value of this Outcome, wrapping the result with outcomeOf error-catching semantics.

inline suspend fun <Ok, Error> Outcome<Ok, Error>.andThenOf(predicate: (Ok) -> Boolean, catch: (throwable: Throwable) -> Outcome<Ok, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: RaiseScope<Error>.(Ok) -> Ok): Outcome<Ok, Error>

Conditionally transforms the Success value, but only when predicate returns true. If predicate returns false, the Success is returned unchanged.

coerceToFailure

infix inline fun <Ok, Error> Outcome<Ok, Error>.coerceToFailure(falter: (Ok) -> Error): Failure<Error>

Coerces this Outcome to a Failure.

coerceToSuccess

infix inline fun <Ok, Error> Outcome<Ok, Error>.coerceToSuccess(recover: (Error) -> Ok): Success<Ok>

Coerces this Outcome to a Success.

collapse

fun <Ancestor, Ok : Ancestor, Error : Ancestor> Outcome<Ok, Error>.collapse(): Ancestor

Extracts either the Success value or the Failure error, returning the nearest common Ancestor type.

component1

open operator override fun component1(): Nothing?

Returns the Ok value via destructuring, or null if this is a Failure. Note that Ok itself may be a nullable type.

component2

open operator override fun component2(): Error

Returns the Error value via destructuring, or null if this is a Success. Note that Error itself may be a nullable type.

equals

open operator override fun equals(other: Any?): Boolean

errorOrDefault

infix fun <Ok, Error> Outcome<Ok, Error>.errorOrDefault(default: Error): Error

Returns the Failure error, or default if the outcome is a Success.

errorOrElse

infix inline fun <Ok, Error> Outcome<Ok, Error>.errorOrElse(faulter: (Ok) -> Error): Error

Returns the Failure error, or the result of faulter applied to the Success value.

errorOrNull

fun <Ok, Error> Outcome<Ok, Error>.errorOrNull(): Error?

Returns the Failure error, or null if the outcome is a Success.

errorOrRaise

context(scope: RaiseScope<OuterError>)
fun <OuterError, Ok : OuterError, InnerError> Outcome<Ok, InnerError>.errorOrRaise(): InnerError

Returns the Failure error, or short-circuits the surrounding RaiseScope with the Success value.

errorOrThrow

fun <Ok, Error> Outcome<Ok, Error>.errorOrThrow(): Error

Returns the Failure error, or throws if the outcome is a Success.

falter

infix inline fun <Ok, Error> Outcome<Ok, Error>.falter(transform: (Ok) -> Error): Failure<Error>

Infix alias for coerceToFailure.

flatMapFailure

infix inline fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.flatMapFailure(transform: (ErrorIn) -> Outcome<Ok, ErrorOut>): Outcome<Ok, ErrorOut>

Transforms Outcome<Ok, ErrorIn> into Outcome<Ok, ErrorOut> by applying transform to the Failure error.

flatMapSuccess

infix inline fun <In, Out, Error> Outcome<In, Error>.flatMapSuccess(transform: (In) -> Outcome<Out, Error>): Outcome<Out, Error>

Transforms Outcome<In, Error> into Outcome<Out, Error> by applying transform to the Success value.

flattenNestedBoth

Flattens nested Outcome values from both the Success and Failure states into a single Outcome.

flattenNestedFailure

fun <OuterOk : AncestorOk, EmbeddedOk : AncestorOk, Error, AncestorOk> Outcome<OuterOk, Outcome<EmbeddedOk, Error>>.flattenNestedFailure(): Outcome<AncestorOk, Error>

Flattens a nested Outcome from inside the Failure state into a single Outcome.

flattenNestedSuccess

fun <Ok, EmbeddedError : AncestorError, OuterError : AncestorError, AncestorError> Outcome<Outcome<Ok, EmbeddedError>, OuterError>.flattenNestedSuccess(): Outcome<Ok, AncestorError>

Flattens a nested Outcome from inside the Success state into a single Outcome.

fold

inline fun <Ok, Error, Output> Outcome<Ok, Error>.fold(failure: Failure<Error>.() -> Output, success: Success<Ok>.() -> Output): Output

Applies success or failure to the receiver Outcome, returning Output.

getOrDefault

infix fun <Ok, Error> Outcome<Ok, Error>.getOrDefault(default: Ok): Ok

Returns the Success value, or default if the outcome is a Failure.

getOrElse

infix inline fun <Ok, Error> Outcome<Ok, Error>.getOrElse(recover: (Error) -> Ok): Ok

Returns the Success value, or the result of recover applied to the Failure error.

getOrNull

fun <Ok, Error> Outcome<Ok, Error>.getOrNull(): Ok?

Returns the Success value, or null if the outcome is a Failure.

getOrRaise

context(scope: RaiseScope<OuterError>)
fun <OuterError, Ok, InnerError : OuterError> Outcome<Ok, InnerError>.getOrRaise(): Ok

Returns the Success value, or short-circuits the surrounding RaiseScope with the Failure error.

getOrThrow

fun <Ok, Error> Outcome<Ok, Error>.getOrThrow(): Ok

Returns the Success value, or throws if the outcome is a Failure.

hashCode

open override fun hashCode(): Int

invert

fun <Ok, Error> Outcome<Ok, Error>.invert(): Outcome<Error, Ok>

Swaps the Success value and the Failure error, producing Outcome<Error, Ok>.

isFailure

fun <Ok, Error> Outcome<Ok, Error>.isFailure(): Boolean

Returns true if this Outcome is a Failure.

infix inline fun <Ok, Error> Outcome<Ok, Error>.isFailure(predicate: (Error) -> Boolean): Boolean

Returns true if this is a Failure and predicate returns true for the error.

isSuccess

fun <Ok, Error> Outcome<Ok, Error>.isSuccess(): Boolean

Returns true if this Outcome is a Success.

infix inline fun <Ok, Error> Outcome<Ok, Error>.isSuccess(predicate: (Ok) -> Boolean): Boolean

Returns true if this is a Success and predicate returns true for the value.

map

inline fun <In, Out, ErrorIn, ErrorOut> Outcome<In, ErrorIn>.map(failure: (ErrorIn) -> ErrorOut, success: (In) -> Out): Outcome<Out, ErrorOut>

Transforms both states of an Outcome, re-wrapping each result in the same kind of Outcome.

mapFailure

infix inline fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.mapFailure(transform: (ErrorIn) -> ErrorOut): Outcome<Ok, ErrorOut>

Transforms Outcome<Ok, ErrorIn> into Outcome<Ok, ErrorOut> by applying transform to the Failure error.

mapSuccess

infix inline fun <In, Out, Error> Outcome<In, Error>.mapSuccess(transform: (In) -> Out): Outcome<Out, Error>

Transforms Outcome<In, Error> into Outcome<Out, Error> by applying transform to the Success value.

onFailure

infix inline fun <Ok, Error> Outcome<Ok, Error>.onFailure(block: (Error) -> Unit): Outcome<Ok, Error>

Calls block with the Failure error if this is a failure, then returns the original Outcome unchanged. No-op on Success.

onSuccess

infix inline fun <Ok, Error> Outcome<Ok, Error>.onSuccess(block: (Ok) -> Unit): Outcome<Ok, Error>

Calls block with the Success value if this is a success, then returns the original Outcome unchanged. No-op on Failure.

recover

infix inline fun <Ok, Error> Outcome<Ok, Error>.recover(transform: (Error) -> Ok): Success<Ok>

Infix alias for coerceToSuccess.

rfold

inline fun <Ok, Error, Output> Outcome<Ok, Error>.rfold(success: Success<Ok>.() -> Output, failure: Failure<Error>.() -> Output): Output

Reverse fold — identical behaviour with swapped lambda argument order.

throwIf

inline fun <Ok, Error> Outcome<Ok, Error>.throwIf(fallbackMessage: (Error) -> String = { "Outcome was Failure and throwIf predicate was true: $it" }, predicate: (Error) -> Boolean): Outcome<Ok, Error>

Throws if this is a Failure and predicate returns true for the error. Returns the original Outcome unchanged otherwise.

throwUnless

inline fun <Ok, Error> Outcome<Ok, Error>.throwUnless(fallbackMessage: (Error) -> String = { "Outcome was Failure and throwUnless predicate was false: $it" }, predicate: (Error) -> Boolean): Outcome<Ok, Error>

Throws if this is a Failure and predicate returns false for the error. Returns the original Outcome unchanged otherwise.

toString

open override fun toString(): String

tryRecover

inline fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.tryRecover(catch: (throwable: Throwable) -> Outcome<Ok, ErrorOut> = ::rethrow, scope: RaiseScope<ErrorOut> = DefaultRaiseScope(), failure: RaiseScope<ErrorOut>.(ErrorIn) -> Ok): Outcome<Ok, ErrorOut>

Transforms a Failure into a Success, wrapping the result with outcome error-catching semantics.

tryRecoverOf

inline suspend fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.tryRecoverOf(catch: (throwable: Throwable) -> Outcome<Ok, ErrorOut> = ::rethrow, scope: RaiseScope<ErrorOut> = DefaultRaiseScope(), failure: RaiseScope<ErrorOut>.(ErrorIn) -> Ok): Outcome<Ok, ErrorOut>

Transforms a Failure into a Success, wrapping the result with outcomeOf error-catching semantics.

Failure

See also

Constructors

Properties

Functions