hd-lang

#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
  1. std-contract.require.declstd.contract declares pub fn require[F < Fn() -> bool](message: string = "requirement failed", condition: F) -> void, with Fn from std.function.
  2. std-contract.require.debug-onceIn a debug or test build, a require call evaluates condition exactly once.
  3. std-contract.require.debug-passIn a debug or test build, if condition returns true, require returns without panicking.
  4. std-contract.require.debug-failIn a debug or test build, if condition returns false, require calls the prelude panic with message. Panic: explicit-panic.
  5. std-contract.require.read-onlycondition is an Fn argument, so by fn.trait.read-only it does not change a capture. A closure that does is an error. Error: not-writable.
  6. std-contract.require.read-refsBy ref.generic.outlives.argument, a closure written as the condition argument may read local references, such as self in a &mut self method, for the call.
  7. std-contract.require.releaseIn a release build, require returns without calling condition. 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.

  1. std-contract.ensure.guardstd.contract declares pub struct EnsureGuard[F < Fn() -> bool & 'a, 'a], which holds a private message and condition.
  2. std-contract.ensure.protocolEnsureGuard[F, 'a] implements AutoClosing and Disposable; its dispose evaluates the condition exactly once.
  3. std-contract.ensure.declstd.contract declares @auto_closing pub fn ensure[F < Fn() -> bool & 'a, 'a](message: string, condition: F) -> EnsureGuard[F, 'a].
  4. std-contract.ensure.passAt a normal exit, a true condition completes silently.
  5. std-contract.ensure.failAt a normal exit, a false condition calls the prelude panic with message. Panic: explicit-panic.
  6. std-contract.ensure.read-onlyThe condition is an Fn argument, so it may read captured local references but does not change a capture. Error: not-writable.
  7. std-contract.ensure.resultThe condition receives no result argument; a postcondition about the result stores it in a local that the condition captures.
  8. 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.statement and flow.auto-closing.order.

Why. A postcondition belongs at scope exit, next to the local state it checks, while Fn prevents the check itself from changing that state.