20 Library introduction [library]

20.4 Method of description (Informative) [description]

20.4.1 Structure of each clause [structure]

20.4.1.4 Detailed specifications [structure.specifications]

1
#
The detailed specifications each contain the following elements:
  • (1.1)
    name and brief description
  • (1.2)
    synopsis (class definition or function declaration, as appropriate)
  • (1.3)
    restrictions on template arguments, if any
  • (1.4)
    description of class invariants
  • (1.5)
    description of function semantics
2
#
Descriptions of class member functions follow the order (as appropriate):157
  • (2.1)
    constructor(s) and destructor
  • (2.2)
    copying, moving & assignment functions
  • (2.3)
    comparison functions
  • (2.4)
    modifier functions
  • (2.5)
    observer functions
  • (2.6)
    operators and other non-member functions
3
#
Descriptions of function semantics contain the following elements (as appropriate):158
  • (3.1)
    Requires: the preconditions for calling the function
  • (3.2)
    Effects: the actions performed by the function
  • (3.3)
    Synchronization: the synchronization operations ([intro.multithread]) applicable to the function
  • (3.4)
    Postconditions: the observable results established by the function
  • (3.5)
    Returns: a description of the value(s) returned by the function
  • (3.6)
    Throws: any exceptions thrown by the function, and the conditions that would cause the exception
  • (3.7)
    Complexity: the time and/or space complexity of the function
  • (3.8)
    Remarks: additional semantic constraints on the function
  • (3.9)
    Error conditions: the error conditions for error codes reported by the function
4
#
Whenever the Effects: element specifies that the semantics of some function F are Equivalent to some code sequence, then the various elements are interpreted as follows.
If F's semantics specifies a Requires: element, then that requirement is logically imposed prior to the equivalent-to semantics.
Next, the semantics of the code sequence are determined by the Requires:, Effects:, Synchronization:, Postconditions:, Returns:, Throws:, Complexity:, Remarks:, and Error conditions: specified for the function invocations contained in the code sequence.
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 the return statements in the code sequence.
If F's semantics contains a Throws:, Postconditions:, or Complexity: element, then that supersedes any occurrences of that element in the code sequence.
5
#
For non-reserved replacement and handler functions, Clause [language.support] specifies two behaviors for the functions in question: their required and default behavior.
The default behavior describes a function definition provided by the implementation.
The required behavior describes the semantics of a function definition provided by either the implementation or a C++ program.
Where no distinction is explicitly made in the description, the behavior described is the required behavior.
6
#
If the formulation of a complexity requirement calls for a negative number of operations, the actual requirement is zero operations.159
7
#
Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees satisfy the requirements.
8
#
Error conditions specify conditions where a function may fail.
The conditions are listed, together with a suitable explanation, as the enum class errc constants ([syserr]).
157)
To save space, items that do not apply to a class are omitted.
For example, if a class does not specify any comparison functions, there will be no “Comparison functions” subclause.
158)
To save space, items that do not apply to a function are omitted.
For example, if a function does not specify any further preconditions, there will be no Requires: paragraph.
159)
This simplifies the presentation of complexity requirements in some cases.