Out parameter

// An out-parameter is a pointer the caller hands over so a function can write its answer into
// the caller's own variable. The caller passes `@share`; the function writes `*result = ...`.
// The return value is then free to say something else, usually whether the answer is good.
//
// Older code and some of the standard library work this way, so it is worth reading fluently.
// But it has two weak spots. The caller must have a variable ready before the call, and nothing
// forces anyone to look at the flag: ignore it, and the variable quietly keeps a stale value.
//
// A fallible `T ! E` closes both gaps. The answer only exists on success, and a result that is
// left unhandled is a compile error. For new code, prefer it; reach for an out-parameter when
// an existing API asks for one.
import Core::ConvertChecked;
import Io::PrintLine;

// Out-parameter style: the answer goes through `result`, and the `bool` says whether to trust it.
func PercentOf(part: int, whole: int, result: *var int) -> bool {
    if whole == 0 {
        return false;
    }
    *result = part * 100 / whole;
    return true;
}

struct ZeroWhole {}

// The same question as a fallible. The answer and the failure travel on separate channels.
func Percent(part: int, whole: int) -> int ! ZeroWhole {
    if whole == 0 {
        fail ZeroWhole {};
    }
    return part * 100 / whole;
}

func Main() -> int {
    var share: int = 0;
    if PercentOf(3, 4, @share) {
        PrintLine("3 of 4 is {}%", share);
    }

    // The mistake the compiler cannot see: the flag is dropped, nothing was written, and `share`
    // still says 75 from the call before.
    PercentOf(1, 0, @share);
    PrintLine("1 of 0, flag ignored: {}%", share);

    // The standard library uses out-parameters too. `ConvertChecked` writes the converted value
    // and returns `true` when something was lost, which is the opposite of `PercentOf` above.
    // With a bare `bool`, only the documentation tells you which way round it reads.
    var narrowed: int8 = 0;
    let lost = ConvertChecked<int, int8>(300, @narrowed);
    PrintLine("300 into int8: lost {}, wrote {}", lost, narrowed);

    // The fallible needs no variable prepared in advance, and it cannot be ignored: a bare
    // `Percent(1, 0);` is rejected. The failure has to be dealt with, here by `catch`.
    let good = Percent(3, 4) catch { else => -1 };
    let bad = Percent(1, 0) catch { else => -1 };
    PrintLine("fallible: {}% and {}%", good, bad);
    return 0;
}