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, orthrows Ewhen there is no answer, and leaving withthrow. - 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 withtry?. - Passing an error to the caller with plain
try, and adding context on the way withcatch { 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,AssertandDebugAssertfor 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
| Lesson | What you will learn | |
|---|---|---|
| 9.1 | Fallible | return a value or throw an error with -> T throws E, and handle it with try and catch |
| 9.2 | Fail | leave a function with an error using throw |
| 9.3 | Unit fallible | a function that returns nothing but can still throw: func F() throws E |
| 9.4 | Outcome | keep an outcome as Core's Result<T, E> and match .Success or .Failure |
| 9.5 | Discard | why a call that can throw must be marked, and how to drop its error on purpose with try? or catch { _ => {} } |
| 9.6 | Catch | handle each way an operation can fail with try ... catch { arms } |
| 9.7 | Catch fallback | turn any error into a default value with catch { _ => ... } or (try? F()) ?? fallback |
| 9.8 | Propagate | pass an error straight to the caller with plain try instead of catching it |
| 9.9 | Error variant | describe the ways an operation can fail with a variant |
| 9.10 | Error mapping | add context to an error as it passes through with try F() catch { e => throw Mapped(e) } |
| 9.11 | Error sum | throw more than one kind of error with throws A | B |
| 9.12 | Fallible main | let Main throw with func Main() throws E, and see the exit status |
| 9.13 | Absence to error | turn a missing value into an error with ?? throw |
| 9.14 | Nested fallible | keep levels apart: -> T? throws E and -> Result<T, E1> throws E2 |
| 9.15 | Panic | stop the program when something impossible happens |
| 9.16 | Assert | check 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.