[structure.specifications] # 16 Library introduction [[library]](./#library) ## 16.3 Method of description [[description]](description#structure.specifications) ### 16.3.2 Structure of each clause [[structure]](structure#specifications) #### 16.3.2.4 Detailed specifications [structure.specifications] [1](#1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L303) The detailed specifications each contain the following elements: - [(1.1)](#1.1) name and brief description - [(1.2)](#1.2) synopsis (class definition or function declaration, as appropriate) - [(1.3)](#1.3) restrictions on template arguments, if any - [(1.4)](#1.4) description of class invariants - [(1.5)](#1.5) description of function semantics [2](#2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L313) Descriptions of class member functions follow the order (as appropriate):[134](#footnote-134 "To save space, items that do not apply to a class are omitted. For example, if a class does not specify any comparison operator functions, there will be no “Comparison operator functions” subclause.") - [(2.1)](#2.1) constructor(s) and destructor - [(2.2)](#2.2) copying, moving & assignment functions - [(2.3)](#2.3) comparison operator functions - [(2.4)](#2.4) modifier functions - [(2.5)](#2.5) observer functions - [(2.6)](#2.6) operators and other non-member functions [3](#3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L330) Descriptions of function semantics contain the following elements (as appropriate):[135](#footnote-135 "To save space, elements that do not apply to a function are omitted. For example, if a function specifies no preconditions, there will be no Preconditions: element.") - [(3.1)](#3.1) *Constraints*: the conditions for the function's participation in overload resolution ([[over.match]](over.match "12.2 Overload resolution"))[.](#3.1.sentence-1) [*Note [1](#note-1)*: Failure to meet such a condition results in the function's silent non-viability[.](#3.1.sentence-2) — *end note*] [*Example [1](#example-1)*: An implementation can express such a condition via a [*constraint-expression*](temp.constr.decl#nt:constraint-expression "13.5.3 Constrained declarations [temp.constr.decl]") ([[temp.constr.decl]](temp.constr.decl "13.5.3 Constrained declarations"))[.](#3.1.sentence-3) — *end example*] - [(3.2)](#3.2) *Mandates*: the conditions that, if not met, render the program ill-formed[.](#3.2.sentence-1) [*Example [2](#example-2)*: An implementation can express such a condition via the [*constant-expression*](expr.const#nt:constant-expression "7.7 Constant expressions [expr.const]") in a [*static_assert-declaration*](dcl.pre#nt:static_assert-declaration "9.1 Preamble [dcl.pre]") ([[dcl.pre]](dcl.pre "9.1 Preamble"))[.](#3.2.sentence-2) If the diagnostic is to be emitted only after the function has been selected by overload resolution, an implementation can express such a condition via a [*constraint-expression*](temp.constr.decl#nt:constraint-expression "13.5.3 Constrained declarations [temp.constr.decl]") ([[temp.constr.decl]](temp.constr.decl "13.5.3 Constrained declarations")) and also define the function as deleted[.](#3.2.sentence-3) — *end example*] - [(3.3)](#3.3) *Constant When*: the conditions that are required for a call to the function to be a constant subexpression ([[defns.const.subexpr]](defns.const.subexpr "3.15 constant subexpression"))[.](#3.3.sentence-1) - [(3.4)](#3.4) *Preconditions*: conditions that the function assumes to hold whenever it is called; violation of any preconditions results in undefined behavior[.](#3.4.sentence-1) [*Example [3](#example-3)*: An implementation can express some such conditions via the use of a contract assertion, such as a precondition assertion ([[dcl.contract.func]](dcl.contract.func "9.4.1 General"))[.](#3.4.sentence-2) — *end example*] - [(3.5)](#3.5) *Hardened preconditions*: conditions that the function assumes to hold whenever it is called[.](#3.5.sentence-1) * [(3.5.1)](#3.5.1) When invoking the function in a hardened implementation, prior to any other observable side effects of the function, one or more contract assertions whose predicates are as described in the hardened precondition are evaluated with a checking semantic ([[basic.contract.eval]](basic.contract.eval "6.11.2 Evaluation"))[.](#3.5.1.sentence-1) If any of these assertions is evaluated with a non-terminating semantic and the contract-violation handler returns, the program has undefined behavior[.](#3.5.1.sentence-2) * [(3.5.2)](#3.5.2) When invoking the function in a non-hardened implementation, if any hardened precondition is violated, the program has undefined behavior[.](#3.5.2.sentence-1) - [(3.6)](#3.6) *Effects*: the actions performed by the function[.](#3.6.sentence-1) - [(3.7)](#3.7) *Synchronization*: the synchronization operations ([[intro.multithread]](intro.multithread "6.10.2 Multi-threaded executions and data races")) applicable to the function[.](#3.7.sentence-1) - [(3.8)](#3.8) *Postconditions*: the conditions (sometimes termed observable results) established by the function[.](#3.8.sentence-1) [*Example [4](#example-4)*: An implementation can express some such conditions via the use of a contract assertion, such as a postcondition assertion ([[dcl.contract.func]](dcl.contract.func "9.4.1 General"))[.](#3.8.sentence-2) — *end example*] - [(3.9)](#3.9) *Result*: for a [*typename-specifier*](temp.res.general#nt:typename-specifier "13.8.1 General [temp.res.general]"), a description of the named type; for an [*expression*](expr.comma#nt:expression "7.6.20 Comma operator [expr.comma]"), a description of the type and value category of the expression; the expression is an lvalue if the type is an lvalue reference type, an xvalue if the type is an rvalue reference type, and a prvalue otherwise[.](#3.9.sentence-1) - [(3.10)](#3.10) *Returns*: a description of the value(s) returned by the function[.](#3.10.sentence-1) - [(3.11)](#3.11) *Throws*: any exceptions thrown by the function, and the conditions that would cause the exception[.](#3.11.sentence-1) - [(3.12)](#3.12) *Complexity*: the time and/or space complexity of the function[.](#3.12.sentence-1) - [(3.13)](#3.13) *Remarks*: additional semantic constraints on the function[.](#3.13.sentence-1) - [(3.14)](#3.14) *Error conditions*: the error conditions for error codes reported by the function[.](#3.14.sentence-1) [4](#4) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L447) Whenever the *Effects* element specifies that the semantics of some functionF are [*Equivalent to*](#def:Equivalent_to) some code sequence, then the various elements are interpreted as follows[.](#4.sentence-1) If F's semantics specifies any *Constraints* or *Mandates* elements, then those requirements are logically imposed prior to the [*equivalent-to*](#def:equivalent-to) semantics[.](#4.sentence-2) Next, the semantics of the code sequence are determined by the*Constraints*,*Mandates*,*Constant When*,*Preconditions*,*Hardened preconditions*,*Effects*,*Synchronization*,*Postconditions*,*Returns*,*Throws*,*Complexity*,*Remarks*, and*Error conditions* specified for the function invocations contained in the code sequence[.](#4.sentence-3) The value returned from F is specified by F's *Returns* element, or if F has no *Returns* element, a non-void return from F is specified by thereturn statements ([[stmt.return]](stmt.return "8.8.4 The return statement")) in the code sequence[.](#4.sentence-4) If F's semantics contains a *Throws*,*Postconditions*, or *Complexity* element, then that supersedes any occurrences of that element in the code sequence[.](#4.sentence-5) [5](#5) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L476) For non-reserved replacement and handler functions,[[support]](support "17 Language support library") specifies two behaviors for the functions in question: their required and default behavior[.](#5.sentence-1) The [*default behavior*](#def:behavior,default "16.3.2.4 Detailed specifications [structure.specifications]") describes a function definition provided by the implementation[.](#5.sentence-2) The [*required behavior*](#def:behavior,required "16.3.2.4 Detailed specifications [structure.specifications]") describes the semantics of a function definition provided by either the implementation or a C++ program[.](#5.sentence-3) Where no distinction is explicitly made in the description, the behavior described is the required behavior[.](#5.sentence-4) [6](#6) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L488) If the formulation of a complexity requirement calls for a negative number of operations, the actual requirement is zero operations[.](#6.sentence-1)[136](#footnote-136 "This simplifies the presentation of complexity requirements in some cases.") [7](#7) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L496) Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees meet the requirements[.](#7.sentence-1) [8](#8) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L501) Error conditions specify conditions where a function may fail[.](#8.sentence-1) The conditions are listed, together with a suitable explanation, as the enum class errc constants ([[syserr]](syserr "19.5 System error support"))[.](#8.sentence-2) [134)](#footnote-134)[134)](#footnoteref-134) To save space, items that do not apply to a class are omitted[.](#footnote-134.sentence-1) For example, if a class does not specify any comparison operator functions, there will be no “Comparison operator functions” subclause[.](#footnote-134.sentence-2) [135)](#footnote-135)[135)](#footnoteref-135) To save space, elements that do not apply to a function are omitted[.](#footnote-135.sentence-1) For example, if a function specifies no preconditions, there will be no *Preconditions*: element[.](#footnote-135.sentence-2) [136)](#footnote-136)[136)](#footnoteref-136) This simplifies the presentation of complexity requirements in some cases[.](#footnote-136.sentence-1)