Each library clause contains the following elements, as applicable:161
Summary
Requirements
Detailed specifications
References to the Standard C library
To save space, items that do not apply to a Clause are omitted. For example, if a Clause does not specify any requirements, there will be no “Requirements” subclause.
The Summary provides a synopsis of the category, and introduces the first-level subclauses. Each subclause also provides a summary, listing the headers specified in the subclause and the library entities provided in each header.
Paragraphs labeled “Note(s):” or “Example(s):” are informative, other paragraphs are normative.
Requirements describe constraints that shall be met by a C++ program that extends the standard library. Such extensions are generally one of the following:
Template arguments
Derived classes
Containers, iterators, and algorithms that meet an interface convention
The string and iostream components use an explicit representation of operations required of template arguments. They use a class template char_traits to define these constraints.
Interface convention requirements are stated as generally as possible. Instead of stating “class X has to define a member function operator++(),” the interface requires “for any object x of class X, ++x is defined.” That is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions that define valid terms of the types that satisfy the requirements. For every set of well-defined expression requirements there is a table that specifies an initial set of the valid expressions and their semantics. Any generic algorithm (Clause [algorithms]) that uses the well-defined expression requirements is described in terms of the valid expressions for its formal type parameters.
Template argument requirements are sometimes referenced by name. See [type.descriptions].
In some cases the semantic requirements are presented as C++ code. Such code is intended as a specification of equivalence of a construct to another construct, not necessarily as the way the construct must be implemented.162
Although in some cases the code given is unambiguously the optimum implementation.
The detailed specifications each contain the following elements:
name and brief description
synopsis (class definition or function prototype, as appropriate)
restrictions on template arguments, if any
description of class invariants
description of function semantics
Descriptions of class member functions follow the order (as appropriate):163
constructor(s) and destructor
copying, moving & assignment functions
comparison functions
modifier functions
observer functions
operators and other non-member functions
Descriptions of function semantics contain the following elements (as appropriate):164
Requires: the preconditions for calling the function
Effects: the actions performed by the function
Synchronization: the synchronization operations ([intro.multithread]) applicable to the function
Postconditions: the observable results established by the function
Returns: a description of the value(s) returned by the function
Throws: any exceptions thrown by the function, and the conditions that would cause the exception
Complexity: the time and/or space complexity of the function
Remarks: additional semantic constraints on the function
Error conditions: the error conditions for error codes reported by the function.
Notes: non-normative comments about the function
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:, Postconditions:, Returns:, Throws:, Complexity:, Remarks:, Error conditions:, and Notes: 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 Returns: elements 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.
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.
If the formulation of a complexity requirement calls for a negative number of operations, the actual requirement is zero operations.165
Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees satisfy the requirements.
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]).
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.
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.
This simplifies the presentation of complexity requirements in some cases.
Paragraphs labeled “See also:” contain cross-references to the relevant portions of this International Standard and the ISO C standard, which is incorporated into this International Standard by reference.