17 Language support library [support]

17.10 Contract-violation handling [support.contract]

17.10.1 Header <contracts> synopsis [contracts.syn]

The header <contracts> defines types for reporting information about contract violations ([basic.contract.eval]).

// all freestanding namespace std::contracts { enum class assertion_kind : unspecified { pre = 1, post = 2, assert = 3 }; enum class evaluation_semantic : unspecified { ignore = 1, observe = 2, enforce = 3, quick_enforce = 4 }; enum class detection_mode : unspecified { predicate_false = 1, evaluation_exception = 2 }; class contract_violation { // no user-accessible constructor public: contract_violation(const contract_violation&) = delete; contract_violation& operator=(const contract_violation&) = delete; see below ~contract_violation(); const char* comment() const noexcept; contracts::detection_mode detection_mode() const noexcept; exception_ptr evaluation_exception() const noexcept; bool is_terminating() const noexcept; assertion_kind kind() const noexcept; source_location location() const noexcept; evaluation_semantic semantic() const noexcept; }; void invoke_default_contract_violation_handler(const contract_violation&); }

17.10.2 Enumerations [support.contract.enum]

Recommended practice: For all enumerations in [support.contract.enum], if implementation-defined enumerators are provided, they should have a minimum value of 1000.

The enumerators of assertion_kind correspond to the syntactic forms of a contract assertion ([basic.contract.general]), with meanings listed in Table 44 .

Table 44 — Enum assertion_kind [tab:support.contract.enum.kind]

🔗 Name	Meaning
🔗 pre	A precondition assertion
🔗 post	A postcondition assertion
🔗 assert	An assertion-statement
🔗

The enumerators of evaluation_semantic correspond to the evaluation semantics with which a contract assertion may be evaluated ([basic.contract.eval]), with meanings listed in Table 45 .

Table 45 — Enum evaluation_semantic [tab:support.contract.enum.semantic]

🔗 Name	Meaning
🔗 ignore	Ignore evaluation semantic
🔗 observe	Observe evaluation semantic
🔗 enforce	Enforce evaluation semantic
🔗 quick_enforce	Quick-enforce evaluation semantic
🔗

The enumerators of detection_mode correspond to the manners in which a contract violation can be identified ([basic.contract.eval]), with meanings listed in Table 46.

Table 46 — Enum detection_mode [tab:support.contract.enum.detection]

🔗 Name	Meaning
🔗 predicate_false	The predicate of the contract assertion evaluated to false or would have evaluated to false.
🔗 evaluation_exception	An uncaught exception occurred during evaluation of the contract assertion.
🔗

17.10.3 Class contract_violation [support.contract.violation]

The class contract_violation defines the type of objects used to represent a contract violation that has been detected during the evaluation of a contract assertion with a particular evaluation semantic ([basic.contract.eval]).

Objects of this type can be created only by the implementation.

It is implementation-defined whether the destructor is virtual.

🔗

const char* comment() const noexcept;

Returns: An implementation-defined ntmbs in the ordinary literal encoding ([lex.charset]).

Recommended practice: The string returned should contain a textual representation of the predicate of the violated contract assertion or an empty string if storing a textual representation is undesired.

[Note 1:

The string can represent a truncated, reformatted, or summarized rendering of the predicate, before or after preprocessing.

— end note]

🔗

contracts::detection_mode detection_mode() const noexcept;

Returns: The enumerator value corresponding to the manner in which the contract violation was identified.

🔗

exception_ptr evaluation_exception() const noexcept;

Returns: If the contract violation occurred because the evaluation of the predicate exited via an exception, an exception_ptr object that refers to that exception or a copy of that exception; otherwise, a null exception_ptr object.

🔗

bool is_terminating() const noexcept;

Returns: true if the evaluation semantic is a terminating semantic ([basic.contract.eval]); otherwise, false.

🔗

assertion_kind kind() const noexcept;

Returns: The enumerator value corresponding to the syntactic form of the violated contract assertion.

🔗

source_location location() const noexcept;

Returns: A source_location object with implementation-defined value.

Recommended practice: The value returned should be a default constructed source_location object or a value identifying the violated contract assertion:

(9.1)
When possible, if the violated contract assertion was a precondition, the source location of the function invocation should be returned.
(9.2)
Otherwise, the source location of the contract assertion should be returned.

🔗

evaluation_semantic semantic() const noexcept;

Returns: The enumerator value corresponding to the evaluation semantic with which the violated contract assertion was evaluated.

17.10.4 Invoke default handler [support.contract.invoke]

🔗

void invoke_default_contract_violation_handler(const contract_violation& v);

Effects: Invokes the default contract-violation handler ([basic.contract.handler]) with the argument v.