v0.4.0
Errors · Lesson 9.13

Absence to error

Source
Turn a missing value into an error that says what was missing, with option ?? throw.
You'll need: Coalesce, Fail

An optional says "nothing here" and stops there. PriceOf(7) returns none, and none cannot say which code was missing or why that matters. When absence is a real problem for the caller, turn it into an error that does say so.

?? throw

A small price list where an unknown code is simply absent:

func PriceOf(code: int) -> int? {
    return match code {
        1 => 250,
        2 => 120,
        3 => 75,
        _ => none
    };
}

Total needs a price, and a missing one is an error worth reporting:

func Total(code: int, quantity: int) -> int throws UnknownProduct {
    let price = PriceOf(code) ?? throw UnknownProduct { code: code };
    return price * quantity;
}

This is the ?? from Coalesce, with throw as its fallback — just as Coalesce exit used return. When the price is present, price is that number. When it is absent, the function throws right there, and the error can carry whatever context is at hand — here, the code that was not found.

flowchart LR
    look["`PriceOf(code)`"] --> q{"Present or `none`?"}
    q -- "present" --> price["`price` is the number;<br/>`Total` carries on"]
    q -- "`none`" --> thrown["`throw UnknownProduct { code }`"]
    thrown --> caller["the caller learns<br/>which code was missing"]

PriceOf itself cannot throw, so its call needs no try. Only Total throws, and Order handles that with a try block and one catch arm.

The error is built only when needed

Like every ?? fallback, the right side runs only when it is needed. For a product that exists, the UnknownProduct value is never even built.

Why not ?

On an optional, ? passes the absence on — but only as absence. It works in a function that returns an optional, and Total returns an int and throws. ? never invents an error for a missing value; ?? throw is how you supply one yourself.

You writeWhen the price is missing, Total…
PriceOf(code) ?? 0carries on with 0, so the order costs nothing
PriceOf(code) ?? return …succeeds at once with the value given to return
PriceOf(code)?is rejected: Total does not return an optional
PriceOf(code) ?? throw …throws, saying which code it was

The program

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

Src/Main.rux
// An optional says "nothing here" and stops there. `PriceOf(7)` returns
// `none`, and `none` cannot say which code was missing or why that matters.
// When absence is a real problem for the caller, turn it into an error that
// does say so:
//
//     let price = PriceOf(code) ?? throw UnknownProduct { code: code };
//
// This is the `??` from the optionals part with `throw` as its fallback. When
// the price is present, `price` is that number. When it is absent, the
// function throws right there, and the error can carry whatever context is at
// hand — here, the code that was not found.
//
// Like every `??` fallback, the right side runs only when it is needed, so
// the error is not even built for a product that exists.
import Io::PrintLine;

struct UnknownProduct {
    code: int;
}

// A small price list. An unknown code is simply absent.
func PriceOf(code: int) -> int? {
    return match code {
        1 => 250,
        2 => 120,
        3 => 75,
        _ => none
    };
}

func Total(code: int, quantity: int) -> int throws UnknownProduct {
    let price = PriceOf(code) ?? throw UnknownProduct { code: code };
    return price * quantity;
}

// The caller handles the error at the call: `try` marks the call that can
// throw, and the `catch` arm runs only when it does.
func Order(code: int, quantity: int) {
    try {
        let total = Total(code, quantity);
        PrintLine("{} x product {}: {} cents", quantity, code, total);
    } catch {
        e => PrintLine("{} x product {}: no product has code {}", quantity, code, e.code)
    }
}

func Main() -> int {
    Order(1, 2);
    Order(3, 4);
    Order(7, 1);
    return 0;
}

Run it

cd Examples/Errors/AbsenceToError
rux run
2 x product 1: 500 cents
4 x product 3: 300 cents
1 x product 7: no product has code 7

Common mistakes

Try it yourself

  1. Add product 4 at 990 cents and order three of them.
  2. Refuse an order of zero items as well. One error struct no longer fits — try a variant with an UnknownCode(int) case and a NoItems case.
  3. Change Order(7, 1) to use PriceOf(7) ?? 0 directly in Main instead of Total. What does the customer pay for an unknown product?

Learn more