#Contract
Status: standard library specification draft.
This chapter defines the development precondition helper in std.contract.
It is an ordinary hd function over the language-tier panic function.
#Require
require checks a caller-supplied condition before work continues:
use std.contract.require
fn debit(balance: i64, amount: i64) -> i64:
require:
amount > 0
require("balance must cover the amount"):
balance >= amount
balance - amount- std-contract.require.decl
std.contractdeclarespub fn require[F < Fn() -> bool](message: string = "requirement failed", condition: F) -> void, withFnfromstd.function. - std-contract.require.debug-onceIn a debug or test build, a
requirecall evaluatesconditionexactly once. - std-contract.require.debug-passIn a debug or test build, if
conditionreturns true,requirereturns without panicking. - std-contract.require.debug-failIn a debug or test build, if
conditionreturns false,requirecalls the preludepanicwithmessage. Panic:explicit-panic. - std-contract.require.read-only
conditionis anFnargument, so byfn.trait.read-onlyit does not change a capture. A closure that does is an error. Error:not-writable. - std-contract.require.read-refsBy
ref.generic.outlives.argument, a closure written as theconditionargument may read local references, such asselfin a&mut selfmethod, for the call. - std-contract.require.releaseIn a release build,
requirereturns without callingcondition. Its arguments are evaluated as for any call, and release optimization removes the ones nothing uses.
Why. Precondition failures are development checks. The paired declarations remain checked in every profile, while a release build pays no runtime cost.
#Ensure
ensure registers a postcondition for the normal exits of its calling scope.
- std-contract.ensure.guard
std.contractdeclarespub struct EnsureGuard[F < Fn() -> bool & 'a, 'a], which holds a private message and condition. - std-contract.ensure.protocol
EnsureGuard[F, 'a]implementsAutoClosingandDisposable; itsdisposeevaluates the condition exactly once. - std-contract.ensure.decl
std.contractdeclares@auto_closing pub fn ensure[F < Fn() -> bool & 'a, 'a](message: string, condition: F) -> EnsureGuard[F, 'a]. - std-contract.ensure.passAt a normal exit, a true condition completes silently.
- std-contract.ensure.failAt a normal exit, a false condition calls the prelude
panicwithmessage. Panic:explicit-panic. - std-contract.ensure.read-onlyThe condition is an
Fnargument, so it may read captured local references but does not change a capture. Error:not-writable. - std-contract.ensure.resultThe condition receives no result argument; a postcondition about the result stores it in a local that the condition captures.
- std-contract.ensure.orderThe guard is registered by the statement call and shares the cleanup stack and last-in, first-out order specified by
flow.auto-closing.statementandflow.auto-closing.order.
Why. A postcondition belongs at scope exit, next to the local state it checks, while
Fnprevents the check itself from changing that state.