16 Library introduction [library]

16.4 Method of description [description]

This subclause describes the conventions used to specify the C++ standard library.

[structure] describes the structure of the normative [support] through [thread] and [depr].

[conventions] describes other editorial conventions.

16.4.1 Structure of each clause [structure]

16.4.1.1 Elements [structure.elements]

Each library clause contains the following elements, as applicable:151

(1.1)
Summary
(1.2)
Requirements
(1.3)
Detailed specifications
(1.4)
References to the C standard library

151)

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.

⮥

16.4.1.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:

(2.1)
macros
(2.2)
values
(2.3)
types and alias templates
(2.4)
classes and class templates
(2.5)
functions and function templates
(2.6)
objects and variable templates
(2.7)
concepts

16.4.1.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:

(1.1)
Template arguments
(1.2)
Derived classes
(1.3)
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 32) 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.

For example, destructible ([concept.destructible]) is such a named requirement.

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

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.

[Example

The required < operator of the totally_ordered concept ([concept.totallyordered]) does not meet the semantic requirements of that concept when operating on NaNs.

— end example

]

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.

152)

Although in some cases the code given is unambiguously the optimum implementation.

⮥

16.4.1.4 Detailed specifications [structure.specifications]

The detailed specifications each contain the following elements:

(1.1)
name and brief description
(1.2)
synopsis (class definition or function declaration, as appropriate)
(1.3)
restrictions on template arguments, if any
(1.4)
description of class invariants
(1.5)
description of function semantics

Descriptions of class member functions follow the order (as appropriate):153

(2.1)
constructor(s) and destructor
(2.2)
copying, moving & assignment functions
(2.3)
comparison functions
(2.4)
modifier functions
(2.5)
observer functions
(2.6)
operators and other non-member functions

Descriptions of function semantics contain the following elements (as appropriate):154

(3.1)
Constraints: the conditions for the function's participation in overload resolution ([over.match]).
[Note
: Failure to meet such a condition results in the function's silent non-viability. — end note
]

[Example
: An implementation might express such a condition via a constraint-expression. — end example
]
(3.2)
Mandates: the conditions that, if not met, render the program ill-formed.
[Example
: An implementation might express such a condition via the constant-expression in a static_assert-declaration. If the diagnostic is to be emitted only after the function has been selected by overload resolution, an implementation might express such a condition via a constraint-expression and also define the function as deleted. — end example
]
(3.3)
Preconditions: the conditions that the function assumes to hold whenever it is called; violation of any preconditions results in undefined behavior.
(3.4)
Effects: the actions performed by the function.
(3.5)
Synchronization: the synchronization operations ([intro.multithread]) applicable to the function.
(3.6)
Postconditions: the conditions (sometimes termed observable results) established by the function.
(3.7)
Returns: a description of the value(s) returned by the function.
(3.8)
Throws: any exceptions thrown by the function, and the conditions that would cause the exception.
(3.9)
Complexity: the time and/or space complexity of the function.
(3.10)
Remarks: additional semantic constraints on the function.
(3.11)
Error conditions: the error conditions for error codes reported by 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 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, 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 the return 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 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.155

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 errc constants ([syserr]).

153)

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.

⮥

154)

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.

⮥

155)

This simplifies the presentation of complexity requirements in some cases.

⮥

16.4.1.5 C library [structure.see.also]

Paragraphs labeled “See also” contain cross-references to the relevant portions of other standards ([intro.refs]).

16.4.2 Other conventions [conventions]

This subclause 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.4.2.1 Exposition-only functions [expos.only.func]

Several function templates defined in [support] through [thread] and [depr] are only defined for the purpose of exposition.

The declaration of such a function is followed by a comment ending in exposition only.

The following are defined for exposition only to aid in the specification of the library:

template<class T> constexpr decay_t<T> decay-copy(T&& v)
    noexcept(is_nothrow_convertible_v<T, decay_t<T>>)           // exposition only
  { 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&>()));

16.4.2.2 Type descriptions [type.descriptions]

16.4.2.2.1 General [type.descriptions.general]

The Requirements subclauses may describe names that are used to specify constraints on template arguments.156

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.

156)

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

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

⮥

16.4.2.2.2 Exposition-only types [expos.only.types]

Several types defined in [support] through [thread] and [depr] are defined for the purpose of exposition.

The declaration of such a type is followed by a comment ending in exposition only.

[Example

namespace std {
  extern "C" using some-handler = int(int, void*, double);  // exposition only
}

The type placeholder some-handler can now be used to specify a function that takes a callback parameter with C language linkage.

— end example

]

16.4.2.2.3 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.157

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.

157)

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

⮥

16.4.2.2.4 Bitmask types [bitmask.types]

Several types defined in [support] through [thread] 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 \neq 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.4.2.2.5 Character sequences [character.seq]

The C standard library makes widespread use of characters and character sequences that follow a few uniform conventions:

(1.1)
A letter is any of the 26 lowercase or 26 uppercase letters in the basic execution character set.
(1.2)
The decimal-point character is the (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 [thread] and [depr] by a period, '.', which is also its value in the "C" locale, but may change during program execution by a call to setlocale(int, const char*),158 or by a change to a locale object, as described in [locales] and [input.output].
(1.3)
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.

158)

declared in <clocale> ([clocale.syn]).

⮥

16.4.2.2.5.1 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.159

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

159)

Many of the objects manipulated by function signatures declared in <cstring> ([cstring.syn]) 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.

⮥

160)

A string-literal, such as "abc", is a static ntbs.

⮥

16.4.2.2.5.2 Multibyte strings [multibyte.strings]

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

A static ntmbs is an ntmbs with static storage duration.

161)

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

Each multibyte character then consists of a single byte.

⮥

16.4.2.2.6 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 type T of a customization point object shall model 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.

Each customization point object type constrains its return type to model a particular concept.

[Note

Many of the customization point objects in the library evaluate function call expressions with an unqualified name which results in a call to a program-defined function found by argument dependent name lookup ([basic.lookup.argdep]).

To preclude such an expression resulting in a call to unconstrained functions with the same name in namespace std, customization point objects specify that lookup for these expressions is performed in a context that includes deleted overloads matching the signatures of overloads defined in namespace std.

When the deleted overloads are viable, program-defined overloads need be more specialized ([temp.func.order]) or more constrained ([temp.constr.order]) to be used by a customization point object.

— end note

]

16.4.2.3 Functions within classes [functions.within.classes]

For the sake of exposition, [support] through [thread] 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.4.2.4 Private members [objects.within.classes]

[support] through [thread] 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 [thread] 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.