Propagate
Handling an error with catch is right when this function is the one that should decide what a failure means. Often it is not. The function is a step in the middle, and an error should simply become the caller's problem.
Plain try does exactly that. On success, try step is the value. On failure, the enclosing function throws that same error at once, and nothing after the call runs.
The long way
Written by hand, passing an error on is the same arm every time: catch the error and throw it again unchanged.
let high = try ReadDigit(tens) catch { error => throw error };
let low = try ReadDigit(units) catch { error => throw error };
TwoDigitsByHand writes that arm twice, once per digit. The two arms are near-identical and say nothing new.
The same with plain try
Plain try is that arm written once. The success values are used straight away:
func TwoDigits(tens: char, units: char) -> int throws DigitError {
let high = try ReadDigit(tens);
let low = try ReadDigit(units);
return high * 10 + low;
}
flowchart LR
step["`try ReadDigit(tens)`"] --> q{"Success or error?"}
q -- "success" --> go["the expression is the digit;<br/>`TwoDigits` carries on"]
q -- "error" --> out["`TwoDigits` throws at once<br/>with the same error"]
out --> caller["the caller's `catch`<br/>sees the original error"]Both versions behave identically: plain try is shorthand, not a different rule. When both digits are wrong, only the first one is reported — the first try leaves, and the second read never happens.
The error travels intact
Neither TwoDigits nor try looked at the error, yet the caller still learns which character was wrong:
DigitError::NotADigit(c) => PrintLine("'{}' is not a digit", c)
Show takes the reader as a function value, read: func(char, char) -> int throws DigitError. Its type throws, so calling read(tens, units) is a throw site like any other, and the try block in Show covers it.
Two requirements
Passing an error on asks two things of the function doing it:
- It must throw, since that is where the error goes.
Mainreturns a plainint, sotry ReadDigit('4')there is rejected. - The error must fit its
throwsclause. Here both areDigitError, so it passes through as is. An error is never converted on the way: a different error type needs Error mapping, or an error sum that includes it.
| Tool | Who decides what an error means | The function |
|---|---|---|
try ... catch { arms } | this function | throws only if you choose |
plain try | the caller | throws, with an error that fits |
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// Handling an error with `catch` is right when this function is the one that should decide what
// a failure means. Often it is not: the function is a step in the middle, and an error should
// simply become the caller's problem.
//
// Written by hand that is the same arm every time: catch the error and throw it again unchanged,
// `e => throw e`. Plain `try` is that arm written once. On success, `try step` is the value. On
// failure, the enclosing function throws that same error at once, and nothing after the call
// runs.
import Io::PrintLine;
variant DigitError {
Blank,
NotADigit(char)
}
// One small step that can fail.
func ReadDigit(c: char) -> int throws DigitError {
if c == ' ' {
throw DigitError::Blank;
}
if c < '0' || c > '9' {
throw DigitError::NotADigit(c);
}
return (c as int) - ('0' as int);
}
// The long way. Each error is caught only to be thrown straight back to the caller: two
// near-identical arms that say nothing new.
func TwoDigitsByHand(tens: char, units: char) -> int throws DigitError {
let high = try ReadDigit(tens) catch { error => throw error };
let low = try ReadDigit(units) catch { error => throw error };
return high * 10 + low;
}
// The same function with plain `try`. The success values are used straight away.
func TwoDigits(tens: char, units: char) -> int throws DigitError {
let high = try ReadDigit(tens);
let low = try ReadDigit(units);
return high * 10 + low;
}
// `read` is a function value whose type throws, so calling it is a throw site like any other.
func Show(read: func(char, char) -> int throws DigitError, tens: char, units: char) {
try {
let value = read(tens, units);
PrintLine("read {}", value);
} catch {
DigitError::Blank => PrintLine("a digit is missing"),
DigitError::NotADigit(c) => PrintLine("'{}' is not a digit", c)
}
}
func Main() -> int {
Show(TwoDigits, '4', '2');
Show(TwoDigits, '4', 'x');
Show(TwoDigits, '?', '2');
Show(TwoDigits, ' ', '7');
// Both versions behave identically: plain `try` is shorthand, not a different rule.
Show(TwoDigitsByHand, '4', 'x');
// The error travels intact. Neither `TwoDigits` nor `try` looked at it, yet the caller still
// learns which character was wrong.
//
// Passing an error on has two requirements. The function doing it must itself throw, since
// that is where the error goes. In `Main`, which returns a plain `int`, `try ReadDigit('4')`
// is rejected: "call to 'ReadDigit' can throw 'DigitError', but 'Main' does not throw". And
// the error must fit that function's `throws` clause. Here both are `DigitError`, so it
// passes through as is.
return 0;
}
Run it
cd Examples/Errors/Propagate
rux run
read 42
'x' is not a digit
'?' is not a digit
a digit is missing
'x' is not a digit
Common mistakes
Try it yourself
- Add
Show(TwoDigits, ' ', 'x');and predict which of the two messages it prints. - Write
ThreeDigits(hundreds: char, tens: char, units: char) -> int throws DigitErrorwith three plaintrys. - Rewrite
ThreeDigitsto callTwoDigitsfor the last two digits. Does that call need anything special?
Learn more
- Optional propagate — postfix
?for absence - Error mapping — adding context on the way through
- Fallible main — plain
tryat the top level of a program - Passing errors on in the Rux Reference