Programming with Result: kotlin.Result

A short tour of the most important standard library functions for working with Result — general transformation using fold(), retrieving values using getOrThrow(), getOrElse()/getOrDefault(), mapping success using map()/mapCatching(), mapping failure using recover()/recoverCatching() and peeking using onSuccess()/onFailure().

— — — — — — — — — — — — — — —

THE CURRENT VERSION OF THIS ARTICLE IS PUBLISHED HERE.

— — — — — — — — — — — — — — —

Tags: #FUNDAMENTAL CONCEPT

This article is part of the Kotlin Primer, an opinionated guide to the Kotlin language, which is indented to help facilitate Kotlin adoption inside Java-centric organizations. It was originally written as an organizational learning resource for Etnetera a.s. and I would like to express my sincere gratitude for their support.

It is recommended to read the Introduction before moving on. Check out the Table of Contents for all articles.

The kotlin.Result type was added to the standard library to solve the issues we talked about in the previous articles, among others. Its implementation is a little different from the one we presented in the previous section — it is not a sealed class hierarchy, but instead implemented as a single value class.

Other than that, it is mostly the same as what we designed ourselves — it is still semantically equivalent to Result<T> = Success(T) | Failure, even though it is not implement that way.

To manually create a success or failure value, use the Result.success(value: T) and Result.failure(exception: Throwable) methods defined on the companion object. You can determine if the Result is a success or failure using the isSuccess and isFailure methods, and access the value/Throwable using getOrNull() and exceptionOrNull(). However, you will rarely need these, since they promote a more imperative style of programming, and should instead prefer one of the standard functions described bellow.

The standard library also defines a runCatching method, which is exactly the same as what we used before:

There is also a receiver version, T.runCatching. Basically, T.runCatching is to T.run what runCatching is to run:

Standard functions

All the standardized functions are specialized versions of the following function:

inline fun <T, R> Result<T>.fold(
    onSuccess: (value: T) -> R,
    onFailure: (exception: Throwable) -> R
): R

This transforms the value contained in the Result, depending on whether it is a success or failure. In essence, the function returns onSuccess(this.getOrNull()!!) if the Result is a success, and onFailure(this.exceptionOrNull()!!) otherwise.

Retrieving a value

getOrThrow()

fun <T> Result<T>.getOrThrow(): T

Returns the success value, or throws. While this might seem like a trivial function, it is actually incredibly useful when composing methods that return Results, and the subject is interesting enough that we'll dedicate a separate section to it bellow.

Equivalent to fold({ it }, { throw it }).

getOrElse(), getOrDefault()

inline fun <T, R> Result<T>.getOrElse(
    onFailure: (exception: Throwable) -> R
): R 

fun <T, R> Result<T>.getOrDefault(defaultValue: R): R

Returns the success value, or maps the exception to one/returns a default value:

Equivalent to fold({ it }, ::onFailure)/fold({ it }, { defaultValue })

Mapping success Results

map()

inline fun <T, R> Result<T>.map(
    transform: (value: T) -> R
): Result<R>

Transforms a success value. Exceptions thrown inside transform get re-thrown.

Equivalent to

fold({ Result.success(transform(it)) }, { Result.failure(it) })

mapCatching()

inline fun <T, R> Result<T>.mapCatching(
    transform: (value: T) -> R
): Result<R>

Transforms a success value, converting any exception thrown in transform to a failure.

Equivalent to

fold({ runCatching { transform(it) } }, { Result.failure(it) })

Which should you use?

Only use map/mapCatching when transforming a single Result. We’ll talk about combining and composing multiple Results in the next article.

Use map if the business/technical essence of the transformation cannot cause failure (e.g. multiplying a value by 2). Use mapCatching if the essence of the transformation can cause failure (i.e. saving a record, performing a business calculation, etc).

I’m emphasizing the essence of the transformation, because, in theory, every single line can throw an OutOfMemory, ThreadDeath etc. error. There’s really no point in wrapping every single line in a runCatching — these errors, if they really happen while doing something as trivial as multiplying by two, will get caught by one of the “upstream” callers of the method.

Mapping failure results

recover()

inline fun <T, R> Result<T>.recover(
    transform: (exception: Throwable) -> R
): Result<R>

Transforms a failure value (R needs to be assignable to T). Similar to map, but operates on failures. Like map, exceptions thrown inside transform get re-thrown.

Equivalent to

fold({ Result.success(it) }, { Result.success(transform(it)) })

recoverCatching()

inline fun <T, R> Result<T>.recoverCatching(
    transform: (exception: Throwable) -> R
): Result<R>

Transforms a failure value, converting any exception thrown in transform to a failure. Similar to mapCatching, but operates on failures.

Which should you use?

As with map, use recover if the transformation is atomic and/or the business/technical essence of the transformation doesn't include failure. Use recoverCatching if the transformation is complex, and/or the essence of the transformation includes failure.

Peeking

onSuccess(), onFailure()

inline fun <T> Result<T>.onSuccess(
    action: (value: T) -> Unit
): Result<T>

inline fun <T> Result<T>.onFailure(
    action: (exception: Throwable) -> Unit
): Result<T>

Executes action if Result is a success/failure. Returns the original Result unchanged. These functions are basically the equivalent of also, but in the context of Result. Their use-cases are the same.

Go back to Programming with Result: Returning a Result, jump to the Table of Contents, or continue to Programming with Result: Combining and Composing Results.