Fallible

// An optional says that a value is missing, but never why. Often the why is exactly what the
// caller needs: dividing 12 by 0 and dividing 13 by 4 both fail to give an exact answer, for
// different reasons that deserve different replies.
//
// `int ! DivideError` reads "an `int`, or else a `DivideError`". A fallible like this has two
// channels. The success channel holds the answer. The failure channel holds an error, a value
// describing what went wrong. The error type is whatever suits, and a variant is a natural fit:
// one case for each way the operation can go wrong.
//
// The success needs no ceremony. `return value;` in a fallible function is the success, just as a
// plain value returned from an `int?` function is a present one.
import Io::PrintLine;

// The ways an exact division can go wrong. `NotExact` carries the remainder with it.
variant DivideError {
    ByZero,
    NotExact(int)
}

// The signature says it all: this produces an `int`, or a `DivideError`. `fail`, the subject of
// the next lesson, leaves through the failure channel; an ordinary `return` is the success.
func ExactDivide(numerator: int, denominator: int) -> int ! DivideError {
    if denominator == 0 {
        fail DivideError::ByZero;
    }
    if numerator % denominator != 0 {
        fail DivideError::NotExact(numerator % denominator);
    }
    return numerator / denominator;
}

// To use the answer, find out which channel it came through. `.Success(value)` matches the answer
// and binds it; `.Failure(error)` matches an error and binds that. The error is an ordinary
// `DivideError`, so a second match picks out its case.
func Report(numerator: int, denominator: int) {
    match ExactDivide(numerator, denominator) {
        .Success(value) => PrintLine("{} / {} = {}", numerator, denominator, value),
        .Failure(error) => Explain(numerator, denominator, error)
    }
}

func Explain(numerator: int, denominator: int, error: DivideError) {
    match error {
        DivideError::ByZero => PrintLine("{} / {} fails: no dividing by zero", numerator,
            denominator),
        DivideError::NotExact(remainder) => PrintLine("{} / {} fails: {} left over", numerator,
            denominator, remainder)
    }
}

func Main() -> int {
    Report(12, 4);
    Report(12, 0);
    Report(13, 4);

    // A fallible is not an `int` until it has been opened. `let half = ExactDivide(12, 2) / 2;`
    // is rejected, and so is calling `ExactDivide(12, 4);` and ignoring what comes back: a
    // failure can never be dropped without the code saying so.
    return 0;
}