v0.4.0
Errors · Lesson 9.8

Propagate

Source
Hand an error to the caller with plain try, which keeps the success and passes the error on unchanged.
You'll need: Outcome, Catch

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:

  1. It must throw, since that is where the error goes. Main returns a plain int, so try ReadDigit('4') there is rejected.
  2. The error must fit its throws clause. Here both are DigitError, 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.
ToolWho decides what an error meansThe function
try ... catch { arms }this functionthrows only if you choose
plain trythe callerthrows, with an error that fits

The program

The whole lesson is one package in the Examples repository. Its comments explain every step.

Src/Main.rux
// 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

  1. Add Show(TwoDigits, ' ', 'x'); and predict which of the two messages it prints.
  2. Write ThreeDigits(hundreds: char, tens: char, units: char) -> int throws DigitError with three plain trys.
  3. Rewrite ThreeDigits to call TwoDigits for the last two digits. Does that call need anything special?

Learn more