[description] (original) (raw)
16.3.1 General [description.general]
Subclause [description] describes the conventions used to specify the C++ standard library.
[conventions] describes other editorial conventions.
16.3.2 Structure of each clause [structure]
16.3.2.1 Elements [structure.elements]
Each library clause contains the following elements, as applicable:132
- Summary
- Requirements
- Detailed specifications
- References to the C standard library
16.3.2.2 Summary [structure.summary]
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.
The contents of the summary and the detailed specifications include:
- macros
- values
- types and alias templates
- classes and class templates
- functions and function templates
- objects and variable templates
- concepts
16.3.2.3 Requirements [structure.requirements]
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 or model a concept
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 meet the requirements.
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.
Any generic algorithm ([algorithms]) that uses the well-defined expression requirements is described in terms of the valid expressions for its template type parameters.
The library specification uses a typographical convention for naming requirements.
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.
For example, Cpp17Destructible (Table 35) is such a named requirement.
Names in constant width type refer to library concepts which are presented as a concept definition ([temp]), possibly with additional prose semantic requirements.
Template argument requirements are sometimes referenced by name.
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.133
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.
This does not affect whether a type models the concept.
A declaration may explicitly impose requirements through its associated constraints ([temp.constr.decl]).
When the associated constraints refer to a concept ([temp.concept]), the semantic constraints specified for that concept are additionally imposed on the use of the declaration.
16.3.2.4 Detailed specifications [structure.specifications]
The detailed specifications each contain the following elements:
- name and brief description
- synopsis (class definition or function declaration, 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):134
- constructor(s) and destructor
- copying, moving & assignment functions
- comparison operator functions
- modifier functions
- observer functions
- operators and other non-member functions
Descriptions of function semantics contain the following elements (as appropriate):135
- Constraints: the conditions for the function's participation in overload resolution ([over.match]).
[Note 1:
Failure to meet such a condition results in the function's silent non-viability.
— end note_]
[_Example 1:
— _end example_] - Mandates: the conditions that, if not met, render the program ill-formed.
[Example 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]) and also define the function as deleted.
— _end example_] - Preconditions: conditions that the function assumes to hold whenever it is called; violation of any preconditions results in undefined behavior.
[Example 3:
An implementation can express some such conditions via the use of a contract assertion, such as a precondition assertion ([dcl.contract.func]).
— _end example_] - Hardened preconditions: conditions that the function assumes to hold whenever it is called.
- 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]).
If any of these assertions is evaluated with a non-terminating semantic and the contract-violation handler returns, the program has undefined behavior. - When invoking the function in a non-hardened implementation, if any hardened precondition is violated, the program has undefined behavior.
- 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]).
- Effects: the actions performed by the function.
- Synchronization: the synchronization operations ([intro.multithread]) applicable to the function.
- Postconditions: the conditions (sometimes termed observable results) established by the function.
[Example 4:
An implementation can express some such conditions via the use of a contract assertion, such as a postcondition assertion ([dcl.contract.func]).
— _end example_] - Result: for a typename-specifier, a description of the named type; for an expression, 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.
- 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.
Whenever the Effects element specifies that the semantics of some functionF are Equivalent to some code sequence, then the various elements are interpreted as follows.
If F's semantics specifies any Constraints or Mandates elements, then those requirements are logically imposed prior to the equivalent-to semantics.
Next, the semantics of the code sequence are determined by the_Constraints_,Mandates,Preconditions,Hardened preconditions,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 thereturn statements ([stmt.return]) 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,[support] specifies two behaviors for the functions in question: their required and default behavior.
The default behaviordescribes a function definition provided by the implementation.
The required behaviordescribes 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.136
Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees meet the requirements.
Error conditions specify conditions where a function may fail.
The conditions are listed, together with a suitable explanation, as the enum class errcconstants ([syserr]).
16.3.3 Other conventions [conventions]
16.3.3.1 General [conventions.general]
Subclause [conventions] describes several editorial conventions used to describe the contents of the C++ standard library.
These conventions are for describingimplementation-defined types, and member functions.
16.3.3.2 Exposition-only entities, etc. [expos.only.entity]
The declaration of such an entity or typedef-nameis followed by a comment ending in exposition only.
The following are defined for exposition only to aid in the specification of the library:namespace std { template<class T> requires convertible_to<T, decay_t<T>> constexpr decay_t<T> decay-copy(T&& v) noexcept(is_nothrow_convertible_v<T, decay_t<T>>) { return std::forward<T>(v); } constexpr auto synth-three-way = []<class T, class U>(const T& t, const U& u) requires requires { { t < u } -> boolean-testable;{ u < t } -> boolean-testable;} { if constexpr (three_way_comparable_with<T, U>) { return t <=> u;} else { if (t < u) return weak_ordering::less;if (u < t) return weak_ordering::greater;return weak_ordering::equivalent;} };template<class T, class U=T> using synth-three-way-result = decltype(synth-three-way(declval<T&>(), declval<U&>()));}
An object dst is said to be decay-copied froma subexpression srcif the type of dst isdecay_t<decltype((src))>
16.3.3.3 Type descriptions [type.descriptions]
16.3.3.3.1 General [type.descriptions.general]
The Requirements subclauses may describe names that are used to specify constraints on template arguments.137
These names are used in library Clauses to describe the types that may be supplied as arguments by a C++ program when instantiating template components from the library.
Certain types defined in [input.output] are used to describe implementation-defined types.
They are based on other types, but with added constraints.
16.3.3.3.2 Enumerated types [enumerated.types]
Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration.138
The enumerated type enumerated can be written:enum enumerated { , , , , … };inline const ();inline const ();inline const ();inline const (); ⋮
Here, the names ,, etc. representenumerated elementsfor this particular enumerated type.
All such elements have distinct values.
16.3.3.3.3 Bitmask types [bitmask.types]
Each bitmask type can be implemented as an enumerated type that overloads certain operators, as an integer type, or as abitset.
The bitmask type bitmask can be written: enum bitmask : int_type { = 1 << 0, = 1 << 1, = 1 << 2, = 1 << 3, … };inline constexpr ();inline constexpr ();inline constexpr ();inline constexpr (); ⋮constexpr _bitmask_ operator&(_bitmask_ X, _bitmask_ Y) { return static_cast<_bitmask_>( static_cast<int_type>(X) & static_cast<int_type>(Y));} constexpr bitmask operator|(bitmask X, bitmask Y) { return static_cast<_bitmask_>( static_cast<int_type>(X) | static_cast<int_type>(Y));} constexpr bitmask operator^(bitmask X, bitmask Y) { return static_cast<_bitmask_>( static_cast<int_type>(X) ^ static_cast<int_type>(Y));} constexpr bitmask operator~(bitmask X) { return static_cast<_bitmask_>(~static_cast<int_type>(X));} bitmask& operator&=(bitmask& X, bitmask Y) { X = X & Y; return X;} bitmask& operator|=(bitmask& X, bitmask Y) { X = X | Y; return X;} bitmask& operator^=(bitmask& X, bitmask Y) { X = X ^ Y; return X;}
Here, the names ,, etc. representbitmask elementsfor this particular bitmask type.
All such elements have distinct, nonzero values such that, for any pair and where i ≠ j, & is nonzero and & is zero.
Additionally, the value 0 is used to represent an empty bitmask, in which no bitmask elements are set.
The following terms apply to objects and values of bitmask types:
- To seta value Y in an object _X_is to evaluate the expression X |= Y.
- To cleara value Y in an object_X_ is to evaluate the expression X &= ~Y.
- The value Y is set in the object_X_ if the expression X & Y is nonzero.
16.3.3.3.4 Character sequences [character.seq]
16.3.3.3.4.1 General [character.seq.general]
The C standard library makes widespread useof characters and character sequences that follow a few uniform conventions:
- Properties specified as locale-specificmay change during program execution by a call to setlocale(int, const char*) ([clocale.syn]), or by a change to a locale object, as described in [locales] and [input.output].
- The execution character set and the execution wide-character setare supersets of the basic literal character set ([lex.charset]).
The encodings of the execution character sets and the sets of additional elements (if any) are locale-specific.
Each element of the execution wide-character set is encoded as a single code unit representable by a value of type wchar_t.
[Note 1:
The encodings of the execution character sets can be unrelated to any literal encoding.
— _end note_] - A letter is any of the 26 lowercase or 26uppercase letters in the basic character set.
- Thedecimal-point characteris the locale-specific (single-byte) character used by functions that convert between a (single-byte) character sequence and a value of one of the floating-point types.
It is used in the character sequence to denote the beginning of a fractional part.
It is represented in [support] through [exec]and [depr] by a period,'.', which is also its value in the "C"locale. - Acharacter sequenceis an array object A that can be declared as_T A_[N_], where T is any of the typeschar,unsigned char, orsigned char ([basic.fundamental]), optionally qualified by any combination ofconstorvolatile.
The initial elements of the array have defined contents up to and including an element determined by some predicate.
A character sequence can be designated by a pointer value_S that points to its first element.
16.3.3.3.4.2 Byte strings [byte.strings]
A null-terminated byte string, or ntbs, is a character sequence whose highest-addressed element with defined content has the value zero (the terminating null character); no other element in the sequence has the value zero.139
The length of an ntbsis the number of elements that precede the terminating null character.
An empty ntbshas a length of zero.
The value of an ntbsis the sequence of values of the elements up to and including the terminating null character.
A static ntbsis an ntbs with static storage duration.[140](#footnote-140 "A string-literal, such as "abc", is a static ntbs.")
16.3.3.3.4.3 Multibyte strings [multibyte.strings]
A multibyte character is a sequence of one or more bytes representing the code unit sequence for an encoded character of the execution character set.
A null-terminated multibyte string, or ntmbs, is an ntbs that constitutes a sequence of valid multibyte characters, beginning and ending in the initial shift state.141
A static ntmbsis an ntmbs with static storage duration.
16.3.3.3.5 Customization Point Object types [customization.point.object]
A customization point object is a function object ([function.objects]) with a literal class type that interacts with program-defined types while enforcing semantic requirements on that interaction.
All instances of a specific customization point object type shall be equal ([concepts.equality]).
The effects of invoking different instances of a specific customization point object type on the same arguments are equivalent.
The type T of a customization point object, ignoring cv-qualifiers, shall modelinvocable<T&, Args...>,invocable<const T&, Args...>,invocable<T, Args...>, andinvocable<const T, Args...> ([concept.invocable]) when the types in Args... meet the requirements specified in that customization point object's definition.
When the types of Args... do not meet the customization point object's requirements, T shall not have a function call operator that participates in overload resolution.
For a given customization point object o, let p be a variable initialized as if by auto p = o;.
Then for any sequence of arguments args..., the following expressions have effects equivalent to o(args...):
- p(args...)
- as_const(p)(args...)
- std::move(p)(args...)
- std::move(as_const(p))(args...)
16.3.3.4 Algorithm function objects [alg.func.obj]
An algorithm function object is a customization point object ([customization.point.object]) that is specified as one or more overloaded function templates.
The name of these function templates designates the corresponding algorithm function object.
For an algorithm function object o, let S be the corresponding set of function templates.
Then for any sequence of arguments args …,o(args …) is expression-equivalent tos(args …), where the result of name lookup for s is the overload set S.
[Note 1:
Algorithm function objects are not found by argument-dependent name lookup ([basic.lookup.argdep]).
[Example 1: void foo() { using namespace std::ranges; std::vector<int> vec{1,2,3}; find(begin(vec), end(vec), 2); }
The function call expression at #1 invokes std::ranges::find, not std::find.
— _end example_]
— _end note_]
16.3.3.5 Functions within classes [functions.within.classes]
For the sake of exposition, [support] through [exec]and [depr] do not describe copy/move constructors, assignment operators, or (non-virtual) destructors with the same apparent semantics as those that can be generated by default ([class.copy.ctor], [class.copy.assign], [class.dtor]).
It is unspecified whether the implementation provides explicit definitions for such member function signatures, or for virtual destructors that can be generated by default.
16.3.3.6 Private members [objects.within.classes]
An implementation may define static or non-static class members, or both, as needed to implement the semantics of the member functions specified in [support]through [exec] and [depr].
For the sake of exposition, some subclauses provide representative declarations, and semantic requirements, for private members of classes that meet the external specifications of the classes.
The declarations for such members are followed by a comment that ends with exposition only, as in:streambuf* sb;
An implementation may use any technique that provides equivalent observable behavior.
16.3.3.7 Freestanding items [freestanding.item]
A freestanding item is a declaration, entity, typedef-name, or macro that is required to be present in a freestanding implementation and a hosted implementation.
Unless otherwise specified, the requirements on freestanding items for a freestanding implementation are the same as the corresponding requirements for a hosted implementation, except that not all of the members of those items are required to be present.
Function declarations and function template declarations followed by a comment that include freestanding-deleted arefreestanding deleted functions.
On freestanding implementations, it is implementation-defined whether each entity introduced by a freestanding deleted function is a deleted function ([dcl.fct.def.delete]) or whether the requirements are the same as the corresponding requirements for a hosted implementation.
[Note 1:
Deleted definitions reduce the chance of overload resolution silently changing when migrating from a freestanding implementation to a hosted implementation.
— _end note_]
[Example 1: double abs(double j); — _end example_]
A declaration in a synopsis is a freestanding item if
- it is followed by a comment that includes freestanding,
- it is followed by a comment that includes freestanding-deleted, or
- the header synopsis begins with a comment that includes freestanding and the declaration is not followed by a comment that includes hosted.
[Note 2:
Declarations followed by hosted in freestanding headers are not freestanding items.
As a result, looking up the name of such functions can vary between hosted and freestanding implementations.
— _end note_]
[Example 2: namespace std { — _end example_]
An entity, deduction guide, or typedef-nameis a freestanding item if its introducing declaration is not followed by a comment that includes hosted, and is:
- introduced by a declaration that is a freestanding item,
- a member of a freestanding item other than a namespace,
- an enumerator of a freestanding item,
- a deduction guide of a freestanding item,
- an enclosing namespace of a freestanding item,
- a friend of a freestanding item,
- denoted by a typedef-name that is a freestanding item, or
- denoted by an alias template that is a freestanding item.
A macro is a freestanding item if it is defined in a header synopsis and
- the definition is followed by a comment that includes freestanding, or
- the header synopsis begins with a comment that includes freestanding and the definition is not followed by a comment that includes hosted.
[Example 3: #define NULL see below — _end example_]
[Note 3:
Freestanding annotations follow some additional exposition conventions that do not impose any additional normative requirements.
Header synopses that begin with a comment containing "all freestanding" contain no hosted items and no freestanding deleted functions.
Header synopses that begin with a comment containing "mostly freestanding" contain at least one hosted item or freestanding deleted function.
Classes and class templates followed by a comment containing "partially freestanding" contain at least one hosted item or freestanding deleted function.
— _end note_]
[Example 4: template<class T, size_t N> struct array; template<class T, size_t N> struct array { constexpr reference operator[](size_type n);constexpr const_reference operator[](size_type n) const;constexpr reference at(size_type n); constexpr const_reference at(size_type n) const; }; — _end example_]