Express a function's preconditions, postconditions, and internal assertions in the language itself, with configurable checking. Keywords:
pre,post,contract_assert· Since: C++26
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.
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.
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.
- 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.
- 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 (herer) — 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.