depish/cppdraft_translate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Init

Browse Source
This commit is contained in:
Leonov Artur (Depish)
2025-10-25 03:02:53 +03:00
commit 043225d523
3416 changed files with 681196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

477
cppdraft/structure.md Normal file
View File

@@ -0,0 +1,477 @@
[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)