Skip to content

Latest commit

 

History

History
86 lines (66 loc) · 3.63 KB

contracts.md

File metadata and controls

86 lines (66 loc) · 3.63 KB

Contracts (C++26)

Express a function's preconditions, postconditions, and internal assertions in the language itself, with configurable checking. Keywords: pre, post, contract_assert · Since: C++26

Mental model

A contract assertion states a bool predicate that's expected to hold at a point in execution. Three forms:

int factorial(int n)
    pre (n >= 0)              // precondition: checked on entry
    post(r: r >= 1)           // postcondition: `r` names the return value
{
    contract_assert(n < 13);  // assertion: checked at this point in the body
    return n <= 1 ? 1 : n * factorial(n - 1);
}

pre/post are function contract specifiers (after the parameter list); contract_assert(cond); is a statement usable anywhere in a body.

Evaluation semantics — checking is configurable

A contract assertion is evaluated under one of four implementation-chosen semantics:

Semantic Checks predicate? Terminates on violation?
ignore no —
observe yes no (calls the handler, then continues)
enforce yes yes (handler, then terminate)
quick-enforce yes yes (terminate immediately)

Which one applies is implementation-defined (typically a build flag), so the same contract can be off in a release build and enforced in a debug/hardened build.

Contract violations

When a checking semantic finds the predicate false (or it throws), a contract violation occurs and the contract-violation handler is invoked:

#include <contracts>

// the program's handler (implementation provides a default; whether you can
// replace it is implementation-defined):
void handle_contract_violation(const std::contracts::contract_violation&);

It receives a const std::contracts::contract_violation& describing the failure (location, kind, the predicate's source text where available). Under enforce the program is then contract-terminated; under observe execution continues.

Why use them

  • Document and enforce the API's expectations at the boundary, in the signature, instead of in comments or scattered asserts.
  • Tunable cost: ship with contracts ignored in hot release paths, enforced in tests/hardened builds — no source changes.
  • A richer replacement for assert (contract_assert) and for hand-written precondition checks.

Gotchas

  • The predicate may be evaluated zero or more times (even repeated), and may be skipped under ignore — so contract predicates must be side-effect-free. pre((count++, true)) is a bug: the increment might or might not happen.
  • post(r: ...) binds the return value to a name you choose (here r) — that's how a postcondition refers to the result.
  • Differing semantics across translation units can break the ODR if a predicate has side effects affecting a constant expression — another reason to keep them pure.
  • C++26, very early support. Feature-test with __cpp_contracts (202502L); this is one of the last C++26 features to land and tooling is nascent. It is not the older Contracts TS (which was removed from C++20). The examples here were checked with GCC 16 (plain -std=c++26; the handler type lives in <contracts>); Clang 22 doesn't implement them yet.

See also