Unit fallible
Some operations have no answer to give back. When a withdrawal works, the money is gone from the account and there is nothing more to say. But it can still fail, and the caller still needs to know.
Such a function declares only its error, after the parameters: func Withdraw(...) throws ShortOfFunds, with no return type.
throws E with no return type
The success of such a function carries the unit () — the empty tuple, whose only value is also written (). It is a success that carries no information beyond "it worked". Writing -> () throws ShortOfFunds means the same thing; the short form is what you will see everywhere:
func Withdraw(account: &var Account, amount: int) throws ShortOfFunds {
The account is a mutable reference, so the function changes the caller's account in place. The only thing left to report is whether that happened.
Three ways out
Because there is no value to return, the function succeeds simply by reaching its end. A bare return; succeeds early, and only throw makes it fail:
if amount == 0 {
// Nothing to do, and that counts as success.
return;
}
if amount > account.balance {
throw ShortOfFunds { missing: amount - account.balance };
}
account.balance -= amount;
// Falling off the end: success.
| The function… | The outcome |
|---|---|
| reaches its closing brace | success |
runs return; | success, early |
runs throw error; | failure, carrying error |
Calling it
No value comes back, but the error still can, so the call is still marked with try. In a try block, the statement after the call runs only when the withdrawal worked:
try {
Withdraw(account, amount);
PrintLine("take {}: done, {} left", amount, account.balance);
} catch {
error => PrintLine("take {}: refused, {} short", amount, error.missing)
}
There is nothing to bind on success, so there is no let — the call is a statement of its own. The single arm error => ... binds the ShortOfFunds and reads how much was missing.
The output follows the balance as it changes. Taking 0 succeeds without touching anything, 80 is refused while 60 is left, and the next 60 empties the account — so even 1 is refused after that.
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// Some operations have no answer to give back. When a withdrawal works, the money is gone from
// the account and there is nothing more to say. Such a function declares only its error, after
// the parameters: `func Withdraw(...) throws ShortOfFunds`, with no return type.
//
// The success then carries the unit `()`, the empty tuple — a success that carries no
// information beyond "it worked". Because there is no value to return, the function succeeds
// simply by reaching its end. A bare `return;` succeeds early, and only `throw` makes it fail.
import Io::PrintLine;
struct Account {
balance: int;
}
struct ShortOfFunds {
missing: int;
}
// Changes the account in place; the only thing to report is whether that happened.
func Withdraw(account: &var Account, amount: int) throws ShortOfFunds {
if amount == 0 {
// Nothing to do, and that counts as success.
return;
}
if amount > account.balance {
throw ShortOfFunds { missing: amount - account.balance };
}
account.balance -= amount;
// Falling off the end: success.
}
func Attempt(account: &var Account, amount: int) {
// The call is still marked with `try`: it returns nothing, but it can throw. The statement
// after it runs only when the withdrawal worked.
try {
Withdraw(account, amount);
PrintLine("take {}: done, {} left", amount, account.balance);
} catch {
error => PrintLine("take {}: refused, {} short", amount, error.missing)
}
}
func Main() -> int {
var account = Account { balance: 100 };
Attempt(account, 40);
Attempt(account, 0);
Attempt(account, 80);
Attempt(account, 60);
Attempt(account, 1);
return 0;
}
Run it
cd Examples/Errors/UnitFallible
rux run
take 40: done, 60 left
take 0: done, 60 left
take 80: refused, 20 short
take 60: done, 0 left
take 1: refused, 1 short
Common mistakes
Try it yourself
- Change the signature to the long spelling
-> () throws ShortOfFundsand check that the program still compiles and prints the same. - Add
Deposit(account: &var Account, amount: int) throws TooMuchthat refuses when the balance would pass 1000, and call it from atryblock. - Put a second
Withdrawcall inAttempt'stryblock. What does the program print when the first one is refused?
Learn more
- Fail — leaving through the error channel with
throw - Discard — the deliberate way to drop an error
- Tuple — the empty tuple
()is the unit - Mutable reference — how
Withdrawchanges the caller's account