16 Library introduction [library]

16.3 Method of description [description]

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 describing implementation-defined types, and member functions .

16.3.3.2 Exposition-only entities, etc. [expos.only.entity]

Several entities and typedef-names defined in [support] through [exec] and [depr] are only defined for the purpose of exposition.

The declaration of such an entity or typedef-name is 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) // exposition only noexcept(is_nothrow_convertible_v<T, decay_t<T>>) { return std::forward<T>(v); } constexpr auto synth-three-way = // exposition only []<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 = // exposition only decltype(synth-three-way(declval<T&>(), declval<U&>())); }

An object dst is said to be decay-copied from a subexpression src if the type of dst is decay_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.139

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.

139)139)

Examples from [utility.requirements] include: Cpp17EqualityComparable, Cpp17LessThanComparable, Cpp17CopyConstructible.

Examples from [iterator.requirements] include: Cpp17InputIterator, Cpp17ForwardIterator.

16.3.3.3.2 Enumerated types [enumerated.types]

Several types defined in [input.output] are enumerated types.

Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration.140

The enumerated type enumerated can be written: enum enumerated {

V_{0}

V_{1}

V_{2}

V_{3}

, … }; inline const

{enumerated C}_{0}

(

V_{0}

); inline const

{enumerated C}_{1}

(

V_{1}

); inline const

{enumerated C}_{2}

(

V_{2}

); inline const

{enumerated C}_{3}

(

V_{3}

); ⋮

Here, the names

C_{0}

C_{1}

, etc. represent enumerated elements for this particular enumerated type.

All such elements have distinct values.

140)140)

Such as an integer type, with constant integer values ([basic.fundamental]).

16.3.3.3.3 Bitmask types [bitmask.types]

Several types defined in [support] through [exec] and [depr] are bitmask types.

Each bitmask type can be implemented as an enumerated type that overloads certain operators, as an integer type, or as a bitset .

The bitmask type bitmask can be written: // For exposition only. // int_type is an integral type capable of representing all values of the bitmask type. enum bitmask : int_type {

V_{0}

= 1 << 0,

V_{1}

= 1 << 1,

V_{2}

= 1 << 2,

V_{3}

= 1 << 3, … }; inline constexpr

{bitmask C}_{0}

(

V_{0}

); inline constexpr

{bitmask C}_{1}

(

V_{1}

); inline constexpr

{bitmask C}_{2}

(

V_{2}

); inline constexpr

{bitmask C}_{3}

(

V_{3}

); ⋮ 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

C_{0}

C_{1}

, etc. represent bitmask elements for this particular bitmask type.

All such elements have distinct, nonzero values such that, for any pair

C_{i}

and

C_{j}

where i ≠ j,

C_{i}

C_{i}

is nonzero and

C_{i}

C_{j}

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:

(4.1)
To set a value Y in an object X is to evaluate the expression X |= Y.
(4.2)
To clear a value Y in an object X is to evaluate the expression X &= ~Y.
(4.3)
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 use of characters and character sequences that follow a few uniform conventions:

(1.1)
Properties specified as locale-specific may 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].
(1.2)
The execution character set and the execution wide-character set are 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]
(1.3)
A letter is any of the 26 lowercase or 26 uppercase letters in the basic character set.
(1.4)
The decimal-point character is 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.
(1.5)
A character sequence is an array object A that can be declared as T A[N], where T is any of the types char, unsigned char, or signed char ([basic.fundamental]), optionally qualified by any combination of const or volatile.

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.141

The length of an ntbs is the number of elements that precede the terminating null character.

An empty ntbs has a length of zero.

The value of an ntbs is the sequence of values of the elements up to and including the terminating null character.

A static ntbs is an ntbs with static storage duration.142

141)141)

Many of the objects manipulated by function signatures declared in <cstring> are character sequences or ntbss.

The size of some of these character sequences is limited by a length value, maintained separately from the character sequence.

142)142)

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.143

A static ntmbs is an ntmbs with static storage duration.

143)143)

An ntbs that contains characters only from the basic literal character set is also an ntmbs.

Each multibyte character then consists of a single byte.

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.

The type of a customization point object, ignoring cv-qualifiers, shall model semiregular ([concepts.object]).

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 model invocable<T&, Args...>, invocable<const T&, Args...>, invocable<T, Args...>, and invocable<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...):

(5.1)
p(args...)
(5.2)
as_const(p)(args...)
(5.3)
std::move(p)(args...)
(5.4)
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 to s(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]).

When found by unqualified name lookup ([basic.lookup.unqual]) for the postfix-expression in a function call ([expr.call]), they inhibit argument-dependent name lookup.

[Example 1: void foo() { using namespace std::ranges; std::vector<int> vec{1,2,3}; find(begin(vec), end(vec), 2); // #1 }

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]

[support] through [exec] and [depr] do not specify the representation of classes, and intentionally omit specification of class members .

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; // exposition only

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 are freestanding 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); // freestanding-deleted — end example]

A declaration in a synopsis is a freestanding item if

(4.1)
it is followed by a comment that includes freestanding,
(4.2)
it is followed by a comment that includes freestanding-deleted, or
(4.3)
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: // all freestanding namespace std { — end example]

An entity, deduction guide, or typedef-name is a freestanding item if it is:

(5.1)
introduced by a declaration that is a freestanding item,
(5.2)
a member of a freestanding item other than a namespace,
(5.3)
an enumerator of a freestanding item,
(5.4)
a deduction guide of a freestanding item,
(5.5)
an enclosing namespace of a freestanding item,
(5.6)
a friend of a freestanding item,
(5.7)
denoted by a typedef-name that is a freestanding item, or
(5.8)
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

(6.1)
the definition is followed by a comment that includes freestanding, or
(6.2)
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 // freestanding — 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; // partially freestanding 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); // freestanding-deleted constexpr const_reference at(size_type n) const; // freestanding-deleted }; — end example]