azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve Result docs to emphasize that any Throwable exception is caught

Browse Source 
#KT-33447 Fixed
This commit is contained in:
Ilya Gorbunov
2019-11-30 07:33:43 +03:00
parent d84daa0a4b
commit edfd933348
1 changed files with 32 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/kotlin/util/Result.kt
+32 -32
View File
@@ -12,7 +12,7 @@ import kotlin.internal.InlineOnly
import kotlin.jvm.JvmField
/**
* A discriminated union that encapsulates successful outcome with a value of type [T]
* A discriminated union that encapsulates a successful outcome with a value of type [T]
* or a failure with an arbitrary [Throwable] exception.
*/
@Suppress("NON_PUBLIC_PRIMARY_CONSTRUCTOR_OF_INLINE_CLASS")
@@ -24,13 +24,13 @@ public inline class Result<out T> @PublishedApi internal constructor(
// discovery
/**
* Returns `true` if this instance represents successful outcome.
* Returns `true` if this instance represents a successful outcome.
* In this case [isFailure] returns `false`.
*/
public val isSuccess: Boolean get() = value !is Failure
/**
* Returns `true` if this instance represents failed outcome.
* Returns `true` if this instance represents a failed outcome.
* In this case [isSuccess] returns `false`.
*/
public val isFailure: Boolean get() = value is Failure
@@ -41,7 +41,7 @@ public inline class Result<out T> @PublishedApi internal constructor(
* Returns the encapsulated value if this instance represents [success][Result.isSuccess] or `null`
* if it is [failure][Result.isFailure].
*
* This function is shorthand for `getOrElse { null }` (see [getOrElse]) or
* This function is a shorthand for `getOrElse { null }` (see [getOrElse]) or
* `fold(onSuccess = { it }, onFailure = { null })` (see [fold]).
*/
@InlineOnly
@@ -52,10 +52,10 @@ public inline class Result<out T> @PublishedApi internal constructor(
}
/**
* Returns the encapsulated exception if this instance represents [failure][isFailure] or `null`
* Returns the encapsulated [Throwable] exception if this instance represents [failure][isFailure] or `null`
* if it is [success][isSuccess].
*
* This function is shorthand for `fold(onSuccess = { null }, onFailure = { it })` (see [fold]).
* This function is a shorthand for `fold(onSuccess = { null }, onFailure = { it })` (see [fold]).
*/
public fun exceptionOrNull(): Throwable? =
when (value) {
@@ -89,7 +89,7 @@ public inline class Result<out T> @PublishedApi internal constructor(
Result(value)
/**
* Returns an instance that encapsulates the given [exception] as failure.
* Returns an instance that encapsulates the given [Throwable] [exception] as failure.
*/
@InlineOnly
public inline fun <T> failure(exception: Throwable): Result<T> =
@@ -128,7 +128,7 @@ internal fun Result<*>.throwOnFailure() {
/**
* Calls the specified function [block] and returns its encapsulated result if invocation was successful,
* catching and encapsulating any thrown exception as a failure.
* catching any [Throwable] exception that was thrown from the [block] function execution and encapsulating it as a failure.
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -141,8 +141,8 @@ public inline fun <R> runCatching(block: () -> R): Result<R> {
}
/**
* Calls the specified function [block] with `this` value as its receiver and returns its encapsulated result
* if invocation was successful, catching and encapsulating any thrown exception as a failure.
* 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.
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -157,10 +157,10 @@ public inline fun <T, R> T.runCatching(block: T.() -> R): Result<R> {
// -- extensions ---
/**
* Returns the encapsulated value if this instance represents [success][Result.isSuccess] or throws the encapsulated exception
* Returns the encapsulated value if this instance represents [success][Result.isSuccess] or throws the encapsulated [Throwable] exception
* if it is [failure][Result.isFailure].
*
* This function is shorthand for `getOrElse { throw it }` (see [getOrElse]).
* This function is a shorthand for `getOrElse { throw it }` (see [getOrElse]).
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -171,11 +171,11 @@ public inline fun <T> Result<T>.getOrThrow(): T {
/**
* Returns the encapsulated value if this instance represents [success][Result.isSuccess] or the
* result of [onFailure] function for encapsulated exception if it is [failure][Result.isFailure].
* result of [onFailure] function for the encapsulated [Throwable] exception if it is [failure][Result.isFailure].
*
* Note, that an exception thrown by [onFailure] function is rethrown by this function.
* Note, that this function rethrows any [Throwable] exception thrown by [onFailure] function.
*
* This function is shorthand for `fold(onSuccess = { it }, onFailure = onFailure)` (see [fold]).
* This function is a shorthand for `fold(onSuccess = { it }, onFailure = onFailure)` (see [fold]).
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -193,7 +193,7 @@ public inline fun <R, T : R> Result<T>.getOrElse(onFailure: (exception: Throwabl
* Returns the encapsulated value if this instance represents [success][Result.isSuccess] or the
* [defaultValue] if it is [failure][Result.isFailure].
*
* This function is shorthand for `getOrElse { defaultValue }` (see [getOrElse]).
* This function is a shorthand for `getOrElse { defaultValue }` (see [getOrElse]).
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -203,10 +203,10 @@ public inline fun <R, T : R> Result<T>.getOrDefault(defaultValue: R): R {
}
/**
* Returns the the result of [onSuccess] for encapsulated value if this instance represents [success][Result.isSuccess]
* or the result of [onFailure] function for encapsulated exception if it is [failure][Result.isFailure].
* Returns the result of [onSuccess] for the encapsulated value if this instance represents [success][Result.isSuccess]
* or the result of [onFailure] function for the encapsulated [Throwable] exception if it is [failure][Result.isFailure].
*
* Note, that an exception thrown by [onSuccess] or by [onFailure] function is rethrown by this function.
* Note, that this function rethrows any [Throwable] exception thrown by [onSuccess] or by [onFailure] function.
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -227,11 +227,11 @@ public inline fun <R, T> Result<T>.fold(
// transformation
/**
* Returns the encapsulated result of the given [transform] function applied to encapsulated value
* Returns the encapsulated result of the given [transform] function applied to the encapsulated value
* if this instance represents [success][Result.isSuccess] or the
* original encapsulated exception if it is [failure][Result.isFailure].
* original encapsulated [Throwable] exception if it is [failure][Result.isFailure].
*
* Note, that an exception thrown by [transform] function is rethrown by this function.
* Note, that this function rethrows any [Throwable] exception thrown by [transform] function.
* See [mapCatching] for an alternative that encapsulates exceptions.
*/
@InlineOnly
@@ -247,12 +247,12 @@ public inline fun <R, T> Result<T>.map(transform: (value: T) -> R): Result<R> {
}
/**
* Returns the encapsulated result of the given [transform] function applied to encapsulated value
* Returns the encapsulated result of the given [transform] function applied to the encapsulated value
* if this instance represents [success][Result.isSuccess] or the
* original encapsulated exception if it is [failure][Result.isFailure].
* original encapsulated [Throwable] exception if it is [failure][Result.isFailure].
*
* Any exception thrown by [transform] function is caught, encapsulated as a failure and returned by this function.
* See [map] for an alternative that rethrows exceptions.
* This function catches any [Throwable] exception thrown by [transform] function and encapsulates it as a failure.
* See [map] for an alternative that rethrows exceptions from `transform` function.
*/
@InlineOnly
@SinceKotlin("1.3")
@@ -264,11 +264,11 @@ public inline fun <R, T> Result<T>.mapCatching(transform: (value: T) -> R): Resu
}
/**
* Returns the encapsulated result of the given [transform] function applied to encapsulated exception
* Returns the encapsulated result of the given [transform] function applied to the encapsulated [Throwable] exception
* if this instance represents [failure][Result.isFailure] or the
* original encapsulated value if it is [success][Result.isSuccess].
*
* Note, that an exception thrown by [transform] function is rethrown by this function.
* Note, that this function rethrows any [Throwable] exception thrown by [transform] function.
* See [recoverCatching] for an alternative that encapsulates exceptions.
*/
@InlineOnly
@@ -284,11 +284,11 @@ public inline fun <R, T : R> Result<T>.recover(transform: (exception: Throwable)
}
/**
* Returns the encapsulated result of the given [transform] function applied to encapsulated exception
* Returns the encapsulated result of the given [transform] function applied to the encapsulated [Throwable] exception
* if this instance represents [failure][Result.isFailure] or the
* original encapsulated value if it is [success][Result.isSuccess].
*
* Any exception thrown by [transform] function is caught, encapsulated as a failure and returned by this function.
* This function catches any [Throwable] exception thrown by [transform] function and encapsulates it as a failure.
* See [recover] for an alternative that rethrows exceptions.
*/
@InlineOnly
@@ -304,7 +304,7 @@ public inline fun <R, T : R> Result<T>.recoverCatching(transform: (exception: Th
// "peek" onto value/exception and pipe
/**
* Performs the given [action] on encapsulated exception if this instance represents [failure][Result.isFailure].
* Performs the given [action] on the encapsulated [Throwable] exception if this instance represents [failure][Result.isFailure].
* Returns the original `Result` unchanged.
*/
@InlineOnly
@@ -318,7 +318,7 @@ public inline fun <T> Result<T>.onFailure(action: (exception: Throwable) -> Unit
}
/**
* Performs the given [action] on encapsulated value if this instance represents [success][Result.isSuccess].
* Performs the given [action] on the encapsulated value if this instance represents [success][Result.isSuccess].
* Returns the original `Result` unchanged.
*/
@InlineOnly