This module implements a result-type which encapsulates both a success and a failure in one value. Only one of the two states can be active.
Based on https://github.com/disruptek/badresults, which was itself based on https://github.com/arnetheduck/nim-result.
Exception translation
Using get or value raises an exception if the Result stores a failure.
- For Result[T, E] the exception raised is:
- if E is a ref type that inherits from Exception, the error value
- if a custom overload of toException exists, the result
of toException(r)
- otherwise, a new ResultError[E] with error as the payload
Types
Result[T; E] = object case o: bool of false: e: E of true: v: T
- A Result is typically used to augment a return value of type T indicating that a computation (proc, etc...) is uncertain and should return a value of type T or end in an error of type E. This is useful to avoid encoding entirely expected error cases as values instead of resorting to exception handling for program control flow or various side-channel data. Source Edit
ResultError[E] = object of ValueError error: E
- Source Edit
ResultErrorRef[E] = ref ResultError[E]
- Source Edit
Procs
proc `$`[T: not void; E](self: Result[T, E]): string
- Returns the string representation of self Source Edit
func `==`(a, b: Result): bool {.inline.}
- Equal if both a and b have the same ok/err status, then compares the value or error pairs using available == for those type of values. Source Edit
func err[T, E](R: typedesc[Result[T, E]]; e: sink E): Result[T, E]
-
Returns a result with an error.
Example:
let r = Result[int, string].err("uh-oh") doAssert r.error == "uh-oh"
Source Edit func error[T, E](self: Result[T, E]): lent E {.inline.}
- Retrieves the error from a Result; raises ResultError[void] if the Result is not an error. Source Edit
func filter[T: not void; E](r: Result[T, E]; callback: proc (v: T): bool): Option[ T]
-
See also:
- filterErr for filtering based on
Source Editthe error
func filterErr[T, E](r: Result[T, E]; callback: proc (e: E): bool): Option[E]
-
See also:
- filter for filtering based on the
Source Editvalue
proc flatMap[T: not void; E, R](r: Result[T, E]; callback: proc (v: T): Result[R, E]): Result[R, E] {.effectsOf: callback.}
- See also: Source Edit
proc flatMapErr[T: not void; E, R](r: Result[T, E]; callback: proc (e: E): Result[T, R]): Result[ T, R] {.effectsOf: callback.}
- See also: Source Edit
func initFailure[T, E](self: var Result[T, E]; e: sink E)
- Sets the result as an error. Source Edit
func initSuccess[E](self: var Result[void, E])
-
Sets a result to success.
Example:
var r: Result[void, string] r.initSuccess() doAssert r.isOk
Source Edit proc initSuccess[T, E](self: var Result[T, E]; v: sink T)
- Sets the result to success and updates value. Source Edit
proc map[T: not void; E, R](r: Result[T, E]; callback: proc (v: T): R): Result[ R, E] {.effectsOf: callback.}
- See also: Source Edit
proc mapErr[T: not void; E, R](r: Result[T, E]; callback: proc (e: E): R): Result[ T, R] {.effectsOf: callback.}
- See also: Source Edit
func ok[T, E](R: typedesc[Result[T, E]]; v: sink T): Result[T, E]
-
Returns a result with a success and value.
Example:
let r = Result[int, string].ok(42) doAssert r.value == 42
Source Edit func take[T: not void; E](r: sink Result[T, E]): T
- Returns the result's value if it stores one. Raises the result's error as an exception otherwise Source Edit
func takeErr[T, E](r: sink Result[T, E]): E
- Returns the result's error if it stores one. Raises a ResultError[void] otherwise Source Edit
func unsafeGet[E](self: Result[void, E]) {.inline.}
- Does nothing if Result is set, undefined behavior if unset. See also: Source Edit
Templates
template get[E](self: Result[void, E])
-
Raise error as an Exception if self.isErr.
See also:
Source Edit template get[T, E](self: Result[T, E]; otherwise: T): untyped
-
If self is set, returns the value. Returns otherwise if self is an error.
See also:
Source Edit template get[T, E](self: var Result[T, E]): untyped
-
If self is set, returns the mutable value. Raises self.error as an Exception otherwise.
See also:
Source Edit template get[T: not void; E](self: Result[T, E]): untyped
-
If self is set, returns the value. Raises self.error as an Exception otherwise.
See also:
Source Edit template toException[E](err: E): ResultErrorRef[E]
-
Refer to this for more information.
The returned exception is required to be a ref.
Source Edit