tur/result

(ok [x :int] :ptr<void>)

wrap a value in an ok result.

A heap-allocated ok result as :ptr<void>.

  (ok 42)  ; => ok(42)

(err [e :int] :ptr<void>)

wrap a value in an err result.

A heap-allocated err result as :ptr<void>.

  (err 1)  ; => err(1)

(ok? [r :ptr<void>] :bool)

check whether a result is ok.

true if r is an ok result, false otherwise.

  (ok? (ok 1))   ; => true
  (ok? (err 0))  ; => false

(err? [r :ptr<void>] :bool)

check whether a result is err.

true if r is an err result (or NULL), false otherwise.

  (err? (err 0))  ; => true
  (err? (ok 1))   ; => false

(ok-val [r :ptr<void>] :int)

extract the ok value from a result.

The contained ok value as :int.

  (ok-val (ok 5))  ; => 5

(err-val [r :ptr<void>] :int)

extract the err value from a result.

The contained err value as :int.

  (err-val (err 99))  ; => 99

(result-unwrap [r :ptr<void>] :int)

extract the ok value, aborting the process if r is err.

The contained ok value as :int.

  (result-unwrap (ok 7))  ; => 7

(result-unwrap-or [r :ptr<void> default_val :int] :int)

extract the ok value, or return a default if r is err.

The ok value if r is ok, otherwise default_val.

  (result-unwrap-or (err 0) 99)  ; => 99

(result-expect [r :ptr<void> msg :cstr] :int)

extract the ok value, aborting with a custom message if r is err.

The contained ok value as :int.

  (result-expect r "parse failed")  ; => ok value or abort

(result-map [r :ptr<void> f :ptr<void>] :ptr<void>)

apply a function to the ok value, propagating err unchanged.

A new ok result with the mapped value, or r unchanged if r is err.

  (result-map (ok 3) (fn [x] (* x 2)))  ; => ok(6)

(result-map-err [r :ptr<void> f :ptr<void>] :ptr<void>)

apply a function to the err value, propagating ok unchanged.

A new err result with the mapped error, or r unchanged if r is ok.

  (result-map-err (err 1) (fn [e] (+ e 100)))  ; => err(101)

(result-flat-map [r :ptr<void> f :ptr<void>] :ptr<void>)

chain a fallible computation over an ok result.

The result of applying f to the ok value, or r unchanged if r is err.

  (result-flat-map (ok 5) (fn [x] (if (> x 0) (ok x) (err -1))))  ; => ok(5)

(result-or [r :ptr<void> alt :ptr<void>] :ptr<void>)

return r if ok, otherwise return the fallback result.

r if r is ok, otherwise alt.

  (result-or (err 0) (ok 99))  ; => ok(99)

(result-or-else [r :ptr<void> f :ptr<void>] :ptr<void>)

return r if ok, otherwise compute a fallback by calling f with the err value.

r if r is ok, otherwise the result of f(err-value).

  (result-or-else (err 1) (fn [e] (ok 0)))  ; => ok(0)

(ok-or [opt :ptr<void> e :int] :ptr<void>)

convert an option to a result, using e as the error value if the option is none.

ok(value) if opt is some(value), err(e) if opt is none.

  (ok-or (some 7) -1)  ; => ok(7)
  (ok-or (none) -1)    ; => err(-1)

(err-context [r :ptr<void> ctx :cstr] :ptr<void>)

prepend context text to an err value's message string.

A new err result whose message is "ctx: original", or r unchanged if r is ok.

  (err-context (err my-msg) "loading config")

(result-eq? [r1 r2 ok-cmp err-cmp] :bool)

compare two results using separate comparators for ok and err values.

Since: Phase E1

(definstance Eq [result])

Eq: structural equality via result-eq?.

(result-free [r :ptr<void>])

free the heap memory for a result value.

(result-free my-result)

(result-collect [v :ptr<void>] :ptr<void>)

collect a vec of results into a single result.

ok(vec-of-ok-values) if every element is ok,
  or err(first-err-value) on the first err encountered.

  (result-collect my-results-vec)  ; => ok(vec) or err(e)

(result-partition [v :ptr<void>] :ptr<void>)

split a vec of results into separate ok and err vecs.

A pair (:ptr<void>) with fields ok_vec and err_vec.
  Use result-partition-ok and result-partition-err to access each vec.

  (let [pair (result-partition my-vec)]
    (result-partition-ok pair))

(result-partition-ok [pair :ptr<void>] :ptr<void>)

extract the ok-vec from a result-partition pair.

The vec (:ptr<void>) of ok values.

  (result-partition-ok (result-partition my-vec))

(result-partition-err [pair :ptr<void>] :ptr<void>)

extract the err-vec from a result-partition pair.

The vec (:ptr<void>) of err values.

  (result-partition-err (result-partition my-vec))

(result-must [r :ptr<void>] :int)

unwrap the ok value or panic with a default message.

Since: Phase R4

(result-must-msg [r :ptr<void> msg :cstr] :int)

unwrap the ok value or panic with a caller-supplied message.

Since: Phase R4

(definstance Foldable [ptr<void>])

Foldable: foldl and foldr over the ok value.

(definstance Bifunctor [ptr<void>])

Bifunctor: bimap over ok and err values.

(definstance Functor [ptr<void>])

Functor: fmap over the ok value.

(definstance Applicative [ptr<void>])

Applicative: pure and ap.

(definstance Monad [ptr<void>])

Monad: bind (flat-map over the ok value).