tur/result

(defdata Result :copy [A B] (Ok A) (Err B))

typed Result[A B]: ok value A or err value B.

Parameterized result type, as a REAL SUM (SR2b of docs/archive/sum-representation-plan.md): (Ok A) or (Err B). Runtime layout is the tagged monomorph -- { int tag; union { Ok; Err } } -- 16 bytes (down from the record's 24), one payload slot, no dead arm to zero-fill, so err no longer needs a zero value for A nor ok one for B. A concrete monomorph flows BY VALUE with no per-ctor allocation (SR2a, default since 2026-08-27); an erased generic base still rides the int64 carrier, a heap pointer to the same layout. Tag values follow declaration order: Ok = 0, Err = 1. The inline-C helpers in the codegen preamble (tur_box_ok / tur_box_err / tur_is_ok / tur_ok_value / tur_err_value and the _int/_ptr builders) build and read this exact layout; keep them in lockstep with this declaration.

Since: Phase TC1

(ok [A B])

wrap a success value of type A in a Result[A B].

(ok 42)                        ; => Result int B  (B inferred)
(:: (ok "hi") (Result cstr cstr))

converted to a sum constructor in SR2b -- the dead err arm, and the
`(default-of B)` zero it required, are gone).

Since: Phase TC1 (made polymorphic over A/B as Prereq 3, 2026-06-12;

(err [A B])

wrap an error value of type B in a Result[A B].

(err 404)                       ; => Result A int   (A inferred)
(:: (err "missing") (Result int cstr))

constructor since SR2b -- no more `(default-of A)` for the dead ok arm).

Since: Phase TC1 (made polymorphic as Prereq 3, 2026-06-12; sum

(ok? [A B])

check whether a Result[A B] is ok.

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

Since: Phase TC1

(err? [A B])

check whether a Result[A B] is err.

(err? (err 1))  ; => true

Since: Phase TC1

(ok-val [A B])

extract the ok value from a typed Result[A B].

(let [r (:: (ok 7) (Result int cstr))]
  (ok-val r))  ; => 7

Since: Phase TC1

(err-val [A B])

extract the error value from a typed Result[A B].

(let [r (:: (err "boom") (Result int cstr))]
  (err-val r))  ; => "boom"

Since: Phase TC1

(result-free [r :int])

free a heap-allocated Result[A B].

(result-free my-result)

Since: Phase TC1

(result-map [A B E])

apply a function to the ok value if ok.

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

Since: Phase TC1

(result-eq? [A E])

compare two Result[A B] values.

(result-eq? (ok 1) (ok 1) (fn [a b] (= a b)) (fn [a b] (= a b)))  ; => true

Since: Phase TC1

(definstance Eq [Result])

equality using the ok and err types' Eq instances.

(result-bimap [container :int fn-left fn-right])

map fn-left over the err arm and fn-right over the ok arm.

Follows the Either convention: the err arm is the "left" side and the ok arm is the "right" side. This is the worker behind the Bifunctor [Result] instance (kept here next to the Result layout it depends on).

(result-bimap (ok 5) neg inc)   ; => ok(6)
(result-bimap (err 5) neg inc)  ; => err(-5)

Since: stdlib-hkt-consolidation T1

(definstance Bifunctor [Result])

map fn-left over err, fn-right over ok.

(bimap (ok 5) neg inc)   ; => ok(6)
(bimap (err 5) neg inc)  ; => err(-5)

Since: stdlib-hkt-consolidation T1

(definstance Functor [(Result _ B)])

map a function over the ok payload; err unchanged.

(fmap (:: (ok 21) (Result int int)) (fn [x] (* x 2)))  ; => ok(42)
(fmap (:: (err 5) (Result int int)) (fn [x] (* x 2)))  ; => err(5)

Since: stdlib-hkt-consolidation T4

(definstance Applicative [(Result _ B)])

pure is ok; ap applies an ok function to an ok argument and returns the first err it meets (the function's before the argument's).

(ap (ok (fn [x] (* x 2))) (ok 21))  ; => ok(42)
(ap (ok (fn [x] (* x 2))) (err 5))  ; => err(5)

Since: typeclass-superclasses-plan SC8b

(definstance Monad [(Result _ B)])

bind sequences through ok; short-circuits on err.

(bind (ok 20) (fn [x] (ok (+ x 1))))  ; => ok(21)

Since: stdlib-hkt-consolidation T4

(definstance MonadError [(Result _ B)])

throw-error builds an err; catch-error runs a handler on the err payload (ok values pass through unchanged).

(throw-error 404)                              ; => err(404)
(catch-error (err 5) (fn [e] (ok (* e -1))))   ; => ok(-5)
(catch-error (ok 7) (fn [e] (ok 0)))           ; => ok(7)

Since: stdlib-hkt-consolidation T4