kotlin-result/com.github.michaelbull.result

Package com.github.michaelbull.result

Types

Err

class Err<out E>(error: E) : Result<Nothing, E>

Represents a failed Result, containing an error.

class Ok<out V>(value: V) : Result<V, Nothing>

Represents a successful Result, containing a value.

Result

sealed class Result<out V, out E>

Result is a type that represents either success (Ok) or failure (Err).

ResultBinding

interface ResultBinding<E>

UnwrapException

class UnwrapException(message: String) : Exception

Functions

and

infix fun <V, E> Result<V, E>.and(result: Result<V, E>): Result<V, E>

Returns result if this Result is Ok, otherwise this Err.

~~infix inline~~ ~~fun~~ <V, E> Result<V, E>.~~and~~(~~result~~: () -> Result<V, E>): Result<V, E>

andThen

infix inline fun <V, E, U> Result<V, E>.andThen(transform: (V) -> Result<U, E>): Result<U, E>

Maps this Result to Result by either applying the transform function if this Result is Ok, or returning this Err.

binding

inline fun <V, E> binding(crossinline block: ResultBinding<E>.() -> V): Result<V, E>

Calls the specified function block with ResultBinding as its receiver and returns its Result.

combine

fun <V, E> Iterable<Result<V, E>>.combine(): Result<List<V>, E>

Combines an Iterable of Results into a single Result (holding a List).

fun <V, E> combine(vararg results: Result<V, E>): Result<List<V>, E>

Combines a vararg of Results into a single Result (holding a List).

expect

infix inline fun <V, E> Result<V, E>.expect(message: () -> Any): V

Unwraps a Result, yielding the value.

~~infix~~ ~~fun~~ <V, E> Result<V, E>.~~expect~~(~~message~~: String): V

expectError

infix inline fun <V, E> Result<V, E>.expectError(message: () -> Any): E

Unwraps a Result, yielding the error.

~~infix~~ ~~fun~~ <V, E> Result<V, E>.~~expectError~~(~~message~~: String): E

flatMap

infix inline fun <V, E, U> Result<V, E>.flatMap(transform: (V) -> Result<U, E>): Result<U, E>

Maps this Result to Result by either applying the transform function if this Result is Ok, or returning this Err.

fold

inline fun <V, E, U> Result<V, E>.fold(success: (V) -> U, failure: (E) -> U): U

Maps this Result to U by applying either the success function if this Result is Ok, or the failure function if this Result is an Err. Both of these functions must return the same type (U).

inline fun <T, R, E> Iterable<T>.fold(initial: R, operation: (R, T) -> Result<R, E>): Result<R, E>

Accumulates value starting with initial value and applying operation from left to right to current accumulator value and each element.

foldRight

inline fun <T, R, E> List<T>.foldRight(initial: R, operation: (T, R) -> Result<R, E>): Result<R, E>

Accumulates value starting with initial value and applying operation from right to left to each element and current accumulator value.

get

fun <V, E> Result<V, E>.get(): V?

Returns the value if this Result is Ok, otherwise null.

getAll

fun <V, E> Iterable<Result<V, E>>.getAll(): List<V>

Extracts from an Iterable of Results all the Ok elements. All the Ok elements are extracted in order.

fun <V, E> getAll(vararg results: Result<V, E>): List<V>

Extracts from a vararg of Results all the Ok elements. All the Ok elements are extracted in order.

getAllErrors

fun <V, E> Iterable<Result<V, E>>.getAllErrors(): List<E>

Extracts from an Iterable of Results all the Err elements. All the Err elements are extracted in order.

fun <V, E> getAllErrors(vararg results: Result<V, E>): List<E>

Extracts from a vararg of Results all the Err elements. All the Err elements are extracted in order.

getError

fun <V, E> Result<V, E>.getError(): E?

Returns the error if this Result is Err, otherwise null.

getErrorOr

infix fun <V, E> Result<V, E>.getErrorOr(default: E): E

Returns the error if this Result is Err, otherwise default.

~~infix inline~~ ~~fun~~ <V, E> Result<V, E>.~~getErrorOr~~(~~default~~: () -> E): E

getErrorOrElse

infix inline fun <V, E> Result<V, E>.getErrorOrElse(transform: (V) -> E): E

Returns the error if this Result is Err, otherwise the transformation of the value.

getOr

infix fun <V, E> Result<V, E>.getOr(default: V): V

Returns the value if this Result is Ok, otherwise default.

~~infix inline~~ ~~fun~~ <V, E> Result<V, E>.~~getOr~~(~~default~~: () -> V): V

getOrElse

infix inline fun <V, E> Result<V, E>.getOrElse(transform: (E) -> V): V

Returns the value if this Result is Ok, otherwise the transformation of the error.

getOrThrow

fun <V, E : Throwable> Result<V, E>.getOrThrow(): V

Returns the value if this Result is Ok, otherwise throws the error.

infix inline fun <V, E> Result<V, E>.getOrThrow(transform: (E) -> Throwable): V

Returns the value if this Result is Ok, otherwise throws the transformation of the error to a Throwable.

iterator

fun <V, E> Result<V, E>.iterator(): Iterator<V>

Returns an Iterator over the possibly contained value. The iterator yields one value if the Result is Ok, otherwise throws NoSuchElementException.

map

infix inline fun <V, E, U> Result<V, E>.map(transform: (V) -> U): Result<U, E>

Maps this Result to Result by either applying the transform function to the value if this Result is Ok, or returning this Err.

mapAll

infix inline fun <V, E, U> Result<Iterable<V>, E>.mapAll(transform: (V) -> Result<U, E>): Result<List, E>

Returns a Result, E> containing the results of applying the given transform function to each element in the original collection, returning early with the first Err if a transformation fails.

mapBoth

inline fun <V, E, U> Result<V, E>.mapBoth(success: (V) -> U, failure: (E) -> U): U

Maps this Result to U by applying either the success function if this Result is Ok, or the failure function if this Result is an Err. Both of these functions must return the same type (U).

mapEither

inline fun <V, E, U, F> Result<V, E>.mapEither(success: (V) -> U, failure: (E) -> F): Result<U, F>

Maps this Result to Result by applying either the success function if this Result is Ok, or the failure function if this Result is an Err.

mapError

infix inline fun <V, E, F> Result<V, E>.mapError(transform: (E) -> F): Result<V, F>

Maps this Result to Result by either applying the transform function to the error if this Result is Err, or returning this Ok.

mapOr

inline fun <V, E, U> Result<V, E>.mapOr(default: U, transform: (V) -> U): U

Maps this Result to U by either applying the transform function to the value if this Result is Ok, or returning the default if this Result is an Err.

mapOrElse

inline fun <V, E, U> Result<V, E>.mapOrElse(default: (E) -> U, transform: (V) -> U): U

Maps this Result to U by applying either the transform function if this Result is Ok, or the default function if this Result is an Err. Both of these functions must return the same type (U).

mapResult

inline fun <V, E, U> Iterable<V>.mapResult(transform: (V) -> Result<U, E>): Result<List, E>

Returns a Result, E> containing the results of applying the given transform function to each element in the original collection, returning early with the first Err if a transformation fails.

mapResultIndexed

inline fun <V, E, U> Iterable<V>.mapResultIndexed(transform: (index: Int, V) -> Result<U, E>): Result<List, E>

Returns a Result, E> containing the results of applying the given transform function to each element and its index in the original collection, returning early with the first Err if a transformation fails.

mapResultIndexedNotNull

inline fun <V, E, U : Any> Iterable<V>.mapResultIndexedNotNull(transform: (index: Int, V) -> Result<U, E>?): Result<List, E>

Returns a Result, E> containing only the non-null results of applying the given transform function to each element and its index in the original collection, returning early with the first Err if a transformation fails.

mapResultIndexedNotNullTo

inline fun <V, E, U : Any, C : MutableCollection<in U>> Iterable<V>.mapResultIndexedNotNullTo(destination: C, transform: (index: Int, V) -> Result<U, E>?): Result<C, E>

Applies the given transform function to each element and its index in the original collection and appends only the non-null results to the given destination, returning early with the first Err if a transformation fails.

mapResultIndexedTo

inline fun <V, E, U, C : MutableCollection<in U>> Iterable<V>.mapResultIndexedTo(destination: C, transform: (index: Int, V) -> Result<U, E>): Result<C, E>

Applies the given transform function to each element and its index in the original collection and appends the results to the given destination, returning early with the first Err if a transformation fails.

mapResultNotNull

inline fun <V, E, U : Any> Iterable<V>.mapResultNotNull(transform: (V) -> Result<U, E>?): Result<List, E>

Returns a Result, E> containing only the non-null results of applying the given transform function to each element in the original collection, returning early with the first Err if a transformation fails.

mapResultNotNullTo

inline fun <V, E, U : Any, C : MutableCollection<in U>> Iterable<V>.mapResultNotNullTo(destination: C, transform: (V) -> Result<U, E>?): Result<C, E>

Applies the given transform function to each element in the original collection and appends only the non-null results to the given destination, returning early with the first Err if a transformation fails.

mapResultTo

inline fun <V, E, U, C : MutableCollection<in U>> Iterable<V>.mapResultTo(destination: C, transform: (V) -> Result<U, E>): Result<C, E>

Applies the given transform function to each element of the original collection and appends the results to the given destination, returning early with the first Err if a transformation fails.

merge

fun <V : U, E : U, U> Result<V, E>.merge(): U

Merges this Result to U, returning the value if this Result is Ok, otherwise the error.

mutableIterator

fun <V, E> Result<V, E>.mutableIterator(): MutableIterator<V>

Returns a MutableIterator over the possibly contained value. The iterator yields one value if the Result is Ok, otherwise throws NoSuchElementException.

onFailure

infix inline fun <V, E> Result<V, E>.onFailure(action: (E) -> Unit): Result<V, E>

Invokes an action if this Result is Err.

onSuccess

infix inline fun <V, E> Result<V, E>.onSuccess(action: (V) -> Unit): Result<V, E>

Invokes an action if this Result is Ok.

infix fun <V, E> Result<V, E>.or(result: Result<V, E>): Result<V, E>

Returns result if this Result is Err, otherwise this Ok.

~~infix inline~~ ~~fun~~ <V, E> Result<V, E>.or(~~result~~: () -> Result<V, E>): Result<V, E>

orElse

infix inline fun <V, E> Result<V, E>.orElse(transform: (E) -> Result<V, E>): Result<V, E>

Returns the transformation of the error if this Result is Err, otherwise this Ok.

orElseThrow

fun <V, E : Throwable> Result<V, E>.orElseThrow(): Ok<V>

Throws the error if this Result is Err, otherwise returns this Ok.

partition

fun <V, E> Iterable<Result<V, E>>.partition(): Pair<List<V>, List<E>>

Partitions an Iterable of Results into a Pair of Lists. All the Ok elements are extracted, in order, to the first value. Similarly the Err elements are extracted to the Pair.second value.

fun <V, E> partition(vararg results: Result<V, E>): Pair<List<V>, List<E>>

Partitions a vararg of Results into a Pair of Lists. All the Ok elements are extracted, in order, to the first value. Similarly the Err elements are extracted to the Pair.second value.

recover

infix inline fun <V, E> Result<V, E>.recover(transform: (E) -> V): Ok<V>

Returns the transformation of the error if this Result is Err, otherwise this Ok.

recoverIf

inline fun <V, E> Result<V, E>.recoverIf(predicate: (E) -> Boolean, transform: (E) -> V): Result<V, E>

Returns the transformation of the error if this Result is Err and satisfies the given predicate, otherwise this Result.

recoverUnless

inline fun <V, E> Result<V, E>.recoverUnless(predicate: (E) -> Boolean, transform: (E) -> V): Result<V, E>

Returns the transformation of the error if this Result is Err and does not satisfy the given predicate, otherwise this Result.

runCatching

inline fun <V> runCatching(block: () -> V): Result<V, Throwable>

Calls the specified function block and returns its encapsulated result if invocation was successful, catching any Throwable exception that was thrown from the block function execution and encapsulating it as a failure.

infix inline fun <T, V> T.runCatching(block: T.() -> V): Result<V, Throwable>

Calls the specified function block with this value as its receiver and returns its encapsulated result if invocation was successful, catching any Throwable exception that was thrown from the block function execution and encapsulating it as a failure.

throwIf

inline fun <V, E : Throwable> Result<V, E>.throwIf(predicate: (E) -> Boolean): Result<V, E>

Throws the error if this Result is an Err and satisfies the given predicate, otherwise returns this Result.

throwUnless

inline fun <V, E : Throwable> Result<V, E>.throwUnless(predicate: (E) -> Boolean): Result<V, E>

Throws the error if this Result is an Err and does not satisfy the given predicate, otherwise returns this Result.

toErrorIf

inline fun <V, E> Result<V, E>.toErrorIf(predicate: (V) -> Boolean, transform: (V) -> E): Result<V, E>

Returns the transformation of the value if this Result is Ok and satisfies the given predicate, otherwise this Result.

toErrorUnless

inline fun <V, E> Result<V, E>.toErrorUnless(predicate: (V) -> Boolean, transform: (V) -> E): Result<V, E>

Returns the transformation of the value if this Result is Ok and does not satisfy the given predicate, otherwise this Result.

toResultOr

infix inline fun <V, E> V?.toResultOr(error: () -> E): Result<V, E>

Converts a nullable of type V to a Result. Returns Ok if the value is non-null, otherwise the supplied error.

unwrap

fun <V, E> Result<V, E>.unwrap(): V

Unwraps a Result, yielding the value.

unwrapError

fun <V, E> Result<V, E>.unwrapError(): E

Unwraps a Result, yielding the error.

zip

inline fun <T1, T2, E, V> zip(result1: Producer<T1, E>, result2: Producer<T2, E>, transform: (T1, T2) -> V): Result<V, E>

Apply a transformation to two Results, if both Results are Ok. If not, the first argument which is an Err will propagate through.

inline fun <T1, T2, T3, E, V> zip(result1: Producer<T1, E>, result2: Producer<T2, E>, result3: Producer<T3, E>, transform: (T1, T2, T3) -> V): Result<V, E>

Apply a transformation to three Results, if all Results are Ok. If not, the first argument which is an Err will propagate through.

inline fun <T1, T2, T3, T4, E, V> zip(result1: Producer<T1, E>, result2: Producer<T2, E>, result3: Producer<T3, E>, result4: Producer<T4, E>, transform: (T1, T2, T3, T4) -> V): Result<V, E>

Apply a transformation to four Results, if all Results are Ok. If not, the first argument which is an Err will propagate through.

inline fun <T1, T2, T3, T4, T5, E, V> zip(result1: Producer<T1, E>, result2: Producer<T2, E>, result3: Producer<T3, E>, result4: Producer<T4, E>, result5: Producer<T5, E>, transform: (T1, T2, T3, T4, T5) -> V): Result<V, E>

Apply a transformation to five Results, if all Results are Ok. If not, the first argument which is an Err will propagate through.