v0.4.0

Part 9: Errors

An optional can say that a value is missing, but never why. This part gives a failure a voice. A function declared -> T throws E returns a T or throws an error of type E saying what went wrong, and the compiler makes sure no error is ever dropped without the code saying so: every call that can throw is marked with try. By the end of the part you can write functions that fail precisely, decide at each call whether to handle an error or pass it on, and tell a failure the caller can fix from a bug that should stop the program.

What you will learn

  • Declaring an error with -> T throws E, or throws E when there is no answer, and leaving with throw.
  • Marking every throwing call with try, and why an unmarked call does not compile.
  • Handling an error with try ... catch — one arm per case, or one _ fallback for all — and dropping it on purpose with try?.
  • Passing an error to the caller with plain try, and adding context on the way with catch { e => throw Mapped(e) }.
  • Keeping an outcome that must outlive its call in Core's Result<T, E>.
  • Designing error types: a variant of cases, or a sum of unrelated errors A | B.
  • A throwing Main, turning absence into an error with ?? throw, and nesting -> T? throws E.
  • Panic, Assert and DebugAssert for the situations only a bug can reach.

Which error tool?

Most of this part is choosing the right tool for one moment in the code. The questions run in this order:

flowchart TD
    start(["Something can go wrong"]) --> bug{"Can it happen in a<br/>program with no bugs?"}
    bug -- "no, only a bug" --> stop["`Panic`, `Assert`, `DebugAssert`<br/>9.15–9.16"]
    bug -- "yes" --> why{"Does the caller need<br/>to know why?"}
    why -- "no" --> opt["An optional `T?`<br/>Part 8"]
    why -- "yes" --> fal["`-> T throws E`, or `throws E`<br/>9.1–9.3"]
    fal --> who{"Who decides what<br/>the error means?"}
    who -- "this function" --> reason{"Does the reason<br/>matter here?"}
    reason -- "yes" --> arms["`try ... catch` with<br/>one arm per case<br/>9.6"]
    reason -- "no" --> fallback["`catch { _ => fallback }`, `try?`<br/>or a deliberate drop<br/>9.5, 9.7"]
    who -- "later, as data" --> keep["a stored `Result<T, E>`<br/>9.4"]
    who -- "the caller" --> same{"Does the error already<br/>fit the caller's type?"}
    same -- "yes" --> q["plain `try` passes it on<br/>9.8, 9.11"]
    same -- "no, or context to add" --> mapped["`catch { e => throw Mapped(e) }`<br/>9.10"]

Lessons

LessonWhat you will learn
9.1Falliblereturn a value or throw an error with -> T throws E, and handle it with try and catch
9.2Failleave a function with an error using throw
9.3Unit falliblea function that returns nothing but can still throw: func F() throws E
9.4Outcomekeep an outcome as Core's Result<T, E> and match .Success or .Failure
9.5Discardwhy a call that can throw must be marked, and how to drop its error on purpose with try? or catch { _ => {} }
9.6Catchhandle each way an operation can fail with try ... catch { arms }
9.7Catch fallbackturn any error into a default value with catch { _ => ... } or (try? F()) ?? fallback
9.8Propagatepass an error straight to the caller with plain try instead of catching it
9.9Error variantdescribe the ways an operation can fail with a variant
9.10Error mappingadd context to an error as it passes through with try F() catch { e => throw Mapped(e) }
9.11Error sumthrow more than one kind of error with throws A | B
9.12Fallible mainlet Main throw with func Main() throws E, and see the exit status
9.13Absence to errorturn a missing value into an error with ?? throw
9.14Nested falliblekeep levels apart: -> T? throws E and -> Result<T, E1> throws E2
9.15Panicstop the program when something impossible happens
9.16Assertcheck an assumption while the program runs

Before you start

Finish Part 8: Optionals first — errors are built on the same ideas, and several lessons compare the two side by side. You also need variants from Part 6 and the patterns of Part 7. Each lesson's package is in the Examples repository's Errors/ folder:

cd Examples/Errors/Fallible
rux run

After this part

Part 10: Sum types takes the A | B you met in Error sum and makes it a type of its own, usable anywhere. Before moving on, try the checkpoint project Calculator: it evaluates sums and key-press tapes where every way a calculation can fail is a case of an error variant.

For the rules behind this part, see Errors, Handling errors, Passing errors on and Panics in the Rux Reference, and Panic and Assert in the API reference.