depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cppdraft_translate/cppdraft/structure.md
Leonov Artur (Depish) 043225d523 Init
2025-10-25 03:02:53 +03:00

478 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

[structure]
# 16 Library introduction [[library]](./#library)
## 16.3 Method of description [[description]](description#structure)
### 16.3.2 Structure of each clause [structure]
#### [16.3.2.1](#elements) Elements [[structure.elements]](structure.elements)
[1](#elements-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L191)
Each library clause contains the following elements, as applicable:[132](#footnote-132 "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.")
- [(1.1)](#elements-1.1)
Summary
- [(1.2)](#elements-1.2)
Requirements
- [(1.3)](#elements-1.3)
Detailed specifications
- [(1.4)](#elements-1.4)
References to the C standard library
[132)](#footnote-132)[132)](#footnoteref-132)
To
save space, items that do not apply to a Clause are omitted[.](#footnote-132.sentence-1)
For example, if a Clause does not specify any requirements,
there will be no “Requirements” subclause[.](#footnote-132.sentence-2)
#### [16.3.2.2](#summary) Summary [[structure.summary]](structure.summary)
[1](#summary-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L208)
The Summary provides a synopsis of the category, and introduces the first-level subclauses[.](#summary-1.sentence-1)
Each subclause also provides a summary, listing the headers specified in the
subclause and the library entities provided in each header[.](#summary-1.sentence-2)
[2](#summary-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L213)
The contents of the summary and the detailed specifications include:
- [(2.1)](#summary-2.1)
macros
- [(2.2)](#summary-2.2)
values
- [(2.3)](#summary-2.3)
types and alias templates
- [(2.4)](#summary-2.4)
classes and class templates
- [(2.5)](#summary-2.5)
functions and function templates
- [(2.6)](#summary-2.6)
objects and variable templates
- [(2.7)](#summary-2.7)
concepts
#### [16.3.2.3](#requirements) Requirements [[structure.requirements]](structure.requirements)
[1](#requirements-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L227)
Requirements describe constraints that shall be met by a C++ program that extends the standard library[.](#requirements-1.sentence-1)
Such extensions are generally one of the following:
- [(1.1)](#requirements-1.1)
Template arguments
- [(1.2)](#requirements-1.2)
Derived classes
- [(1.3)](#requirements-1.3)
Containers, iterators, and algorithms that meet an interface convention or
model a concept
[2](#requirements-2)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L238)
The string and iostream components use an explicit representation of operations
required of template arguments[.](#requirements-2.sentence-1)
They use a class template char_traits to
define these constraints[.](#requirements-2.sentence-2)
[3](#requirements-3)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L243)
Interface convention requirements are stated as generally as possible[.](#requirements-3.sentence-1)
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”[.](#requirements-3.sentence-2)
That is, whether the operator is a member is unspecified[.](#requirements-3.sentence-3)
[4](#requirements-4)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L249)
Requirements are stated in terms of well-defined expressions that define valid terms of
the types that meet the requirements[.](#requirements-4.sentence-1)
For every set of well-defined expression
requirements there is either a named concept or a table that specifies an initial set of the valid expressions and
their semantics[.](#requirements-4.sentence-2)
Any generic algorithm ([[algorithms]](algorithms "26 Algorithms library")) that uses the
well-defined expression requirements is described in terms of the valid expressions for
its template type parameters[.](#requirements-4.sentence-3)
[5](#requirements-5)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L257)
The library specification uses a typographical convention for naming
requirements[.](#requirements-5.sentence-1)
Names in *italic* type that begin with the prefix*Cpp17* refer to sets of well-defined expression requirements typically
presented in tabular form, possibly with additional prose semantic requirements[.](#requirements-5.sentence-2)
For example, *Cpp17Destructible* (Table [35](utility.arg.requirements#tab:cpp17.destructible "Table 35: Cpp17Destructible requirements")) is such a named
requirement[.](#requirements-5.sentence-3)
Names in constant width type refer to library concepts
which are presented as a concept definition ([[temp]](temp "13 Templates")), possibly with additional
prose semantic requirements[.](#requirements-5.sentence-4)
For example,[destructible](concept.destructible#concept:destructible "18.4.10 Concept destructible [concept.destructible]") ([[concept.destructible]](concept.destructible "18.4.10 Concept destructible"))
is such a named requirement[.](#requirements-5.sentence-5)
[6](#requirements-6)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L269)
Template argument requirements are sometimes referenced by name[.](#requirements-6.sentence-1)
See [[type.descriptions]](type.descriptions "16.3.3.3 Type descriptions")[.](#requirements-6.sentence-2)
[7](#requirements-7)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L273)
In some cases the semantic requirements are presented as C++ code[.](#requirements-7.sentence-1)
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[.](#requirements-7.sentence-2)[133](#footnote-133 "Although in some cases the code given is unambiguously the optimum implementation.")
[8](#requirements-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L284)
Required operations of any concept defined in this document need not be
total functions; that is, some arguments to a required operation may
result in the required semantics failing to be met[.](#requirements-8.sentence-1)
[*Example [1](#requirements-example-1)*:
The required < operator of the [totally_ordered](concept.totallyordered#concept:totally_ordered "18.5.5 Concept totally_­ordered [concept.totallyordered]") concept ([[concept.totallyordered]](concept.totallyordered "18.5.5 Concept totally_­ordered")) does not meet the
semantic requirements of that concept when operating on NaNs[.](#requirements-8.sentence-2)
— *end example*]
This does not affect whether a type models the concept[.](#requirements-8.sentence-3)
[9](#requirements-9)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L295)
A declaration may explicitly impose requirements through its associated
constraints ([[temp.constr.decl]](temp.constr.decl "13.5.3 Constrained declarations"))[.](#requirements-9.sentence-1)
When the associated constraints refer to a
concept ([[temp.concept]](temp.concept "13.7.9 Concept definitions")), the semantic constraints specified for that concept
are additionally imposed on the use of the declaration[.](#requirements-9.sentence-2)
[133)](#footnote-133)[133)](#footnoteref-133)
Although in some cases the code given is
unambiguously the optimum implementation[.](#footnote-133.sentence-1)
#### [16.3.2.4](#specifications) Detailed specifications [[structure.specifications]](structure.specifications)
[1](#specifications-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L303)
The detailed specifications each contain the following elements:
- [(1.1)](#specifications-1.1)
name and brief description
- [(1.2)](#specifications-1.2)
synopsis (class definition or function declaration, as appropriate)
- [(1.3)](#specifications-1.3)
restrictions on template arguments, if any
- [(1.4)](#specifications-1.4)
description of class invariants
- [(1.5)](#specifications-1.5)
description of function semantics
[2](#specifications-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)](#specifications-2.1)
constructor(s) and destructor
- [(2.2)](#specifications-2.2)
copying, moving & assignment functions
- [(2.3)](#specifications-2.3)
comparison operator functions
- [(2.4)](#specifications-2.4)
modifier functions
- [(2.5)](#specifications-2.5)
observer functions
- [(2.6)](#specifications-2.6)
operators and other non-member functions
[3](#specifications-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)](#specifications-3.1)
*Constraints*: the conditions for the function's participation
in overload resolution ([[over.match]](over.match "12.2 Overload resolution"))[.](#specifications-3.1.sentence-1)
[*Note [1](#specifications-note-1)*:
Failure to meet such a condition results in the function's silent non-viability[.](#specifications-3.1.sentence-2)
— *end note*]
[*Example [1](#specifications-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"))[.](#specifications-3.1.sentence-3)
— *end example*]
- [(3.2)](#specifications-3.2)
*Mandates*: the conditions that, if not met, render the program ill-formed[.](#specifications-3.2.sentence-1)
[*Example [2](#specifications-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"))[.](#specifications-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[.](#specifications-3.2.sentence-3)
— *end example*]
- [(3.3)](#specifications-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"))[.](#specifications-3.3.sentence-1)
- [(3.4)](#specifications-3.4)
*Preconditions*: conditions that the function assumes to hold whenever it is called;
violation of any preconditions results in undefined behavior[.](#specifications-3.4.sentence-1)
[*Example [3](#specifications-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"))[.](#specifications-3.4.sentence-2)
— *end example*]
- [(3.5)](#specifications-3.5)
*Hardened preconditions*: conditions that the function assumes to hold whenever it is called[.](#specifications-3.5.sentence-1)
* [(3.5.1)](#specifications-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"))[.](#specifications-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[.](#specifications-3.5.1.sentence-2)
* [(3.5.2)](#specifications-3.5.2)
When invoking the function in a non-hardened implementation,
if any hardened precondition is violated,
the program has undefined behavior[.](#specifications-3.5.2.sentence-1)
- [(3.6)](#specifications-3.6)
*Effects*: the actions performed by the function[.](#specifications-3.6.sentence-1)
- [(3.7)](#specifications-3.7)
*Synchronization*: the synchronization operations ([[intro.multithread]](intro.multithread "6.10.2 Multi-threaded executions and data races")) applicable to the function[.](#specifications-3.7.sentence-1)
- [(3.8)](#specifications-3.8)
*Postconditions*: the conditions (sometimes termed observable results)
established by the function[.](#specifications-3.8.sentence-1)
[*Example [4](#specifications-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"))[.](#specifications-3.8.sentence-2)
— *end example*]
- [(3.9)](#specifications-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[.](#specifications-3.9.sentence-1)
- [(3.10)](#specifications-3.10)
*Returns*: a description of the value(s) returned by the function[.](#specifications-3.10.sentence-1)
- [(3.11)](#specifications-3.11)
*Throws*: any exceptions thrown by the function, and the conditions that would cause the exception[.](#specifications-3.11.sentence-1)
- [(3.12)](#specifications-3.12)
*Complexity*: the time and/or space complexity of the function[.](#specifications-3.12.sentence-1)
- [(3.13)](#specifications-3.13)
*Remarks*: additional semantic constraints on the function[.](#specifications-3.13.sentence-1)
- [(3.14)](#specifications-3.14)
*Error conditions*: the error conditions for error codes reported by the function[.](#specifications-3.14.sentence-1)
[4](#specifications-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[.](#specifications-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[.](#specifications-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[.](#specifications-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[.](#specifications-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[.](#specifications-4.sentence-5)
[5](#specifications-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[.](#specifications-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[.](#specifications-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[.](#specifications-5.sentence-3)
Where no distinction is explicitly made in the description, the
behavior described is the required behavior[.](#specifications-5.sentence-4)
[6](#specifications-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[.](#specifications-6.sentence-1)[136](#footnote-136 "This simplifies the presentation of complexity requirements in some cases.")
[7](#specifications-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[.](#specifications-7.sentence-1)
[8](#specifications-8)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L501)
Error conditions specify conditions where a function may fail[.](#specifications-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"))[.](#specifications-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)
#### [16.3.2.5](#see.also) C library [[structure.see.also]](structure.see.also)
[1](#see.also-1)
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lib-intro.tex#L508)
Paragraphs labeled “See also” contain cross-references to the relevant portions
of other standards ([[intro.refs]](intro.refs "2 Normative references"))[.](#see.also-1.sentence-1)
Reference in New Issue View Git Blame Copy Permalink