%!TEX root = std.tex \rSec0[library]{Library introduction} \rSec1[library.general]{General} \pnum This Clause describes the contents of the \defnx{\Cpp{} standard library}{library!\Cpp{} standard}, how a well-formed \Cpp{} program makes use of the library, and how a conforming implementation may provide the entities in the library. \pnum The following subclauses describe the method of description\iref{description} and organization\iref{organization} of the library. \ref{requirements}, \ref{\firstlibchapter} through \ref{\lastlibchapter}, and \ref{depr} specify the contents of the library, as well as library requirements and constraints on both well-formed \Cpp{} programs and conforming implementations. \pnum Detailed specifications for each of the components in the library are in \ref{\firstlibchapter}--\ref{\lastlibchapter}, as shown in \tref{library.categories}. \begin{floattable}{Library categories}{library.categories} {ll} \topline \hdstyle{Clause} & \hdstyle{Category} \\ \capsep \ref{support} & Language support library \\ \ref{concepts} & Concepts library \\ \ref{diagnostics} & Diagnostics library \\ \ref{mem} & Memory management library \\ \ref{meta} & Metaprogramming library \\ \ref{utilities} & General utilities library \\ \ref{containers} & Containers library \\ \ref{iterators} & Iterators library \\ \ref{ranges} & Ranges library \\ \ref{algorithms} & Algorithms library \\ \ref{strings} & Strings library \\ \ref{text} & Text processing library \\ \ref{numerics} & Numerics library \\ \ref{time} & Time library \\ \ref{input.output} & Input/output library \\ \ref{thread} & Concurrency support library \\ \ref{exec} & Execution control library \\ \end{floattable} \pnum The operating system interface described in \IsoPosix{} is hereinafter called \defn{POSIX}. \pnum The language support library\iref{support} provides components that are required by certain parts of the \Cpp{} language, such as memory allocation\iref{expr.new,expr.delete} and exception processing\iref{except}. \pnum The concepts library\iref{concepts} describes library components that \Cpp{} programs may use to perform compile-time validation of template arguments and perform function dispatch based on properties of types. \pnum The diagnostics library\iref{diagnostics} provides a consistent framework for reporting errors in a \Cpp{} program, including predefined exception classes. \pnum The memory management library\iref{mem} provides components for memory management, including smart pointers and scoped allocators. \pnum The metaprogramming library\iref{meta} describes facilities for use in templates and during constant evaluation, including type traits, integer sequences, and rational arithmetic. \pnum The general utilities library\iref{utilities} includes components used by other library elements, such as a predefined storage allocator for dynamic storage management\iref{basic.stc.dynamic}, and components used as infrastructure in \Cpp{} programs, such as tuples and function wrappers. \pnum The containers\iref{containers}, iterators\iref{iterators}, ranges\iref{ranges}, and algorithms\iref{algorithms} libraries provide a \Cpp{} program with access to a subset of the most widely used algorithms and data structures. \pnum The strings library\iref{strings} provides support for manipulating sequences of type \tcode{char}, sequences of type \keyword{char8_t}, sequences of type \keyword{char16_t}, sequences of type \keyword{char32_t}, sequences of type \keyword{wchar_t}, and sequences of any other character-like type. \pnum The text processing library\iref{text} provides support for text processing, including formatting, internationalization support and regular expression matching and searching. \pnum The numerics library\iref{numerics} provides numeric algorithms and complex number components that extend support for numeric processing. The \tcode{valarray} component provides support for \textit{n}-at-a-time processing, potentially implemented as parallel operations on platforms that support such processing. The random number component provides facilities for generating pseudo-random numbers. \pnum The time library\iref{time} provides generally useful time utilities. \pnum The input/output library\iref{input.output} provides the \tcode{iostream} components that are the primary mechanism for \Cpp{} program input and output. They can be used with other elements of the library, particularly strings, locales, and iterators. \pnum The concurrency support library\iref{thread} provides components to create and manage threads, including atomic operations, mutual exclusion, and interthread communication. \pnum The execution control library\iref{exec} provides components supporting execution of function objects. \rSec1[library.c]{The C standard library} \pnum The \Cpp{} standard library also makes available the facilities of the C standard library, \indextext{library!C standard}% suitably adjusted to ensure static type safety. \pnum The descriptions of many library functions rely on the C standard library for the semantics of those functions. In some cases, the signatures specified in this document may be different from the signatures in the C standard library, and additional overloads may be declared in this document, but the behavior and the preconditions (including any preconditions implied by the use of a C \tcode{restrict} qualifier) are the same unless otherwise stated. \pnum A call to a C standard library function is a non-constant library call\iref{defns.nonconst.libcall} if it raises a floating-point exception other than \tcode{FE_INEXACT}. The semantics of a call to a C standard library function evaluated as a core constant expression are those specified in \IsoC{}, Annex F \begin{footnote} See also \IsoC{}, 7.6. \end{footnote} to the extent applicable to the floating-point types\iref{basic.fundamental} that are parameter types of the called function. \begin{note} \IsoC{}, Annex F specifies the conditions under which floating-point exceptions are raised and the behavior when NaNs and/or infinities are passed as arguments. \end{note} \begin{note} Equivalently, a call to a C standard library function is a non-constant library call if \tcode{errno} is set when \tcode{math_errhandling \& MATH_ERRNO} is \tcode{true}. \end{note} \rSec1[description]{Method of description} \rSec2[description.general]{General} \pnum Subclause \ref{description} describes the conventions used to specify the \Cpp{} standard library. \ref{structure} describes the structure of \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr}. \ref{conventions} describes other editorial conventions. \rSec2[structure]{Structure of each clause} \rSec3[structure.elements]{Elements} \pnum Each library clause contains the following elements, as applicable: \begin{footnote} 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. \end{footnote} \begin{itemize} \item Summary \item Requirements \item Detailed specifications \item References to the C standard library \end{itemize} \rSec3[structure.summary]{Summary} \pnum 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. \pnum The contents of the summary and the detailed specifications include: \begin{itemize} \item macros \item values \item types and alias templates \item classes and class templates \item functions and function templates \item objects and variable templates \item concepts \end{itemize} \rSec3[structure.requirements]{Requirements} \pnum \indextext{requirements}% Requirements describe constraints that shall be met by a \Cpp{} program that extends the standard library. Such extensions are generally one of the following: \begin{itemize} \item Template arguments \item Derived classes \item Containers, iterators, and algorithms that meet an interface convention or model a concept \end{itemize} \pnum The string and iostream components use an explicit representation of operations required of template arguments. They use a class template \tcode{char_traits} to define these constraints. \pnum Interface convention requirements are stated as generally as possible. Instead of stating ``class \tcode{X} has to define a member function \tcode{operator++()}'', the interface requires ``for any object \tcode{x} of class \tcode{X}, \tcode{++x} is defined''. That is, whether the operator is a member is unspecified. \pnum 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\iref{algorithms} that uses the well-defined expression requirements is described in terms of the valid expressions for its template type parameters. \pnum The library specification uses a typographical convention for naming requirements. Names in \textit{italic} type that begin with the prefix \oldconcept{} refer to sets of well-defined expression requirements typically presented in tabular form, possibly with additional prose semantic requirements. For example, \oldconcept{Destructible}~(\tref{cpp17.destructible}) is such a named requirement. Names in \tcode{constant width} type refer to library concepts which are presented as a concept definition\iref{temp}, possibly with additional prose semantic requirements. For example, \libconcept{destructible}\iref{concept.destructible} is such a named requirement. \pnum Template argument requirements are sometimes referenced by name. See~\ref{type.descriptions}. \pnum In some cases the semantic requirements are presented as \Cpp{} 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. \begin{footnote} Although in some cases the code given is unambiguously the optimum implementation. \end{footnote} \pnum 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. \begin{example} The required \tcode{<} operator of the \libconcept{totally_ordered} concept\iref{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. \pnum A declaration may explicitly impose requirements through its associated constraints\iref{temp.constr.decl}. When the associated constraints refer to a concept\iref{temp.concept}, the semantic constraints specified for that concept are additionally imposed on the use of the declaration. \rSec3[structure.specifications]{Detailed specifications} \pnum The detailed specifications each contain the following elements:% \begin{itemize} \item name and brief description \item synopsis (class definition or function declaration, as appropriate) \item restrictions on template arguments, if any \item description of class invariants \item description of function semantics \end{itemize} \pnum Descriptions of class member functions follow the order (as appropriate): \begin{footnote} 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. \end{footnote} \begin{itemize} \item constructor(s) and destructor \item copying, moving \& assignment functions \item comparison operator functions \item modifier functions \item observer functions \item operators and other non-member functions \end{itemize} \pnum Descriptions of function semantics contain the following elements (as appropriate): \begin{footnote} 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 \expects element. \end{footnote} \begin{itemize} \item \constraints the conditions for the function's participation in overload resolution\iref{over.match}. \begin{note} Failure to meet such a condition results in the function's silent non-viability. \end{note} \begin{example} An implementation can express such a condition via a \grammarterm{constraint-expression}\iref{temp.constr.decl}. \end{example} \item \mandates the conditions that, if not met, render the program ill-formed. \begin{example} An implementation can express such a condition via the \grammarterm{constant-expression} in a \grammarterm{static_assert-declaration}\iref{dcl.pre}. 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 \grammarterm{constraint-expression}\iref{temp.constr.decl} and also define the function as deleted. \end{example} \item \constantwhen the conditions that are required for a call to the function to be a constant subexpression\iref{defns.const.subexpr}. \item \expects conditions that the function assumes to hold whenever it is called; violation of any preconditions results in undefined behavior. \begin{example} An implementation can express some such conditions via the use of a contract assertion, such as a precondition assertion\iref{dcl.contract.func}. \end{example} \item \hardexpects conditions that the function assumes to hold whenever it is called. \begin{itemize} \item When invoking the function in a hardened implementation, prior to any other observable side effects of the function, contract assertions whose predicates are as described in the hardened precondition are evaluated with a terminating semantic\iref{basic.contract.eval}. \item When invoking the function in a non-hardened implementation, if any hardened precondition is violated, the program has undefined behavior. \end{itemize} \item \effects the actions performed by the function. \item \sync the synchronization operations\iref{intro.multithread} applicable to the function. \item \ensures the conditions (sometimes termed observable results) established by the function. \begin{example} An implementation can express some such conditions via the use of a contract assertion, such as a postcondition assertion\iref{dcl.contract.func}. \end{example} \item \result for a \grammarterm{typename-specifier}, a description of the named type; for an \grammarterm{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. \item \returns a description of the value(s) returned by the function. \item \throws any exceptions thrown by the function, and the conditions that would cause the exception. \item \complexity the time and/or space complexity of the function. \item \remarks additional semantic constraints on the function. \item \errors the error conditions for error codes reported by the function. \end{itemize} \pnum Whenever the \Fundescx{Effects} element specifies that the semantics of some function \tcode{F} are \term{Equivalent to} some code sequence, then the various elements are interpreted as follows. If \tcode{F}'s semantics specifies any \Fundescx{Constraints} or \Fundescx{Mandates} elements, then those requirements are logically imposed prior to the \term{equivalent-to} semantics. Next, the semantics of the code sequence are determined by the \Fundescx{Constraints}, \Fundescx{Mandates}, \Fundescx{Constant When}, \Fundescx{Preconditions}, \Fundescx{Hardened preconditions}, \Fundescx{Effects}, \Fundescx{Synchronization}, \Fundescx{Postconditions}, \Fundescx{Returns}, \Fundescx{Throws}, \Fundescx{Complexity}, \Fundescx{Remarks}, and \Fundescx{Error conditions} specified for the function invocations contained in the code sequence. The value returned from \tcode{F} is specified by \tcode{F}'s \Fundescx{Returns} element, or if \tcode{F} has no \Fundescx{Returns} element, a non-\keyword{void} return from \tcode{F} is specified by the \tcode{return} statements\iref{stmt.return} in the code sequence. If \tcode{F}'s semantics contains a \Fundescx{Throws}, \Fundescx{Postconditions}, or \Fundescx{Complexity} element, then that supersedes any occurrences of that element in the code sequence. \pnum For non-reserved replacement and handler functions, \ref{support} specifies two behaviors for the functions in question: their required and default behavior. The \defnx{default behavior}{behavior!default} describes a function definition provided by the implementation. The \defnx{required behavior}{behavior!required} describes the semantics of a function definition provided by either the implementation or a \Cpp{} program. Where no distinction is explicitly made in the description, the behavior described is the required behavior. \pnum If the formulation of a complexity requirement calls for a negative number of operations, the actual requirement is zero operations. \begin{footnote} This simplifies the presentation of complexity requirements in some cases. \end{footnote} \pnum Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees meet the requirements. \pnum Error conditions specify conditions where a function may fail. The conditions are listed, together with a suitable explanation, as the \tcode{enum class errc} constants\iref{syserr}. \rSec3[structure.see.also]{C library} \pnum Paragraphs labeled ``\textsc{See also}'' contain cross-references to the relevant portions of other standards\iref{intro.refs}. \rSec2[conventions]{Other conventions} \rSec3[conventions.general]{General} \indextext{conventions}% \pnum Subclause \ref{conventions} describes several editorial conventions used to describe the contents of the \Cpp{} standard library. These conventions are for describing implementation-defined types\iref{type.descriptions}, and member functions\iref{functions.within.classes}. \rSec3[expos.only.entity]{Exposition-only entities, etc.} \pnum Several entities declared in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} are provided for exposition only. The declaration of such an entity is followed by a comment ending in \expos. \pnum The following are provided for exposition only to aid in the specification of the library: \indexlibrary{decay-copy@\exposid{decay-copy}}% \begin{codeblock} namespace std { template requires @\libconcept{convertible_to}@> constexpr decay_t @\exposidnc{decay-copy}@(T&& v) // \expos noexcept(is_nothrow_convertible_v>) { return std::forward(v); } constexpr auto @\exposidnc{synth-three-way}@ = // \expos [](const T& t, const U& u) requires requires { { t < u } -> @\exposconcept{boolean-testable}@; { u < t } -> @\exposconcept{boolean-testable}@; } { if constexpr (@\libconcept{three_way_comparable_with}@) { return t <=> u; } else { if (t < u) return weak_ordering::less; if (u < t) return weak_ordering::greater; return weak_ordering::equivalent; } }; template using @\exposidnc{synth-three-way-result}@ = // \expos decltype(@\exposidnc{synth-three-way}@(declval(), declval())); template concept @\defexposconceptnc{constexpr-wrapper-like}@ = // \expos @\libconcept{convertible_to}@ && @\libconcept{equality_comparable_with}@ && bool_constant::value && bool_constant(T()) == T::value>::value; } \end{codeblock} \pnum An object \tcode{dst} is said to be \defn{decay-copied from} a subexpression \tcode{src} if the type of \tcode{dst} is \begin{codeblock} decay_t \end{codeblock} and \tcode{dst} is copy-initialized from \tcode{src}. \rSec3[type.descriptions]{Type descriptions} \rSec4[type.descriptions.general]{General} \pnum The Requirements subclauses may describe names that are used to specify constraints on template arguments. \begin{footnote} Examples from~\ref{utility.requirements} include: \oldconcept{EqualityComparable}, \oldconcept{LessThanComparable}, \oldconcept{CopyConstructible}. Examples from~\ref{iterator.requirements} include: \oldconcept{InputIterator}, \oldconcept{ForwardIterator}. \end{footnote} These names are used in library Clauses to describe the types that may be supplied as arguments by a \Cpp{} program when instantiating template components from the library. \pnum Certain types shown in \ref{input.output} are used to describe implementation-defined types. \indextext{types!implementation-defined}% They are based on other types, but with added constraints. \rSec4[enumerated.types]{Enumerated types} \pnum Several types specified in \ref{input.output} and \ref{re} are \defnadjx{enumerated}{types}{type}. Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration. \begin{footnote} Such as an integer type, with constant integer values\iref{basic.fundamental}. \end{footnote} \pnum The enumerated type \tcode{\placeholder{enumerated}} can be written: \begin{codeblock} enum @\placeholder{enumerated}@ { @$\tcode{\placeholder{V}}_{0}$@, @$\tcode{\placeholder{V}}_{1}$@, @$\tcode{\placeholder{V}}_{2}$@, @$\tcode{\placeholder{V}}_{3}$@, @$\ldots$@ }; inline const @$\tcode{\placeholder{enumerated C}}_{0}$@(@$\tcode{\placeholder{V}}_{0}$@); inline const @$\tcode{\placeholder{enumerated C}}_{1}$@(@$\tcode{\placeholder{V}}_{1}$@); inline const @$\tcode{\placeholder{enumerated C}}_{2}$@(@$\tcode{\placeholder{V}}_{2}$@); inline const @$\tcode{\placeholder{enumerated C}}_{3}$@(@$\tcode{\placeholder{V}}_{3}$@); @\vdots@ \end{codeblock} \pnum Here, the names $\tcode{\placeholder{C}}_0$, $\tcode{\placeholder{C}}_1$, etc.\ represent \defnx{enumerated elements}{enumerated element} for this particular enumerated type. \indextext{type!enumerated}% All such elements have distinct values. \rSec4[bitmask.types]{Bitmask types} \pnum Several types specified in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} are \defnx{bitmask types}{type!bitmask}. Each bitmask type can be implemented as an enumerated type that overloads certain operators, as an integer type, or as a \tcode{bitset}\iref{template.bitset}. \indextext{type!enumerated}% \pnum The bitmask type \tcode{\placeholder{bitmask}} can be written: \begin{codeblock} // For exposition only. // \tcode{int_type} is an integral type capable of representing all values of the bitmask type. enum @\placeholder{bitmask}@ : int_type { @$\tcode{\placeholder{V}}_{0}$@ = 1 << 0, @$\tcode{\placeholder{V}}_{1}$@ = 1 << 1, @$\tcode{\placeholder{V}}_{2}$@ = 1 << 2, @$\tcode{\placeholder{V}}_{3}$@ = 1 << 3, @$\ldots$@ }; inline constexpr @$\tcode{\placeholder{bitmask C}}_{0}$@(@$\tcode{\placeholder{V}}_{0}{}$@); inline constexpr @$\tcode{\placeholder{bitmask C}}_{1}$@(@$\tcode{\placeholder{V}}_{1}{}$@); inline constexpr @$\tcode{\placeholder{bitmask C}}_{2}$@(@$\tcode{\placeholder{V}}_{2}{}$@); inline constexpr @$\tcode{\placeholder{bitmask C}}_{3}$@(@$\tcode{\placeholder{V}}_{3}{}$@); @\vdots@ constexpr @\placeholder{bitmask}{}@ operator&(@\placeholder{bitmask}{}@ X, @\placeholder{bitmask}{}@ Y) { return static_cast<@\placeholder{bitmask}{}@>( static_cast(X) & static_cast(Y)); } constexpr @\placeholder{bitmask}{}@ operator|(@\placeholder{bitmask}{}@ X, @\placeholder{bitmask}{}@ Y) { return static_cast<@\placeholder{bitmask}{}@>( static_cast(X) | static_cast(Y)); } constexpr @\placeholder{bitmask}{}@ operator^(@\placeholder{bitmask}{}@ X, @\placeholder{bitmask}{}@ Y) { return static_cast<@\placeholder{bitmask}{}@>( static_cast(X) ^ static_cast(Y)); } constexpr @\placeholder{bitmask}{}@ operator~(@\placeholder{bitmask}{}@ X) { return static_cast<@\placeholder{bitmask}{}@>(~static_cast(X)); } @\placeholder{bitmask}{}@& operator&=(@\placeholder{bitmask}{}@& X, @\placeholder{bitmask}{}@ Y) { X = X & Y; return X; } @\placeholder{bitmask}{}@& operator|=(@\placeholder{bitmask}{}@& X, @\placeholder{bitmask}{}@ Y) { X = X | Y; return X; } @\placeholder{bitmask}{}@& operator^=(@\placeholder{bitmask}{}@& X, @\placeholder{bitmask}{}@ Y) { X = X ^ Y; return X; } \end{codeblock} \pnum Here, the names $\tcode{\placeholder{C}}_0$, $\tcode{\placeholder{C}}_1$, etc.\ represent \defnx{bitmask elements}{bitmask!element} for this particular bitmask type. \indextext{type!bitmask}% All such elements have distinct, nonzero values such that, for any pair $\tcode{\placeholder{C}}_i$ and $\tcode{\placeholder{C}}_j$ where $i \neq j$, \tcode{$\placeholder{C}_i$ \& $\placeholder{C}_i$} is nonzero and \tcode{$\placeholder{C}_i$ \& $\placeholder{C}_j$} is zero. Additionally, the value \tcode{0} is used to represent an \defnx{empty bitmask}{bitmask!empty}, in which no bitmask elements are set. \pnum The following terms apply to objects and values of bitmask types: \begin{itemize} \item To \defnx{set}{bitmask!value!set} a value \textit{Y} in an object \textit{X} is to evaluate the expression \textit{X} \tcode{|=} \textit{Y}. \item To \defnx{clear}{bitmask!value!clear} a value \textit{Y} in an object \textit{X} is to evaluate the expression \textit{X} \tcode{\&= \~}\textit{Y}. \item The value \textit{Y} \defnx{is set}{bitmask!value!is set} in the object \textit{X} if the expression \textit{X} \tcode{\&} \textit{Y} is nonzero. \end{itemize} \rSec4[character.seq]{Character sequences} \rSec5[character.seq.general]{General} \pnum The C standard library makes widespread use \indextext{library!C standard}% of characters and character sequences that follow a few uniform conventions: \begin{itemize} \item Properties specified as \defn{locale-specific} may change during program execution by a call to \tcode{setlocale(int, const char*)}\iref{clocale.syn}, or by a change to a \tcode{locale} object, as described in \ref{locales} and \ref{input.output}. \item The \defnadj{execution}{character set} and the \defnadj{execution}{wide-character set} are supersets of the basic literal character set\iref{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 \keyword{wchar_t}. \begin{note} The encodings of the execution character sets can be unrelated to any literal encoding. \end{note} \item A \defn{letter} is any of the 26 lowercase or 26 \indextext{lowercase}% \indextext{uppercase}% uppercase letters in the basic character set. \item The \defnx{decimal-point character}{character!decimal-point} 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 \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} by a period, \indextext{period}% \tcode{'.'}, which is also its value in the \tcode{"C"} locale. \item A \defn{character sequence} is an array object\iref{dcl.array} \tcode{\placeholdernc{A}} that can be declared as \tcode{\placeholdernc{T\;A}[\placeholder{N}]}, where \tcode{\placeholder{T}} is any of the types \tcode{char}, \tcode{unsigned char}, or \tcode{signed char}\iref{basic.fundamental}, optionally qualified by any combination of \keyword{const} or \tcode{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 \tcode{\placeholder{S}} that points to its first element. \item \indextext{STATICALLY-WIDEN@\exposid{STATICALLY-WIDEN}}% Let \exposid{STATICALLY-WIDEN}\tcode{("...")} be \tcode{"..."} if \tcode{charT} is \tcode{char} and \tcode{L"..."} if \tcode{charT} is \keyword{wchar_t}. \end{itemize} \rSec5[byte.strings]{Byte strings} \indextext{string!null-terminated byte|see{\ntbs{}}}% \pnum A \defnx{null-terminated byte string}{NTBS@\ntbs{}}, or \ntbs{}, is a character sequence whose highest-addressed element with defined content has the value zero (the \defnx{terminating null character}{character!terminating null}); no other element in the sequence has the value zero. \begin{footnote} Many of the objects manipulated by function signatures declared in \libheaderref{cstring} are character sequences or \ntbs{}s. The size of some of these character sequences is limited by a length value, maintained separately from the character sequence. \end{footnote} \pnum The \defnx{length of an \ntbs{}}{NTBS@\ntbs{}!length} is the number of elements that precede the terminating null character. An \defnx{empty \ntbs{}}{NTBS@\ntbs{}!empty} has a length of zero. \pnum The \defnx{value of an \ntbs{}}{NTBS@\ntbs{}!value} is the sequence of values of the elements up to and including the terminating null character. \pnum A \defnx{static \ntbs{}}{NTBS@\ntbs{}!static} is an \ntbs{} with static storage duration. \begin{footnote} A \grammarterm{string-literal}, such as \tcode{"abc"}, is a static \ntbs{}. \end{footnote} \rSec5[multibyte.strings]{Multibyte strings} \pnum A \defnx{multibyte character}{character!multibyte} is a sequence of one or more bytes representing the code unit sequence for an encoded character of the execution character set. \indextext{string!null-terminated multibyte|see{\ntmbs{}}}% \pnum A \defnx{null-terminated multibyte string}{NTMBS@\ntmbs{}}, or \ntmbs{}, is an \ntbs{} that constitutes a sequence of valid multibyte characters, beginning and ending in the initial shift state. \begin{footnote} 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. \end{footnote} \pnum A \defnx{static \ntmbs{}}{NTMBS@\ntmbs{}!static} is an \ntmbs{} with static storage duration. \rSec4[customization.point.object]{Customization Point Object types} \pnum A \defnadj{customization point}{object} is a function object\iref{function.objects} with a literal class type that interacts with program-defined types while enforcing semantic requirements on that interaction. \pnum The type of a customization point object, ignoring cv-qualifiers, shall model \libconcept{semiregular}\iref{concepts.object} and shall be a structural type\iref{temp.param} and a trivially copyable type\iref{class.prop}. Every constructor of this type shall have a non-throwing exception specification\iref{except.spec}. \pnum All instances of a specific customization point object type shall be equal\iref{concepts.equality}. The effects of invoking different instances of a specific customization point object type on the same arguments are equivalent. \pnum The type \tcode{T} of a customization point object, ignoring \grammarterm{cv-qualifier}s, shall model \tcode{\libconcept{invocable}}, \tcode{\libconcept{invocable}}, \tcode{\libconcept{invocable}}, and \tcode{\libconcept{invocable}}\iref{concept.invocable} when the types in \tcode{Args...} meet the requirements specified in that customization point object's definition. When the types of \tcode{Args...} do not meet the customization point object's requirements, \tcode{T} shall not have a function call operator that participates in overload resolution. \pnum For a given customization point object \tcode{o}, let \tcode{p} be a variable initialized as if by \tcode{auto p = o;}. Then for any sequence of arguments \tcode{args...}, the following expressions have effects equivalent to \tcode{o(args...)}: \begin{itemize} \item \tcode{p(args...)} \item \tcode{as_const(p)(args...)} \item \tcode{std::move(p)(args...)} \item \tcode{std::move(as_const(p))(args...)} \end{itemize} \rSec3[alg.func.obj]{Algorithm function objects} \pnum An \defn{algorithm function object} is a customization point object\iref{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. \pnum For an algorithm function object \tcode{o}, let $S$ be the corresponding set of function templates. Then for any sequence of arguments $\tcode{args} \dotsc$, $\tcode{o(args} \dotsc \tcode{)}$ is expression-equivalent to $\tcode{s(args} \dotsc \tcode{)}$, where the result of name lookup for \tcode{s} is the overload set $S$. \begin{note} Algorithm function objects are not found by argument-dependent name lookup\iref{basic.lookup.argdep}. When found by unqualified name lookup\iref{basic.lookup.unqual} for the \grammarterm{postfix-expression} in a function call\iref{expr.call}, they inhibit argument-dependent name lookup. \begin{example} \begin{codeblock} void foo() { using namespace std::ranges; std::vector vec{1,2,3}; find(begin(vec), end(vec), 2); // \#1 } \end{codeblock} The function call expression at \#1 invokes \tcode{std::ranges::find}, not \tcode{std::find}. \end{example} \end{note} \rSec3[functions.within.classes]{Functions within classes} \pnum For the sake of exposition, \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{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\iref{class.copy.ctor,class.copy.assign,class.dtor}. \indextext{constructor!copy}% \indextext{operator!assignment}% \indextext{destructor}% It is unspecified whether the implementation provides explicit definitions for such member function signatures, or for virtual destructors that can be generated by default. \rSec3[objects.within.classes]{Private members} \pnum \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} do not specify the representation of classes, and intentionally omit specification of class members\iref{class.mem}. An implementation may define static or non-static class members, or both, as needed to implement the semantics of the member functions specified in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr}. \pnum 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 \expos, as in: \begin{codeblock} streambuf* sb; // \expos \end{codeblock} \pnum An implementation may use any technique that provides equivalent observable behavior. \rSec3[freestanding.item]{Freestanding items} \pnum \indextext{item!freestanding|see{freestanding item}}% A \defn{freestanding item} is a declaration, entity, or macro that is required to be present in a freestanding implementation and a hosted implementation. \pnum 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. \pnum Function declarations and function template declarations followed by a comment that include \textit{freestanding-deleted} are \defnadjx{freestanding deleted}{functions}{function}. On freestanding implementations, it is \impldef{whether a freestanding deleted function is a deleted function} whether each entity introduced by a freestanding deleted function is a deleted function\iref{dcl.fct.def.delete} or whether the requirements are the same as the corresponding requirements for a hosted implementation. \begin{note} Deleted definitions reduce the chance of overload resolution silently changing when migrating from a freestanding implementation to a hosted implementation. \end{note} \begin{example} \begin{codeblock} double abs(double j); // freestanding-deleted \end{codeblock} \end{example} \pnum \indextext{declaration!freestanding item}% A declaration in a synopsis is a freestanding item if \begin{itemize} \item it is followed by a comment that includes \textit{freestanding}, \item it is followed by a comment that includes \textit{freestanding-deleted}, or \item the header synopsis begins with a comment that includes \textit{freestanding} and the declaration is not followed by a comment that includes \textit{hosted}. \begin{note} Declarations followed by \textit{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} \end{itemize} \begin{example} \begin{codeblock} // all freestanding namespace std { \end{codeblock} \end{example} \pnum \indextext{entity!freestanding item}% \indextext{deduction guide!freestanding item}% An entity or deduction guide is a freestanding item if its introducing declaration is not followed by a comment that includes \textit{hosted}, and is: \begin{itemize} \item introduced by a declaration that is a freestanding item, \item a member of a freestanding item other than a namespace, \item an enumerator of a freestanding item, \item a deduction guide of a freestanding item, \item an enclosing namespace of a freestanding item, \item a friend of a freestanding item, \item denoted by a type alias that is a freestanding item, or \item denoted by an alias template that is a freestanding item. \end{itemize} \pnum \indextext{macro!freestanding item}% A macro is a freestanding item if it is defined in a header synopsis and \begin{itemize} \item the definition is followed by a comment that includes \textit{freestanding}, or \item the header synopsis begins with a comment that includes \textit{freestanding} and the definition is not followed by a comment that includes \textit{hosted}. \end{itemize} \begin{example} \begin{codeblock} #define NULL @\seebelow@ // freestanding \end{codeblock} \end{example} \pnum \begin{note} 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} \begin{example} \begin{codeblock} template struct array; // partially freestanding template 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{codeblock} \end{example} \rSec1[requirements]{Library-wide requirements} \rSec2[requirements.general]{General} \pnum Subclause \ref{requirements} specifies requirements that apply to the entire \Cpp{} standard library. \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} specify the requirements of individual entities within the library. \pnum Requirements specified in terms of interactions between threads do not apply to programs having only a single thread of execution. \pnum \ref{organization} describes the library's contents and organization, \ref{using} describes how well-formed \Cpp{} programs gain access to library entities, \ref{utility.requirements} describes constraints on types and functions used with the \Cpp{} standard library, \ref{constraints} describes constraints on well-formed \Cpp{} programs, and \ref{conforming} describes constraints on conforming implementations. \rSec2[organization]{Library contents and organization} \rSec3[organization.general]{General} \pnum \ref{contents} describes the entities and macros defined in the \Cpp{} standard library. \ref{headers} lists the standard library headers and some constraints on those headers. \ref{compliance} lists requirements for a freestanding implementation of the \Cpp{} standard library. \rSec3[contents]{Library contents} \pnum The \Cpp{} standard library provides definitions for the entities and macros described in the synopses of the \Cpp{} standard library headers\iref{headers}, unless otherwise specified. \pnum All library entities except \tcode{operator new} and \tcode{operator delete} are defined within the namespace \tcode{std} or namespaces nested within namespace \tcode{std}. \begin{footnote} The C standard library headers\iref{support.c.headers} also define names within the global namespace, while the \Cpp{} headers for C library facilities\iref{headers} can also define names within the global namespace. \end{footnote} \indextext{namespace} It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an inline namespace inside that namespace. \begin{footnote} This gives implementers freedom to use inline namespaces to support multiple configurations of the library. \end{footnote} \pnum Whenever an unqualified name other than \tcode{swap}, \tcode{make_error_code}, \tcode{make_error_condition}, \tcode{from_stream}, or \tcode{submdspan_mapping} is used in the specification of a declaration \tcode{D} in \ref{\firstlibchapter} through \ref{\lastlibchapter} or \ref{depr}, its meaning is established as-if by performing unqualified name lookup\iref{basic.lookup.unqual} in the context of \tcode{D}. \begin{note} Argument-dependent lookup is not performed. \end{note} Similarly, the meaning of a \grammarterm{qualified-id} is established as-if by performing qualified name lookup\iref{basic.lookup.qual} in the context of \tcode{D}. \begin{example} The reference to \tcode{is_array_v} in the specification of \tcode{std::to_array}\iref{array.creation} refers to \tcode{::std::is_array_v}. \end{example} \begin{note} Operators in expressions\iref{over.match.oper} are not so constrained; see \ref{global.functions}. \end{note} The meaning of the unqualified name \tcode{swap} is established in an overload resolution context for swappable values\iref{swappable.requirements}. The meanings of the unqualified names \tcode{make_error_code}, \tcode{make_error_condition}, \tcode{from_stream}, and \tcode{submdspan_mapping} are established as-if by performing argument-dependent lookup\iref{basic.lookup.argdep}. \rSec3[headers]{Headers} \pnum Each element of the \Cpp{} standard library is declared or defined (as appropriate) in a \defn{header}. \begin{footnote} A header is not necessarily a source file, nor are the sequences delimited by \tcode{<} and \tcode{>} in header names necessarily valid source file names\iref{cpp.include}. \end{footnote} \pnum The \Cpp{} standard library provides the \defnx{\Cpp{} library headers}{header!\Cpp{} library}, shown in \tref{headers.cpp}. \begin{multicolfloattable}{\Cpp{} library headers}{headers.cpp} {llll} \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \end{multicolfloattable} \pnum The facilities of the C standard library are provided in the \indextext{library!C standard}% additional headers shown in \tref{headers.cpp.c}.% \begin{footnote} It is intentional that there is no \Cpp{} header for any of these C headers: \libnoheader{stdnoreturn.h}, \libnoheader{threads.h}. \end{footnote} \begin{multicolfloattable}{\Cpp{} headers for C library facilities}{headers.cpp.c} {lllllll} \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \columnbreak \tcode{} \\ \tcode{} \\ \tcode{} \\ \end{multicolfloattable} \pnum The headers listed in \tref{headers.cpp}, or, for a freestanding implementation, the subset of such headers that are provided by the implementation, are collectively known as the \defnadj{importable}{\Cpp{} library headers}. \begin{note} Importable \Cpp{} library headers can be imported\iref{module.import}. \end{note} \begin{example} \begin{codeblock} import ; // imports the \tcode{} header unit std::vector vi; // OK \end{codeblock} \end{example} \pnum Except as noted in \ref{library} through \ref{\lastlibchapter} and \ref{depr}, the contents of each header \tcode{c\placeholder{name}} is the same as that of the corresponding header \tcode{\placeholder{name}.h} as specified in the C standard library\iref{intro.refs}. In the \Cpp{} standard library, however, the declarations (except for names which are defined as macros in C) are within namespace scope\iref{basic.scope.namespace} of the namespace \tcode{std}. It is unspecified whether these names (including any overloads added in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr}) are first declared within the global namespace scope and are then injected into namespace \tcode{std} by explicit \grammarterm{using-declaration}{s}\iref{namespace.udecl}. \pnum Names which are defined as macros in C shall be defined as macros in the \Cpp{} standard library, even if C grants license for implementation as functions. \begin{note} The names defined as macros in C include the following: \tcode{assert}, \tcode{offsetof}, \tcode{setjmp}, \tcode{va_arg}, \tcode{va_end}, and \tcode{va_start}. \end{note} \pnum Names that are defined as functions in C shall be defined as functions in the \Cpp{} standard library. \begin{footnote} This disallows the practice, allowed in C, of providing a masking macro in addition to the function prototype. The only way to achieve equivalent inline behavior in \Cpp{} is to provide a definition as an extern inline function. \end{footnote} \pnum Identifiers that are keywords or operators in \Cpp{} shall not be defined as macros in \Cpp{} standard library headers. \begin{footnote} In particular, including the standard header \libheader{iso646.h} has no effect. \end{footnote} \pnum Subclause \ref{support.c.headers} describes the effects of using the \tcode{\placeholder{name}.h} (C header) form in a \Cpp{} program. \begin{footnote} The \tcode{".h"} headers dump all their names into the global namespace, whereas the newer forms keep their names in namespace \tcode{std}. Therefore, the newer forms are the preferred forms for all uses except for \Cpp{} programs which are intended to be strictly compatible with C. \end{footnote} \pnum \IsoC{}, Annex K describes a large number of functions, with associated types and macros, which ``promote safer, more secure programming'' than many of the traditional C library functions. The names of the functions have a suffix of \tcode{_s}; most of them provide the same service as the C library function with the unsuffixed name, but generally take an additional argument whose value is the size of the result array. If any \Cpp{} header is included, it is \impldef{whether functions from Annex K of the C standard library are declared when \Cpp{} headers are included} whether any of these names is declared in the global namespace. (None of them is declared in namespace \tcode{std}.) \pnum \tref{c.annex.k.names} lists the Annex K names that may be declared in some header. These names are also subject to the restrictions of~\ref{macro.names}. \begin{multicolfloattable}{Names from \IsoC{}, Annex K}{c.annex.k.names} {llll} \tcode{abort_handler_s} \\ \tcode{asctime_s} \\ \tcode{bsearch_s} \\ \tcode{constraint_handler_t} \\ \tcode{ctime_s} \\ \tcode{errno_t} \\ \tcode{fopen_s} \\ \tcode{fprintf_s} \\ \tcode{freopen_s} \\ \tcode{fscanf_s} \\ \tcode{fwprintf_s} \\ \tcode{fwscanf_s} \\ \tcode{getenv_s} \\ \tcode{gets_s} \\ \tcode{gmtime_s} \\ \tcode{ignore_handler_s} \\ \tcode{localtime_s} \\ \tcode{L_tmpnam_s} \\ \tcode{mbsrtowcs_s} \\ \columnbreak \tcode{mbstowcs_s} \\ \tcode{memcpy_s} \\ \tcode{memmove_s} \\ \tcode{memset_s} \\ \tcode{printf_s} \\ \tcode{qsort_s} \\ \tcode{RSIZE_MAX} \\ \tcode{rsize_t} \\ \tcode{scanf_s} \\ \tcode{set_constraint_handler_s} \\ \tcode{snprintf_s} \\ \tcode{snwprintf_s} \\ \tcode{sprintf_s} \\ \tcode{sscanf_s} \\ \tcode{strcat_s} \\ \tcode{strcpy_s} \\ \tcode{strerrorlen_s} \\ \tcode{strerror_s} \\ \tcode{strlen_s} \\ \columnbreak \tcode{strncat_s} \\ \tcode{strncpy_s} \\ \tcode{strtok_s} \\ \tcode{swprintf_s} \\ \tcode{swscanf_s} \\ \tcode{tmpfile_s} \\ \tcode{TMP_MAX_S} \\ \tcode{tmpnam_s} \\ \tcode{vfprintf_s} \\ \tcode{vfscanf_s} \\ \tcode{vfwprintf_s} \\ \tcode{vfwscanf_s} \\ \tcode{vprintf_s} \\ \tcode{vscanf_s} \\ \tcode{vsnprintf_s} \\ \tcode{vsnwprintf_s} \\ \tcode{vsprintf_s} \\ \tcode{vsscanf_s} \\ \tcode{vswprintf_s} \\ \columnbreak \tcode{vswscanf_s} \\ \tcode{vwprintf_s} \\ \tcode{vwscanf_s} \\ \tcode{wcrtomb_s} \\ \tcode{wcscat_s} \\ \tcode{wcscpy_s} \\ \tcode{wcsncat_s} \\ \tcode{wcsncpy_s} \\ \tcode{wcsnlen_s} \\ \tcode{wcsrtombs_s} \\ \tcode{wcstok_s} \\ \tcode{wcstombs_s} \\ \tcode{wctomb_s} \\ \tcode{wmemcpy_s} \\ \tcode{wmemmove_s} \\ \tcode{wprintf_s} \\ \tcode{wscanf_s} \\ \end{multicolfloattable} \rSec3[std.modules]{Modules} \pnum The \Cpp{} standard library provides the following \defn{\Cpp{} library modules}. \pnum The named module \tcode{std} exports declarations in namespace \tcode{std} that are provided by the importable \Cpp{} library headers (\tref{headers.cpp} or the subset provided by a freestanding implementation) and the \Cpp{} headers for C library facilities~(\tref{headers.cpp.c}). It additionally exports declarations in the global namespace for the storage allocation and deallocation functions that are provided by \libheaderref{new}. \pnum The named module \tcode{std.compat} exports the same declarations as the named module \tcode{std}, and additionally exports \begin{itemize} \item declarations in the global namespace corresponding to the declarations in namespace \tcode{std} that are provided by the \Cpp{} headers for C library facilities~(\tref{headers.cpp.c}), except the explicitly excluded declarations described in \ref{support.c.headers.other} and \item declarations provided by the headers \libheaderref{stdbit.h} and \libheaderref{stdckdint.h}. \end{itemize} \pnum It is unspecified to which module a declaration in the standard library is attached. \begin{note} Conforming implementations ensure that mixing \tcode{\#include} and \tcode{import} does not result in conflicting attachments\iref{basic.link}. \end{note} \recommended Implementations should ensure such attachments do not preclude further evolution or decomposition of the standard library modules. \pnum A declaration in the standard library denotes the same entity regardless of whether it was made reachable through including a header, importing a header unit, or importing a \Cpp{} library module. \pnum \recommended Implementations should avoid exporting any other declarations from the \Cpp{} library modules. \begin{note} Like all named modules, the \Cpp{} library modules do not make macros visible\iref{module.import}, such as \tcode{assert}\iref{cassert.syn}, \tcode{errno}\iref{cerrno.syn}, \tcode{offsetof}\iref{cstddef.syn}, and \tcode{va_arg}\iref{cstdarg.syn}. \end{note} \rSec3[compliance]{Freestanding implementations} \indextext{implementation!freestanding|(}% \pnum Two kinds of implementations are defined: \indextext{implementation!hosted}% hosted and freestanding\iref{intro.compliance}; the kind of the implementation is \impldef{whether the implementation is hosted or freestanding}. For a hosted implementation, this document describes the set of available headers. \pnum A freestanding implementation has an \impldef{headers for freestanding implementation} set of headers. This set shall include at least the headers shown in \tref{headers.cpp.fs}. \begin{libsumtab}{\Cpp{} headers for freestanding implementations}{headers.cpp.fs} \ref{support.types} & Common definitions & \tcode{} \\ \rowsep \ref{cstdlib.syn} & C standard library & \tcode{} \\ \rowsep \ref{support.limits} & Implementation properties & \tcode{}, \tcode{}, \tcode{}, \\ & & \tcode{} \\ \rowsep \ref{cstdint.syn} & Integer types & \tcode{} \\ \rowsep \ref{support.dynamic} & Dynamic memory management & \tcode{} \\ \rowsep \ref{support.rtti} & Type identification & \tcode{} \\ \rowsep \ref{support.srcloc} & Source location & \tcode{} \\ \rowsep \ref{support.exception} & Exception handling & \tcode{} \\ \rowsep \ref{support.contract} & Contract-violation handling & \tcode{} \\ \rowsep \ref{support.initlist} & Initializer lists & \tcode{} \\ \rowsep \ref{cmp} & Comparisons & \tcode{} \\ \rowsep \ref{support.coroutine} & Coroutines support & \tcode{} \\ \rowsep \ref{support.runtime} & Other runtime support & \tcode{} \\ \rowsep \ref{concepts} & Concepts library & \tcode{} \\ \rowsep \ref{errno} & Error numbers & \tcode{} \\ \rowsep \ref{syserr} & System error support & \tcode{} \\ \rowsep \ref{debugging} & Debugging & \tcode{} \\ \rowsep \ref{memory} & Memory & \tcode{} \\ \rowsep \ref{type.traits} & Type traits & \tcode{} \\ \rowsep \ref{ratio} & Compile-time rational arithmetic & \tcode{} \\ \rowsep \ref{utility} & Utility components & \tcode{} \\ \rowsep \ref{tuple} & Tuples & \tcode{} \\ \rowsep \ref{optional} & Optional objects & \tcode{} \\ \rowsep \ref{variant} & Variants & \tcode{} \\ \rowsep \ref{expected} & Expected objects & \tcode{} \\ \rowsep \ref{function.objects} & Function objects & \tcode{} \\ \rowsep \ref{bit} & Bit manipulation & \tcode{} \\ \rowsep \ref{stdbit.h.syn} & C-compatible bit manipulation & \tcode{} \\ \rowsep \ref{array} & Class template \tcode{array} & \tcode{} \\ \rowsep \ref{inplace.vector} & Class template \tcode{inplace_vector} & \tcode{} \\ \rowsep \ref{views.contiguous} & Contiguous access & \tcode{} \\ \rowsep \ref{views.multidim} & Multidimensional access & \tcode{} \\ \rowsep \ref{iterators} & Iterators library & \tcode{} \\ \rowsep \ref{ranges} & Ranges library & \tcode{} \\ \rowsep \ref{algorithms} & Algorithms library & \tcode{}, \tcode{} \\ \rowsep \ref{execpol} & Execution policies & \tcode{} \\ \rowsep \ref{string.view} & String view classes & \tcode{} \\ \rowsep \ref{string.classes} & String classes & \tcode{} \\ \rowsep \ref{c.strings} & Null-terminated sequence utilities & \tcode{}, \tcode{} \\ \rowsep \ref{charconv} & Primitive numeric conversions & \tcode{} \\ \rowsep \ref{rand} & Random number generation & \tcode{} \\ \rowsep \ref{c.math} & Mathematical functions for floating-point types & \tcode{} \\ \rowsep \ref{atomics} & Atomics & \tcode{} \\ \rowsep \end{libsumtab} \pnum For each of the headers listed in \tref{headers.cpp.fs}, a freestanding implementation provides at least the freestanding items\iref{freestanding.item} declared in the header. \pnum The \defnadj{hosted}{library facilities} are the set of facilities described in this document that are required for hosted implementations, but not required for freestanding implementations. A freestanding implementation provides a (possibly empty) implementation-defined subset of the hosted library facilities. Unless otherwise specified, the requirements on each declaration, entity, and macro provided in this way are the same as the corresponding requirements for a hosted implementation, except that not all of the members of the namespaces are required to be present. \pnum A freestanding implementation provides deleted definitions\iref{dcl.fct.def.delete} for a (possibly empty) implementation-defined subset of the namespace-scope functions and function templates from the hosted library facilities. \begin{note} An implementation can provide a deleted definition so that the result of overload resolution does not silently change when migrating a program from a freestanding implementation to a hosted implementation. \end{note} \indextext{implementation!freestanding|)}% \rSec2[using]{Using the library} \rSec3[using.overview]{Overview} \pnum Subclause \ref{using} describes how a \Cpp{} program gains access to the facilities of the \Cpp{} standard library. \ref{using.headers} describes effects during translation phase 4, while~\ref{using.linkage} describes effects during phase 8\iref{lex.phases}. \rSec3[using.headers]{Headers} \pnum The entities in the \Cpp{} standard library are defined in headers, whose contents are made available to a translation unit when it contains the appropriate \indextext{unit!translation}% \indextext{\idxcode{\#include}}% \tcode{\#include} preprocessing directive\iref{cpp.include} or the appropriate \indextext{\idxcode{import}}% \tcode{import} declaration\iref{module.import}. \indextext{source file} \pnum A translation unit may include library headers in any order\iref{lex.separate}. \indextext{unit!translation}% Each may be included more than once, with no effect different from being included exactly once, except that the effect of including either \libheaderref{cassert} or \libheaderrefx{assert.h}{support.c.headers} depends each time on the lexically current definition of \indextext{\idxcode{NDEBUG}}% \indexlibraryglobal{NDEBUG}% \tcode{NDEBUG}. \begin{footnote} This is the same as the C standard library. \end{footnote} \pnum A translation unit shall include a header only outside of any \indextext{unit!translation}% declaration or definition and, in the case of a module unit, only in its \grammarterm{global-module-fragment}, and shall include the header or import the corresponding header unit lexically before the first reference in that translation unit to any of the entities declared in that header. No diagnostic is required. \rSec3[using.linkage]{Linkage} \pnum Entities in the \Cpp{} standard library have external linkage\iref{basic.link}. Unless otherwise specified, objects and functions have the default \tcode{extern "C++"} linkage\iref{dcl.link}. \pnum \indextext{library!C standard}% Whether a name from the C standard library declared with external linkage has \indextext{linkage!external}% \indextext{header!C library}% \indextext{\idxcode{extern ""C""}}% \tcode{extern "C"} or \indextext{\idxcode{extern ""C++""}}% \tcode{extern "C++"} linkage is \impldef{linkage of names from C standard library}. It is recommended that an implementation use \tcode{extern "C++"} linkage for this purpose. \begin{footnote} The only reliable way to declare an object or function signature from the C standard library is by including the header that declares it, notwithstanding the latitude granted in \IsoC{}, 7.1.4. \end{footnote} \pnum Objects and functions defined in the library and required by a \Cpp{} program are included in the program prior to program startup. \indextext{startup!program}% \pnum See also replacement functions\iref{replacement.functions}, runtime changes\iref{handler.functions}. \rSec2[utility.requirements]{Requirements on types and expressions} \rSec3[utility.requirements.general]{General} \pnum \ref{utility.arg.requirements} describes requirements on types and expressions used to instantiate templates defined in the \Cpp{} standard library. \ref{swappable.requirements} describes the requirements on swappable types and swappable expressions. \ref{nullablepointer.requirements} describes the requirements on pointer-like types that support null values. \ref{hash.requirements} describes the requirements on hash function objects. \ref{allocator.requirements} describes the requirements on storage allocators. \rSec3[utility.arg.requirements]{Template argument requirements} \pnum The template definitions in the \Cpp{} standard library refer to various named requirements whose details are set out in Tables~\ref{tab:cpp17.equalitycomparable}--\ref{tab:cpp17.destructible}. In these tables, \begin{itemize} \item \tcode{T} denotes an object or reference type to be supplied by a \Cpp{} program instantiating a template, \item \tcode{a}, \tcode{b}, and \tcode{c} denote values of type (possibly const) \tcode{T}, \item \tcode{s} and \tcode{t} denote modifiable lvalues of type \tcode{T}, \item \tcode{u} denotes an identifier, \item \tcode{rv} denotes an rvalue of type \tcode{T}, and \item \tcode{v} denotes an lvalue of type (possibly const) \tcode{T} or an rvalue of type \tcode{const T}. \end{itemize} \begin{oldconcepttable}{EqualityComparable}{}{cpp17.equalitycomparable} {x{1in}x{1in}p{3in}} \topline \hdstyle{Expression} & \hdstyle{Return type} & \rhdr{Requirement} \\ \capsep \tcode{a == b} & \tcode{decltype(a == b)} models \exposconceptx{boolean-testa\-ble}{boolean-testable} & \tcode{==} is an equivalence relation, that is, it has the following properties: \begin{itemize} \item For all \tcode{a}, \tcode{a == a}. \item If \tcode{a == b}, then \tcode{b == a}. \item If \tcode{a == b} and \tcode{b == c}, then \tcode{a == c}. \end{itemize} \\ \end{oldconcepttable} \begin{oldconcepttable}{LessThanComparable}{}{cpp17.lessthancomparable} {x{1in}x{1in}p{3in}} \topline \hdstyle{Expression} & \hdstyle{Return type} & \hdstyle{Requirement} \\ \capsep \tcode{a < b} & \tcode{decltype(a < b)} models \exposconceptx{boolean-testa\-ble}{boolean-testable} & \tcode{<} is a strict weak ordering relation\iref{alg.sorting} \\ \end{oldconcepttable} \begin{oldconcepttable}{DefaultConstructible}{}{cpp17.defaultconstructible} {x{2.15in}p{3in}} \topline \hdstyle{Expression} & \hdstyle{Post-condition} \\ \capsep \tcode{T t;} & object \tcode{t} is default-initialized \\ \rowsep \tcode{T u\{\};} & object \tcode{u} is value-initialized or aggregate-initialized \\ \rowsep \tcode{T()}\br\tcode{T\{\}} & an object of type \tcode{T} is value-initialized or aggregate-initialized \\ \end{oldconcepttable} \begin{oldconcepttable}{MoveConstructible}{}{cpp17.moveconstructible} {p{1in}p{4.15in}} \topline \hdstyle{Expression} & \hdstyle{Post-condition} \\ \capsep \tcode{T u = rv;} & \tcode{u} is equivalent to the value of \tcode{rv} before the construction\\ \rowsep \tcode{T(rv)} & \tcode{T(rv)} is equivalent to the value of \tcode{rv} before the construction \\ \rowsep \multicolumn{2}{|p{5.3in}|}{ \tcode{rv}'s state is unspecified \begin{tailnote} \tcode{rv} must still meet the requirements of the library component that is using it. The operations listed in those requirements must work as specified whether \tcode{rv} has been moved from or not. \end{tailnote} }\\ \end{oldconcepttable} \begin{oldconcepttable}{CopyConstructible}{ (in addition to \oldconcept{MoveConstructible})}{cpp17.copyconstructible} {p{1in}p{4.15in}} \topline \hdstyle{Expression} & \hdstyle{Post-condition} \\ \capsep \tcode{T u = v;} & the value of \tcode{v} is unchanged and is equivalent to \tcode{ u}\\ \rowsep \tcode{T(v)} & the value of \tcode{v} is unchanged and is equivalent to \tcode{T(v)} \\ \end{oldconcepttable} \begin{oldconcepttable}{MoveAssignable}{}{cpp17.moveassignable} {p{1in}p{1in}p{1in}p{1.9in}} \topline \hdstyle{Expression} & \hdstyle{Return type} & \hdstyle{Return value} & \hdstyle{Post-condition} \\ \capsep \tcode{t = rv} & \tcode{T\&} & \tcode{t} & If \tcode{t} and \tcode{rv} do not refer to the same object, \tcode{t} is equivalent to the value of \tcode{rv} before the assignment\\ \rowsep \multicolumn{4}{|p{5.3in}|}{ \tcode{rv}'s state is unspecified. \begin{tailnote} \tcode{rv} must still meet the requirements of the library component that is using it, whether or not \tcode{t} and \tcode{rv} refer to the same object. The operations listed in those requirements must work as specified whether \tcode{rv} has been moved from or not. \end{tailnote} }\\ \end{oldconcepttable} \begin{oldconcepttable}{CopyAssignable}{ (in addition to \oldconcept{MoveAssignable})}{cpp17.copyassignable} {p{1in}p{1in}p{1in}p{1.9in}} \topline \hdstyle{Expression} & \hdstyle{Return type} & \hdstyle{Return value} & \hdstyle{Post-condition} \\ \capsep \tcode{t = v} & \tcode{T\&} & \tcode{t} & \tcode{t} is equivalent to \tcode{v}, the value of \tcode{v} is unchanged\\ \end{oldconcepttable} \begin{oldconcepttable}{Destructible}{}{cpp17.destructible} {p{1in}p{4.15in}} \topline \hdstyle{Expression} & \hdstyle{Post-condition} \\ \capsep \tcode{a.\~T()} & No exception is propagated. \\ \rowsep \multicolumn{2}{|l|}{ \begin{tailnote} Array types and non-object types are not \oldconcept{Destructible}. \end{tailnote} } \\ \end{oldconcepttable} \rSec3[swappable.requirements]{Swappable requirements} \pnum This subclause provides definitions for swappable types and expressions. In these definitions, let \tcode{t} denote an expression of type \tcode{T}, and let \tcode{u} denote an expression of type \tcode{U}. \pnum An object \tcode{t} is \defn{swappable with} an object \tcode{u} if and only if \begin{itemize} \item the expressions \tcode{swap(t, u)} and \tcode{swap(u, t)} are valid when evaluated in the context described below, and \item these expressions have the following effects: \begin{itemize} \item the object referred to by \tcode{t} has the value originally held by \tcode{u} and \item the object referred to by \tcode{u} has the value originally held by \tcode{t}. \end{itemize} \end{itemize} \pnum The context in which \tcode{swap(t, u)} and \tcode{swap(u, t)} are evaluated shall ensure that a binary non-member function named ``swap'' is selected via overload resolution\iref{over.match} on a candidate set that includes: \begin{itemize} \item the two \tcode{swap} function templates defined in \libheaderref{utility} and \item the lookup set produced by argument-dependent lookup\iref{basic.lookup.argdep}. \end{itemize} \begin{note} If \tcode{T} and \tcode{U} are both fundamental types or arrays of fundamental types and the declarations from the header \libheader{utility} are in scope, the overall lookup set described above is equivalent to that of the qualified name lookup applied to the expression \tcode{std::swap(t, u)} or \tcode{std::swap(u, t)} as appropriate. \end{note} \begin{note} It is unspecified whether a library component that has a swappable requirement includes the header \libheader{utility} to ensure an appropriate evaluation context. \end{note} \pnum An rvalue or lvalue \tcode{t} is \defn{swappable} if and only if \tcode{t} is swappable with any rvalue or lvalue, respectively, of type \tcode{T}. \pnum A type \tcode{X} meets the \defnoldconcept{Swappable} requirements if lvalues of type \tcode{X} are swappable. \pnum A type \tcode{X} meeting any of the iterator requirements\iref{iterator.requirements} meets the \defnoldconcept{ValueSwappable} requirements if, for any dereferenceable object \tcode{x} of type \tcode{X}, \tcode{*x} is swappable. \pnum \begin{example} User code can ensure that the evaluation of \tcode{swap} calls is performed in an appropriate context under the various conditions as follows: \begin{codeblock} #include #include // Preconditions: \tcode{std::forward(t)} is swappable with \tcode{std::forward(u)}. template void value_swap(T&& t, U&& u) { using std::swap; swap(std::forward(t), std::forward(u)); // OK, uses ``swappable with'' conditions // for rvalues and lvalues } // Preconditions: \tcode{T} meets the \oldconcept{Swappable} requirements. template void lv_swap(T& t1, T& t2) { using std::swap; swap(t1, t2); // OK, uses swappable conditions for lvalues of type \tcode{T} } namespace N { struct A { int m; }; struct Proxy { A* a; }; Proxy proxy(A& a) { return Proxy{ &a }; } void swap(A& x, Proxy p) { std::swap(x.m, p.a->m); // OK, uses context equivalent to swappable // conditions for fundamental types } void swap(Proxy p, A& x) { swap(x, p); } // satisfy symmetry constraint } int main() { int i = 1, j = 2; lv_swap(i, j); assert(i == 2 && j == 1); N::A a1 = { 5 }, a2 = { -5 }; value_swap(a1, proxy(a2)); assert(a1.m == -5 && a2.m == 5); } \end{codeblock} \end{example} \rSec3[nullablepointer.requirements]{\oldconcept{NullablePointer} requirements} \pnum A \oldconcept{NullablePointer} type is a pointer-like type that supports null values. A type \tcode{P} meets the \oldconcept{\-Nullable\-Pointer} requirements if \begin{itemize} \item \tcode{P} meets the \oldconcept{EqualityComparable}, \oldconcept{DefaultConstructible}, \oldconcept{CopyConstructible}, \oldconcept{\-Copy\-Assign\-able}, \oldconcept{Swappable}, and \oldconcept{Destructible} requirements, \item the expressions shown in \tref{cpp17.nullablepointer} are valid and have the indicated semantics, and \item \tcode{P} meets all the other requirements of this subclause. \end{itemize} \pnum A value-initialized object of type \tcode{P} produces the null value of the type. The null value shall be equivalent only to itself. A default-initialized object of type \tcode{P} may have an indeterminate or erroneous value. \begin{note} Operations involving indeterminate values can cause undefined behavior, and operations involving erroneous values can cause erroneous behavior\iref{basic.indet}. \end{note} \pnum An object \tcode{p} of type \tcode{P} can be contextually converted to \tcode{bool}\iref{conv}. The effect shall be as if \tcode{p != nullptr} had been evaluated in place of \tcode{p}. \pnum No operation which is part of the \oldconcept{NullablePointer} requirements shall exit via an exception. \pnum In \tref{cpp17.nullablepointer}, \tcode{u} denotes an identifier, \tcode{t} denotes a non-\keyword{const} lvalue of type \tcode{P}, \tcode{a} and \tcode{b} denote values of type (possibly const) \tcode{P}, and \tcode{np} denotes a value of type (possibly const) \tcode{std::nullptr_t}. \begin{oldconcepttable}{NullablePointer}{}{cpp17.nullablepointer} {lx{2in}l} \topline \lhdr{Expression} & \chdr{Return type} & \rhdr{Operational semantics} \\ \capsep \tcode{P u(np);}\br & & \ensures \tcode{u == nullptr} \\ \tcode{P u = np;} & & \\ \rowsep \tcode{P(np)} & & \ensures \tcode{P(np) == nullptr} \\ \rowsep \tcode{t = np} & \tcode{P\&} & \ensures \tcode{t == nullptr} \\ \rowsep \tcode{a != b} & \tcode{decltype(a != b)} models \exposconcept{boolean-testable} & \tcode{!(a == b)} \\ \rowsep \tcode{a == np} & \tcode{decltype(a == np)} and \tcode{decltype(np == a)} each model \exposconcept{boolean-testable} & \tcode{a == P()} \\ \tcode{np == a} & & \\ \rowsep \tcode{a != np} & \tcode{decltype(a != np)} and \tcode{decltype(np != a)} each model \exposconcept{boolean-testable} & \tcode{!(a == np)} \\ \tcode{np != a} & & \\ \end{oldconcepttable} \rSec3[hash.requirements]{\oldconcept{Hash} requirements} \pnum A type \tcode{H} meets the \defnoldconcept{Hash} requirements if \begin{itemize} \item it is a function object type\iref{function.objects}, \item it meets the \oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible}) and \oldconcept{Destructible} (\tref{cpp17.destructible}) requirements, and \item the expressions shown in \tref{cpp17.hash} are valid and have the indicated semantics. \end{itemize} \pnum Given \tcode{Key} is an argument type for function objects of type \tcode{H}, in \tref{cpp17.hash} \tcode{h} is a value of type (possibly const) \tcode{H}, \tcode{u} is an lvalue of type \tcode{Key}, and \tcode{k} is a value of a type convertible to (possibly const) \tcode{Key}. \begin{oldconcepttable}{Hash}{}{cpp17.hash} {llp{.55\hsize}} \topline \lhdr{Expression} & \chdr{Return type} & \rhdr{Requirement} \\ \capsep \tcode{h(k)} & \tcode{size_t} & The value returned shall depend only on the argument \tcode{k} for the duration of the program. \begin{note} Thus all evaluations of the expression \tcode{h(k)} with the same value for \tcode{k} yield the same result for a given execution of the program. \end{note} For two different values \tcode{t1} and \tcode{t2}, the probability that \tcode{h(t1)} and \tcode{h(t2)} compare equal should be very small, approaching \tcode{1.0 / numeric_limits::max()}. \\ \rowsep \tcode{h(u)} & \tcode{size_t} & Shall not modify \tcode{u}. \\ \end{oldconcepttable} \rSec3[allocator.requirements]{\oldconcept{Allocator} requirements} \rSec4[allocator.requirements.general]{General} \indextext{\idxoldconcept{Allocator}}% \pnum The library describes a standard set of requirements for \term{allocators}, which are class-type objects that encapsulate the information about an allocation model. This information includes the knowledge of pointer types, the type of their difference, the type of the size of objects in this allocation model, as well as the memory allocation and deallocation primitives for it. All of the string types\iref{strings}, containers\iref{containers} (except \tcode{array} and \tcode{inplace_vector}), string buffers and string streams\iref{input.output}, and \tcode{match_results}\iref{re} are parameterized in terms of allocators. \pnum In \ref{allocator.requirements}, \begin{itemize} \item \tcode{T}, \tcode{U}, \tcode{C} denote any \cv-unqualified object type\iref{term.object.type}, \item \tcode{X} denotes an allocator class for type \tcode{T}, \item \tcode{Y} denotes the corresponding allocator class for type \tcode{U}, \item \tcode{XX} denotes the type \tcode{allocator_traits}, \item \tcode{YY} denotes the type \tcode{allocator_traits}, \item \tcode{a}, \tcode{a1}, \tcode{a2} denote lvalues of type \tcode{X}, \item \tcode{u} denotes the name of a variable being declared, \item \tcode{b} denotes a value of type \tcode{Y}, \item \tcode{c} denotes a pointer of type \tcode{C*} through which indirection is valid, \item \tcode{p} denotes a value of type \tcode{XX::pointer} obtained by calling \tcode{a1.allocate}, where \tcode{a1 == a}, \item \tcode{q} denotes a value of type \tcode{XX::const_pointer} obtained by conversion from a value \tcode{p}, \item \tcode{r} denotes a value of type \tcode{T\&} obtained by the expression \tcode{*p}, \item \tcode{w} denotes a value of type \tcode{XX::void_pointer} obtained by conversion from a value \tcode{p}, \item \tcode{x} denotes a value of type \tcode{XX::const_void_pointer} obtained by conversion from a value \tcode{q} or a value \tcode{w}, \item \tcode{y} denotes a value of type \tcode{XX::const_void_pointer} obtained by conversion from a result value of \tcode{YY::allocate}, or else a value of type (possibly const) \tcode{std::nullptr_t}, \item \tcode{n} denotes a value of type \tcode{XX::size_type}, \item \tcode{Args} denotes a template parameter pack, and \item \tcode{args} denotes a function parameter pack with the pattern \tcode{Args\&\&}. \end{itemize} \pnum The class template \tcode{allocator_traits}\iref{allocator.traits} supplies a uniform interface to all allocator types. This subclause describes the requirements on allocator types and thus on types used to instantiate \tcode{allocator_traits}. A requirement is optional if a default for a given type or expression is specified. Within the standard library \tcode{allocator_traits} template, an optional requirement that is not supplied by an allocator is replaced by the specified default type or expression. \begin{note} There are no program-defined specializations of \tcode{allocator_traits}. \end{note} \begin{itemdecl} typename X::pointer \end{itemdecl} \begin{itemdescr} \pnum \remarks Default: \tcode{T*} \end{itemdescr} \begin{itemdecl} typename X::const_pointer \end{itemdecl} \begin{itemdescr} \pnum \mandates \tcode{XX::pointer} is convertible to \tcode{XX::const_pointer}. \pnum \remarks Default: \tcode{pointer_traits::rebind} \end{itemdescr} \begin{itemdecl} typename X::void_pointer typename Y::void_pointer \end{itemdecl} \begin{itemdescr} \pnum \mandates \tcode{XX::pointer} is convertible to \tcode{XX::void_pointer}. \tcode{XX::void_pointer} and \tcode{YY::void_pointer} are the same type. \pnum \remarks Default: \tcode{pointer_traits::rebind} \end{itemdescr} \begin{itemdecl} typename X::const_void_pointer typename Y::const_void_pointer \end{itemdecl} \begin{itemdescr} \pnum \mandates \tcode{XX::pointer}, \tcode{XX::const_pointer}, and \tcode{XX::void_pointer} are convertible to \tcode{XX::const_void_pointer}. \tcode{XX::const_void_pointer} and \tcode{YY::const_void_pointer} are the same type. \pnum \remarks Default: \tcode{pointer_traits::rebind} \end{itemdescr} \begin{itemdecl} typename X::value_type \end{itemdecl} \begin{itemdescr} \pnum \result Identical to \tcode{T}. \end{itemdescr} \begin{itemdecl} typename X::size_type \end{itemdecl} \begin{itemdescr} \pnum \result An unsigned integer type that can represent the size of the largest object in the allocation model. \pnum \remarks Default: \tcode{make_unsigned_t} \end{itemdescr} \begin{itemdecl} typename X::difference_type \end{itemdecl} \begin{itemdescr} \pnum \result A signed integer type that can represent the difference between any two pointers in the allocation model. \pnum \remarks Default: \tcode{pointer_traits::difference_type} \end{itemdescr} \begin{itemdecl} typename X::rebind::other \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{Y} \pnum \ensures For all \tcode{U} (including \tcode{T}), \tcode{YY::rebind_alloc} is \tcode{X}. \pnum \remarks If \tcode{Allocator} is a class template specialization of the form \tcode{SomeAllocator}, where \tcode{Args} is zero or more type arguments, and \tcode{Allocator} does not supply a \tcode{rebind} member template, the standard \tcode{allocator_traits} template uses \tcode{SomeAllocator} in place of \tcode{Allocator::re\-bind::other} by default. For allocator types that are not template specializations of the above form, no default is provided. \pnum \begin{note} The member class template \tcode{rebind} of \tcode{X} is effectively a typedef template. In general, if the name \tcode{Allocator} is bound to \tcode{SomeAllocator}, then \tcode{Allocator::rebind::other} is the same type as \tcode{SomeAllocator}, where \tcode{SomeAllocator::value_type} is \tcode{T} and \tcode{SomeAllocator::value_type} is \tcode{U}. \end{note} \end{itemdescr} \begin{itemdecl} *p \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{T\&} \end{itemdescr} \begin{itemdecl} *q \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{const T\&} \pnum \ensures \tcode{*q} refers to the same object as \tcode{*p}. \end{itemdescr} \begin{itemdecl} p->m \end{itemdecl} \begin{itemdescr} \pnum \result Type of \tcode{T::m}. \pnum \expects \tcode{(*p).m} is well-defined. \pnum \effects Equivalent to \tcode{(*p).m}. \end{itemdescr} \begin{itemdecl} q->m \end{itemdecl} \begin{itemdescr} \pnum \result Type of \tcode{T::m}. \pnum \expects \tcode{(*q).m} is well-defined. \pnum \effects Equivalent to \tcode{(*q).m}. \end{itemdescr} \begin{itemdecl} static_cast(w) \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{XX::pointer} \pnum \ensures \tcode{static_cast(w) == p}. \end{itemdescr} \begin{itemdecl} static_cast(x) \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{XX::const_pointer} \pnum \ensures \tcode{static_cast(x) == q}. \end{itemdescr} \begin{itemdecl} pointer_traits::pointer_to(r) \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{XX::pointer} \pnum \ensures Same as \tcode{p}. \end{itemdescr} \begin{itemdecl} a.allocate(n) \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{XX::pointer} \pnum \effects Memory is allocated for an array of \tcode{n} \tcode{T} and such an object is created but array elements are not constructed. \begin{example} When reusing storage denoted by some pointer value \tcode{p}, \tcode{launder(reinterpret_cast(new (p) byte[n * sizeof(T)]))} can be used to implicitly create a suitable array object and obtain a pointer to it. \end{example} \pnum \throws \tcode{allocate} may throw an appropriate exception. \pnum \begin{note} It is intended that \tcode{a.allocate} be an efficient means of allocating a single object of type \tcode{T}, even when \tcode{sizeof(T)} is small. That is, there is no need for a container to maintain its own free list. \end{note} \pnum \remarks If \tcode{n == 0}, the return value is unspecified. \end{itemdescr} \begin{itemdecl} a.allocate(n, y) \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{XX::pointer} \pnum \effects Same as \tcode{a.allocate(n)}. The use of \tcode{y} is unspecified, but it is intended as an aid to locality. \pnum \remarks Default: \tcode{a.allocate(n)} \end{itemdescr} \begin{itemdecl} a.allocate_at_least(n) \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{allocation_result} \pnum \returns \tcode{allocation_result\{ptr, count\}} where \tcode{ptr} is memory allocated for an array of \tcode{count} \tcode{T} and such an object is created but array elements are not constructed, such that $\tcode{count} \geq \tcode{n}$. If \tcode{n == 0}, the return value is unspecified. \pnum \throws \tcode{allocate_at_least} may throw an appropriate exception. \pnum \remarks Default: \tcode{\{a.allocate(n), n\}}. \end{itemdescr} \begin{itemdecl} a.deallocate(p, n) \end{itemdecl} \begin{itemdescr} \pnum \result (not used) \pnum \expects \begin{itemize} \item If \tcode{p} is memory that was obtained by a call to \tcode{a.allocate_at_least}, let \tcode{ret} be the value returned and \tcode{req} be the value passed as the first argument of that call. \tcode{p} is equal to \tcode{ret.ptr} and \tcode{n} is a value such that $\tcode{req} \leq \tcode{n} \leq \tcode{ret.count}$. \item Otherwise, \tcode{p} is a pointer value obtained from \tcode{allocate}. \tcode{n} equals the value passed as the first argument to the invocation of \tcode{allocate} which returned \tcode{p}. \end{itemize} \tcode{p} has not been invalidated by an intervening call to \tcode{deallocate}. \pnum \throws Nothing. \end{itemdescr} \begin{itemdecl} a.max_size() \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{XX::size_type} \pnum \returns The largest value \tcode{n} that can meaningfully be passed to \tcode{a.allocate(n)}. \pnum \remarks Default: \tcode{numeric_limits::max() / sizeof(value_type)} \end{itemdescr} \begin{itemdecl} a1 == a2 \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{bool} \pnum \returns \tcode{true} only if storage allocated from each can be deallocated via the other. \pnum \throws Nothing. \pnum \remarks \tcode{operator==} shall be reflexive, symmetric, and transitive. \end{itemdescr} \begin{itemdecl} a1 != a2 \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{bool} \pnum \returns \tcode{!(a1 == a2)}. \end{itemdescr} \begin{itemdecl} a == b \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{bool} \pnum \returns \tcode{a == YY::rebind_alloc(b)}. \end{itemdescr} \begin{itemdecl} a != b \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{bool} \pnum \returns \tcode{!(a == b)}. \end{itemdescr} \begin{itemdecl} X u(a); X u = a; \end{itemdecl} \begin{itemdescr} \pnum \ensures \tcode{u == a} \pnum \throws Nothing. \end{itemdescr} \begin{itemdecl} X u(b); \end{itemdecl} \begin{itemdescr} \pnum \ensures \tcode{Y(u) == b} and \tcode{u == X(b)}. \pnum \throws Nothing. \end{itemdescr} \begin{itemdecl} X u(std::move(a)); X u = std::move(a); \end{itemdecl} \begin{itemdescr} \pnum \ensures The value of \tcode{a} is unchanged and is equal to \tcode{u}. \pnum \throws Nothing. \end{itemdescr} \begin{itemdecl} X u(std::move(b)); \end{itemdecl} \begin{itemdescr} \pnum \ensures \tcode{u} is equal to the prior value of \tcode{X(b)}. \pnum \throws Nothing. \end{itemdescr} \begin{itemdecl} a.construct(c, args...) \end{itemdecl} \begin{itemdescr} \pnum \result (not used) \pnum \effects Constructs an object of type \tcode{C} at \tcode{c}. \pnum \remarks Default: \tcode{construct_at(c, std::forward(args)...)} \end{itemdescr} \begin{itemdecl} a.destroy(c) \end{itemdecl} \begin{itemdescr} \pnum \result (not used) \pnum \effects Destroys the object at \tcode{c}. \pnum \remarks Default: \tcode{destroy_at(c)} \end{itemdescr} \begin{itemdecl} a.select_on_container_copy_construction() \end{itemdecl} \begin{itemdescr} \pnum \result \tcode{X} \pnum \returns Typically returns either \tcode{a} or \tcode{X()}. \pnum \remarks Default: \tcode{return a;} \end{itemdescr} \begin{itemdecl} typename X::propagate_on_container_copy_assignment \end{itemdecl} \begin{itemdescr} \pnum \result Identical to or derived from \tcode{true_type} or \tcode{false_type}. \pnum \returns \tcode{true_type} only if an allocator of type \tcode{X} should be copied when the client container is copy-assigned; if so, \tcode{X} shall meet the \oldconcept{CopyAssignable} requirements (\tref{cpp17.copyassignable}) and the copy operation shall not throw exceptions. \pnum \remarks Default: \tcode{false_type} \end{itemdescr} \begin{itemdecl} typename X::propagate_on_container_move_assignment \end{itemdecl} \begin{itemdescr} \pnum \result Identical to or derived from \tcode{true_type} or \tcode{false_type}. \pnum \returns \tcode{true_type} only if an allocator of type \tcode{X} should be moved when the client container is move-assigned; if so, \tcode{X} shall meet the \oldconcept{MoveAssignable} requirements (\tref{cpp17.moveassignable}) and the move operation shall not throw exceptions. \pnum \remarks Default: \tcode{false_type} \end{itemdescr} \begin{itemdecl} typename X::propagate_on_container_swap \end{itemdecl} \begin{itemdescr} \pnum \result Identical to or derived from \tcode{true_type} or \tcode{false_type}. \pnum \returns \tcode{true_type} only if an allocator of type \tcode{X} should be swapped when the client container is swapped; if so, \tcode{X} shall meet the \oldconcept{Swappable} requirements\iref{swappable.requirements} and the \tcode{swap} operation shall not throw exceptions. \pnum \remarks Default: \tcode{false_type} \end{itemdescr} \begin{itemdecl} typename X::is_always_equal \end{itemdecl} \begin{itemdescr} \pnum \result Identical to or derived from \tcode{true_type} or \tcode{false_type}. \pnum \returns \tcode{true_type} only if the expression \tcode{a1 == a2} is guaranteed to be \tcode{true} for any two (possibly const) values \tcode{a1}, \tcode{a2} of type \tcode{X}. \pnum \remarks Default: \tcode{is_empty::type} \end{itemdescr} \pnum An allocator type \tcode{X} shall meet the \oldconcept{CopyConstructible} requirements (\tref{cpp17.copyconstructible}). The \tcode{XX::pointer}, \tcode{XX::const_pointer}, \tcode{XX::void_pointer}, and \tcode{XX::const_void_pointer} types shall meet the \oldconcept{Nullable\-Pointer} requirements (\tref{cpp17.nullablepointer}). No constructor, comparison operator function, copy operation, move operation, or swap operation on these pointer types shall exit via an exception. \tcode{XX::pointer} and \tcode{XX::const_pointer} shall also meet the requirements for a \oldconcept{RandomAccessIterator}\iref{random.access.iterators} and the additional requirement that, when \tcode{p} and \tcode{(p + n)} are dereferenceable pointer values for some integral value \tcode{n}, \begin{codeblock} addressof(*(p + n)) == addressof(*p) + n \end{codeblock} is \tcode{true}. \pnum Let \tcode{x1} and \tcode{x2} denote objects of (possibly different) types \tcode{XX::void_pointer}, \tcode{XX::const_void_pointer}, \tcode{XX::pointer}, or \tcode{XX::const_pointer}. Then, \tcode{x1} and \tcode{x2} are \defn{equivalently-valued} pointer values, if and only if both \tcode{x1} and \tcode{x2} can be explicitly converted to the two corresponding objects \tcode{px1} and \tcode{px2} of type \tcode{XX::const_pointer}, using a sequence of \keyword{static_cast}s using only these four types, and the expression \tcode{px1 == px2} evaluates to \tcode{true}. \pnum Let \tcode{w1} and \tcode{w2} denote objects of type \tcode{XX::void_pointer}. Then for the expressions \begin{codeblock} w1 == w2 w1 != w2 \end{codeblock} either or both objects may be replaced by an equivalently-valued object of type \tcode{XX::const_void_pointer} with no change in semantics. \pnum Let \tcode{p1} and \tcode{p2} denote objects of type \tcode{XX::pointer}. Then for the expressions \begin{codeblock} p1 == p2 p1 != p2 p1 < p2 p1 <= p2 p1 >= p2 p1 > p2 p1 - p2 \end{codeblock} either or both objects may be replaced by an equivalently-valued object of type \tcode{XX::const_pointer} with no change in semantics. \pnum An allocator may constrain the types on which it can be instantiated and the arguments for which its \tcode{construct} or \tcode{destroy} members may be called. If a type cannot be used with a particular allocator, the allocator class or the call to \tcode{construct} or \tcode{destroy} may fail to instantiate. \pnum If the alignment associated with a specific over-aligned type is not supported by an allocator, instantiation of the allocator for that type may fail. The allocator also may silently ignore the requested alignment. \begin{note} Additionally, the member function \tcode{allocate} for that type can fail by throwing an object of type \tcode{bad_alloc}. \end{note} \pnum \begin{example} The following is an allocator class template supporting the minimal interface that meets the requirements of \ref{allocator.requirements.general}: \begin{codeblock} template struct SimpleAllocator { using value_type = T; SimpleAllocator(@\textit{ctor args}@); template SimpleAllocator(const SimpleAllocator& other); T* allocate(std::size_t n); void deallocate(T* p, std::size_t n); template bool operator==(const SimpleAllocator& rhs) const; }; \end{codeblock} \end{example} \pnum The following exposition-only concept defines the minimal requirements on an Allocator type. \begin{codeblock} namespace std { template concept @\defexposconcept{simple-allocator}@ = requires(Alloc alloc, size_t n) { { *alloc.allocate(n) } -> @\libconcept{same_as}@; { alloc.deallocate(alloc.allocate(n), n) }; } && @\libconcept{copy_constructible}@ && @\libconcept{equality_comparable}@; } \end{codeblock} A type \tcode{Alloc} models \exposconcept{simple-allocator} if it meets the requirements of \ref{allocator.requirements.general}. \rSec4[allocator.requirements.completeness]{Allocator completeness requirements} \pnum If \tcode{X} is an allocator class for type \tcode{T}, \tcode{X} additionally meets the allocator completeness requirements if, whether or not \tcode{T} is a complete type: \begin{itemize} \item \tcode{X} is a complete type, and \item all the member types of \tcode{allocator_traits}\iref{allocator.traits} other than \tcode{value_type} are complete types. \end{itemize} \rSec2[constraints]{Constraints on programs} \rSec3[constraints.overview]{Overview} \pnum Subclause \ref{constraints} describes restrictions on \Cpp{} programs that use the facilities of the \Cpp{} standard library. The following subclauses specify constraints on the program's use of namespaces\iref{namespace.std}, its use of various reserved names\iref{reserved.names}, its use of headers\iref{alt.headers}, its use of standard library classes as base classes\iref{derived.classes}, its definitions of replacement functions\iref{replacement.functions}, and its installation of handler functions during execution\iref{handler.functions}. \rSec3[namespace.constraints]{Namespace use} \rSec4[namespace.std]{Namespace \tcode{std}} \pnum Unless otherwise specified, the behavior of a \Cpp{} program is undefined if it adds declarations or definitions to namespace \tcode{std} or to a namespace within namespace \tcode{std}. \pnum Unless explicitly prohibited, a program may add a template specialization for any standard library class template to namespace \tcode{std} provided that \begin{itemize} \item the added declaration depends on at least one program-defined type, and \item the specialization meets the standard library requirements for the original template. \begin{footnote} Any library code that instantiates other library templates must be prepared to work adequately with any user-supplied specialization that meets the minimum requirements of this document. \end{footnote} \end{itemize} \pnum The behavior of a \Cpp{} program is undefined if it declares an explicit or partial specialization of any standard library variable template, except where explicitly permitted by the specification of that variable template. \begin{note} The requirements on an explicit or partial specialization are stated by each variable template that grants such permission. \end{note} \pnum The behavior of a \Cpp{} program is undefined if it declares \begin{itemize} \item an explicit specialization of any member function of a standard library class template, or \item an explicit specialization of any member function template of a standard library class or class template, or \item an explicit or partial specialization of any member class template of a standard library class or class template, or \item a deduction guide for any standard library class template. \end{itemize} \pnum A program may explicitly instantiate a class template defined in the standard library only if the declaration \begin{itemize} \item depends on the name of at least one program-defined type, and \item the instantiation meets the standard library requirements for the original template. \end{itemize} \pnum Let \tcode{\placeholder{F}} denote a standard library function\iref{global.functions}, a standard library static member function, or a specialization of a standard library function template. Unless \tcode{\placeholder{F}} is designated an \defnadj{addressable}{function}, the behavior of a \Cpp{} program is unspecified (possibly ill-formed) if it explicitly or implicitly attempts to form a pointer to \tcode{\placeholder{F}}. \begin{note} Possible means of forming such pointers include application of the unary \tcode{\&} operator\iref{expr.unary.op}, \tcode{addressof}\iref{specialized.addressof}, or a function-to-pointer standard conversion\iref{conv.func}. \end{note} Moreover, the behavior of a \Cpp{} program is unspecified (possibly ill-formed) if it attempts to form a reference to \tcode{\placeholder{F}} or if it attempts to form a pointer-to-member designating either a standard library non-static member function\iref{member.functions} or a specialization of a standard library member function template. \pnum Let \tcode{\placeholder{F}} denote a standard library function or function template. Unless \tcode{\placeholder{F}} is designated an addressable function, it is unspecified if or how a reflection value designating the associated entity can be formed. For any value \tcode{\placeholder{p}} of type \tcode{meta::info} that represents a reflection of a parameter of \tcode{\placeholder{F}}, it is unspecified if \tcode{has_identifier(\placeholder{p})} returns \tcode{true} or \tcode{false}, and if \tcode{meta::has_identifier(\placeholder{p})} is \tcode{true}, then the \ntmbs{} produced by \tcode{meta::identifier_of(\placeholder{p})} and \tcode{meta::u8identifier_of(\placeholder{p})} is unspecified. %FIXME: Why is this not an example, but a note that begins with "For example"? \begin{note} For example, it is possible that \tcode{std::meta::members_of} will not return reflections of standard library functions that an implementation handles through an extra-linguistic mechanism. \end{note} \pnum Let \tcode{\placeholder{C}} denote a standard library class or class template specialization. It is unspecified if or how a reflection value can be formed to any private member of \tcode{\placeholder{C}}, or what the names of such members may be. \pnum A translation unit shall not declare namespace \tcode{std} to be an inline namespace\iref{namespace.def}. \rSec4[namespace.posix]{Namespace \tcode{posix}} \pnum The behavior of a \Cpp{} program is undefined if it adds declarations or definitions to namespace \tcode{posix} or to a namespace within namespace \tcode{posix} unless otherwise specified. The namespace \tcode{posix} is reserved for use by \IsoPosixUndated{} and other POSIX standards. \rSec4[namespace.future]{Namespaces for future standardization} \pnum Top-level namespaces whose \grammarterm{namespace-name} consists of \tcode{std} followed by one or more \grammarterm{digit}{s}\iref{lex.name} are reserved for future standardization. The behavior of a \Cpp{} program is undefined if it adds declarations or definitions to such a namespace. \begin{example} The top-level namespace \tcode{std2} is reserved for use by future revisions of this International Standard. \end{example} \rSec3[reserved.names]{Reserved names}% \rSec4[reserved.names.general]{General}% \indextext{name!reserved} \pnum The \Cpp{} standard library reserves the following kinds of names: \begin{itemize} \item macros \item global names \item names with external linkage \end{itemize} \pnum If a program declares or defines a name in a context where it is reserved, other than as explicitly allowed by \ref{library}, its behavior is undefined.% \indextext{undefined} \rSec4[zombie.names]{Zombie names}% \indextext{name!zombie}% \indextext{living dead!name of}% \indextext{brains!names that want to eat your}% \pnum In namespace \tcode{std}, the names shown in \tref{zombie.names.std} are reserved for previous standardization: \begin{multicolfloattable}{Zombie names in namespace \tcode{std}}{zombie.names.std} {lll} \indexlibraryzombie{auto_ptr} \tcode{auto_ptr} \\ \indexlibraryzombie{auto_ptr_ref} \tcode{auto_ptr_ref} \\ \indexlibraryzombie{binary_function} \tcode{binary_function} \\ \indexlibraryzombie{binary_negate} \tcode{binary_negate} \\ \indexlibraryzombie{bind1st} \tcode{bind1st} \\ \indexlibraryzombie{bind2nd} \tcode{bind2nd} \\ \indexlibraryzombie{binder1st} \tcode{binder1st} \\ \indexlibraryzombie{binder2nd} \tcode{binder2nd} \\ \indexlibraryzombie{codecvt_mode} \tcode{codecvt_mode} \\ \indexlibraryzombie{codecvt_utf16} \tcode{codecvt_utf16} \\ \indexlibraryzombie{codecvt_utf8} \tcode{codecvt_utf8} \\ \indexlibraryzombie{codecvt_utf8_utf16} \tcode{codecvt_utf8_utf16} \\ \indexlibraryzombie{const_mem_fun1_ref_t} \tcode{const_mem_fun1_ref_t} \\ \indexlibraryzombie{const_mem_fun1_t} \tcode{const_mem_fun1_t} \\ \indexlibraryzombie{const_mem_fun_ref_t} \tcode{const_mem_fun_ref_t} \\ \indexlibraryzombie{const_mem_fun_t} \tcode{const_mem_fun_t} \\ \indexlibraryzombie{consume_header} \tcode{consume_header} \\ \indexlibraryzombie{declare_no_pointers} \tcode{declare_no_pointers} \\ \indexlibraryzombie{declare_reachable} \tcode{declare_reachable} \\ \columnbreak \indexlibraryzombie{generate_header} \tcode{generate_header} \\ \indexlibraryzombie{get_pointer_safety} \tcode{get_pointer_safety} \\ \indexlibraryzombie{get_temporary_buffer} \tcode{get_temporary_buffer} \\ \indexlibraryzombie{get_unexpected} \tcode{get_unexpected} \\ \indexlibraryzombie{gets} \tcode{gets} \\ \indexlibraryzombie{is_literal_type} \tcode{is_literal_type} \\ \indexlibraryzombie{is_literal_type_v} \tcode{is_literal_type_v} \\ \indexlibraryzombie{istrstream} \tcode{istrstream} \\ \indexlibraryzombie{little_endian} \tcode{little_endian} \\ \indexlibraryzombie{mem_fun1_ref_t} \tcode{mem_fun1_ref_t} \\ \indexlibraryzombie{mem_fun1_t} \tcode{mem_fun1_t} \\ \indexlibraryzombie{mem_fun_ref_t} \tcode{mem_fun_ref_t} \\ \indexlibraryzombie{mem_fun_ref} \tcode{mem_fun_ref} \\ \indexlibraryzombie{mem_fun_t} \tcode{mem_fun_t} \\ \indexlibraryzombie{mem_fun} \tcode{mem_fun} \\ \indexlibraryzombie{not1} \tcode{not1} \\ \indexlibraryzombie{not2} \tcode{not2} \\ \indexlibraryzombie{ostrstream} \tcode{ostrstream} \\ \indexlibraryzombie{pointer_safety} \tcode{pointer_safety} \\ \columnbreak \indexlibraryzombie{pointer_to_binary_function} \tcode{pointer_to_binary_function} \\ \indexlibraryzombie{pointer_to_unary_function} \tcode{pointer_to_unary_function} \\ \indexlibraryzombie{ptr_fun} \tcode{ptr_fun} \\ \indexlibraryzombie{random_shuffle} \tcode{random_shuffle} \\ \indexlibraryzombie{raw_storage_iterator} \tcode{raw_storage_iterator} \\ \indexlibraryzombie{result_of} \tcode{result_of} \\ \indexlibraryzombie{result_of_t} \tcode{result_of_t} \\ \indexlibraryzombie{return_temporary_buffer} \tcode{return_temporary_buffer} \\ \indexlibraryzombie{set_unexpected} \tcode{set_unexpected} \\ \indexlibraryzombie{strstream} \tcode{strstream} \\ \indexlibraryzombie{strstreambuf} \tcode{strstreambuf} \\ \indexlibraryzombie{unary_function} \tcode{unary_function} \\ \indexlibraryzombie{unary_negate} \tcode{unary_negate} \\ \indexlibraryzombie{uncaught_exception} \tcode{uncaught_exception} \\ \indexlibraryzombie{undeclare_no_pointers} \tcode{undeclare_no_pointers} \\ \indexlibraryzombie{undeclare_reachable} \tcode{undeclare_reachable} \\ \indexlibraryzombie{unexpected_handler} \tcode{unexpected_handler} \\ \indexlibraryzombie{wbuffer_convert} \tcode{wbuffer_convert} \\ \indexlibraryzombie{wstring_convert} \tcode{wstring_convert} \\ \end{multicolfloattable} \pnum The names shown in \tref{zombie.names.objmacro} are reserved as members for previous standardization, and may not be used as a name for object-like macros in portable code: \begin{multicolfloattable}{Zombie object-like macros}{zombie.names.objmacro} {lll} \indexlibraryzombie{argument_type} \tcode{argument_type} \\ \indexlibraryzombie{first_argument_type} \tcode{first_argument_type} \\ \indexlibraryzombie{io_state} \tcode{io_state} \\ \columnbreak \indexlibraryzombie{op} \tcode{op} \\ \indexlibraryzombie{open_mode} \tcode{open_mode} \\ \indexlibraryzombie{preferred} \tcode{preferred} \\ \columnbreak \indexlibraryzombie{second_argument_type} \tcode{second_argument_type} \\ \indexlibraryzombie{seek_dir} \tcode{seek_dir} \\ \indexlibraryzombie{strict} \tcode{strict} \\ \end{multicolfloattable} \pnum The names shown in \tref{zombie.names.fnmacro} are reserved as member functions for previous standardization, and may not be used as a name for function-like macros in portable code: \begin{multicolfloattable}{Zombie function-like macros}{zombie.names.fnmacro} {llllll} \indexlibraryzombie{converted} \tcode{converted} \\ \columnbreak \indexlibraryzombie{freeze} \tcode{freeze} \\ \columnbreak \indexlibraryzombie{from_bytes} \tcode{from_bytes} \\ \columnbreak \indexlibraryzombie{pcount} \tcode{pcount} \\ \columnbreak \indexlibraryzombie{stossc} \tcode{stossc} \\ \columnbreak \indexlibraryzombie{to_bytes} \tcode{to_bytes} \\ \end{multicolfloattable} \pnum The header names shown in \tref{zombie.names.header} are reserved for previous standardization: \begin{multicolfloattable}{Zombie headers}{zombie.names.header} {lllll} \libnoheader{ccomplex} \\ \libnoheader{ciso646} \\ \columnbreak \libnoheader{codecvt} \\ \libnoheader{cstdalign} \\ \columnbreak \libnoheader{cstdbool} \\ \columnbreak \libnoheader{ctgmath} \\ \columnbreak \libnoheader{strstream} \\ \end{multicolfloattable} \rSec4[macro.names]{Macro names} \pnum \indextext{\idxcode{\#undef}}% \indextext{unit!translation}% A translation unit that includes a standard library header shall not \tcode{\#define} or \tcode{\#undef} names declared in any standard library header. \rSec4[extern.names]{External linkage} \pnum Each name declared as an object with external linkage \indextext{linkage!external}% in a header is reserved to the implementation to designate that library object with external linkage,% \indextext{linkage!external}% \begin{footnote} The list of such reserved names includes \tcode{errno}, declared or defined in \libheaderref{cerrno}. \end{footnote} both in namespace \tcode{std} and in the global namespace. \pnum Each \indextext{function!global}% global function signature declared with \indextext{linkage!external}% external linkage in a header is reserved to the implementation to designate that function signature with \indextext{linkage!external}% external linkage.% \begin{footnote} The list of such reserved function signatures with external linkage includes \indexlibraryglobal{setjmp}% \tcode{setjmp(jmp_buf)}, declared or defined in \libheaderref{csetjmp}, and \indexlibraryglobal{va_end}% \indexlibraryglobal{va_list}% \tcode{va_end(va_list)}, declared or defined in \libheaderref{cstdarg}. \end{footnote} \pnum Each name from the C standard library declared with external linkage \indextext{linkage!external}% is reserved to the implementation for use as a name with \indextext{header!C}% \indextext{\idxcode{extern ""C""}}% \tcode{extern "C"} linkage, both in namespace \tcode{std} and in the global namespace. \pnum Each function signature from the C standard library declared with \indextext{linkage!external}% external linkage is reserved to the implementation for use as a function signature with both \indextext{\idxcode{extern ""C""}}% \tcode{extern "C"} and \indextext{\idxcode{extern ""C++""}}% \tcode{extern "C++"} linkage, \begin{footnote} The function signatures declared in \indextext{Amendment 1}% \libheaderref{cuchar}, \libheaderref{cwchar}, and \libheaderref{cwctype} are always reserved, notwithstanding the restrictions imposed in subclause 4.5.1 of Amendment 1 to the C Standard for these headers. \end{footnote} or as a name of namespace scope in the global namespace. \rSec4[extern.types]{Types} \pnum For each type \tcode{T} from the C standard library, the types \tcode{::T} and \tcode{std::T} are reserved to the implementation and, when declared, \tcode{::T} shall be identical to \tcode{std::T}. \rSec4[usrlit.suffix]{User-defined literal suffixes} \pnum Literal suffix identifiers\iref{over.literal} that do not start with an underscore are reserved for future standardization. Literal suffix identifiers that contain a double underscore \tcode{\unun} \indextext{character!underscore}% are reserved for use by \Cpp{} implementations. \rSec3[alt.headers]{Headers} \pnum If a file with a name equivalent to the derived file name for one of the \Cpp{} standard library headers is not provided as part of the implementation, and a file with that name is placed in any of the standard places for a source file to be included\iref{cpp.include}, the behavior is undefined.% \indextext{source file}% \indextext{undefined} \rSec3[derived.classes]{Derived classes} \pnum Virtual member function signatures defined \indextext{function!virtual member}% for a base class in the \Cpp{} standard \indextext{class!base}% \indextext{library!\Cpp{} standard}% library may be overridden in a derived class defined in the program\iref{class.virtual}. \rSec3[replacement.functions]{Replacement functions} \pnum If a function defined in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} is specified as replaceable\iref{term.replaceable.function}, the description of function semantics apply to both the default version defined by the \Cpp{} standard library and the replacement function defined by the program. \rSec3[handler.functions]{Handler functions} \pnum The \Cpp{} standard library provides a default version of the following handler function\iref{support}: \begin{itemize} \item \tcode{terminate_handler} \indexlibraryglobal{terminate_handler}% \end{itemize} \pnum A \Cpp{} program may install different handler functions during execution, by supplying a pointer to a function defined in the program or the library as an argument to (respectively): \begin{itemize} \item \indexlibraryglobal{set_new_handler}\tcode{set_new_handler} \item \indexlibraryglobal{set_terminate}\tcode{set_terminate} \end{itemize} See also subclauses~\ref{alloc.errors}, Storage allocation errors, and~\ref{support.exception}, Exception handling. \pnum A \Cpp{} program can get a pointer to the current handler function by calling the following functions: \begin{itemize} \item \indexlibraryglobal{get_new_handler}% \tcode{get_new_handler} \item \indexlibraryglobal{get_terminate} \tcode{get_terminate} \end{itemize} \pnum Calling the \tcode{set_*} and \tcode{get_*} functions shall not incur a data race\iref{intro.races}. A call to any of the \tcode{set_*} functions synchronizes with subsequent calls to the same \tcode{set_*} function and to the corresponding \tcode{get_*} function. \rSec3[res.on.functions]{Other functions} \pnum In certain cases (replacement functions, handler functions, operations on types used to instantiate standard library template components), the \Cpp{} standard library depends on components supplied by a \Cpp{} program. If these components do not meet their requirements, this document places no requirements on the implementation. \pnum In particular, the behavior is undefined in the following cases: \begin{itemize} \item For replacement functions\iref{replacement.functions}, if the installed replacement function does not implement the semantics of the applicable \required paragraph. \item For handler functions\iref{new.handler,terminate.handler}, if the installed handler function does not implement the semantics of the applicable \required paragraph. \item For types used as template arguments when instantiating a template component, if the operations on the type do not implement the semantics of the applicable \emph{Requirements} subclause\iref{allocator.requirements,container.requirements,iterator.requirements, algorithms.requirements,numeric.requirements}. Operations on such types can report a failure by throwing an exception unless otherwise specified. \item If any replacement function or handler function or destructor operation exits via an exception, unless specifically allowed in the applicable \required paragraph. \item If an incomplete type\iref{term.incomplete.type} is used as a template argument when instantiating a template component or evaluating a concept, unless specifically allowed for that component. \end{itemize} \rSec3[res.on.arguments]{Function arguments} \pnum \indextext{restriction}% \indextext{argument}% Each of the following applies to all arguments \indextext{argument}% to functions defined in the \Cpp{} standard library,% \indextext{library!\Cpp{} standard} unless explicitly stated otherwise. \begin{itemize} \item If an argument to a function has an invalid value (such \indextext{argument}% as a value outside the domain of the function or a pointer invalid for its intended use), the behavior is undefined. \indextext{undefined}% \item If a function argument is described as being an array, \indextext{argument}% the pointer actually passed to the function shall have a value such that all address computations and accesses to objects (that would be valid if the pointer did point to the first element of such an array) are in fact valid. \item If a function argument is bound to an rvalue reference parameter, the implementation may assume that this parameter is a unique reference to this argument, except that the argument passed to a move assignment operator may be a reference to \tcode{*this}\iref{lib.types.movedfrom}. \begin{note} If the type of a parameter is a forwarding reference\iref{temp.deduct.call} that is deduced to an lvalue reference type, then the argument is not bound to an rvalue reference. \end{note} \begin{note} If a program casts an lvalue to an xvalue while passing that lvalue to a library function (e.g., by calling the function with the argument \tcode{std::move(x)}), the program is effectively asking that function to treat that lvalue as a temporary object. The implementation is free to optimize away aliasing checks which would possibly be needed if the argument was an lvalue. \end{note} \end{itemize} \rSec3[res.on.objects]{Library object access} \pnum The behavior of a program is undefined if calls to standard library functions from different threads may introduce a data race. The conditions under which this may occur are specified in~\ref{res.on.data.races}. \begin{note} Modifying an object of a standard library type that is shared between threads risks undefined behavior unless objects of that type are explicitly specified as being shareable without data races or the user supplies a locking mechanism. \end{note} \pnum If an object of a standard library type is accessed, and the beginning of the object's lifetime\iref{basic.life} does not happen before the access, or the access does not happen before the end of the object's lifetime, the behavior is undefined unless otherwise specified. \begin{note} This applies even to objects such as mutexes intended for thread synchronization. \end{note} \rSec3[res.on.requirements]{Semantic requirements} \pnum A sequence \tcode{Args} of template arguments is said to \indextext{concept!model}% \defnx{model}{model!concept} a concept \tcode{C} if \tcode{Args} satisfies \tcode{C}\iref{temp.constr.decl} and meets all semantic requirements (if any) given in the specification of \tcode{C}. \pnum If the validity or meaning of a program depends on whether a sequence of template arguments models a concept, and the concept is satisfied but not modeled, the program is ill-formed, no diagnostic required. \pnum If the semantic requirements of a declaration's constraints\iref{structure.requirements} are not modeled at the point of use, the program is ill-formed, no diagnostic required. \rSec2[conforming]{Conforming implementations} \rSec3[conforming.overview]{Overview} \pnum Subclause \ref{conforming} describes the constraints upon, and latitude of, implementations of the \Cpp{} standard library. \pnum An implementation's use of \begin{itemize} \item headers is discussed in~\ref{res.on.headers}, \item macros in~\ref{res.on.macro.definitions}, \item non-member functions in~\ref{global.functions}, \item member functions in~\ref{member.functions}, \item data race avoidance in~\ref{res.on.data.races}, \item access specifiers in~\ref{protection.within.classes}, \item class derivation in~\ref{derivation}, \item exceptions in~\ref{res.on.exception.handling}, and \item contract assertions in~\ref{res.contract.assertions}. \end{itemize} \rSec3[res.on.headers]{Headers} \pnum A \Cpp{} header may include other \Cpp{} headers. A \Cpp{} header shall provide the declarations and definitions that appear in its synopsis. A \Cpp{} header shown in its synopsis as including other \Cpp{} headers shall provide the declarations and definitions that appear in the synopses of those other headers. \pnum Certain types and macros are defined in more than one header. Every such entity shall be defined such that any header that defines it may be included after any other header that also defines it\iref{basic.def.odr}. \pnum The C standard library headers\iref{support.c.headers} shall include only their corresponding \Cpp{} standard library header, as described in~\ref{headers}. \rSec3[res.on.macro.definitions]{Restrictions on macro definitions} \indextext{restriction}% \pnum The names and global function signatures described in~\ref{contents} are reserved to the implementation. \indextext{argument}% \indextext{header!C}% \indextext{function!global}% \indextext{inline}% \indextext{macro!masking}% \pnum All object-like macros defined by the C standard library and described in this Clause as expanding to integral constant expressions are also suitable for use in \tcode{\#if}\indextext{\idxcode{\#if}} preprocessing directives, unless explicitly stated otherwise. \rSec3[global.functions]{Non-member functions} \pnum It is unspecified whether any non-member functions in the \Cpp{} standard library are defined as inline\iref{dcl.inline}. \pnum A call to a non-member function signature described in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} shall behave as if the implementation declared no additional non-member function signatures. \begin{footnote} A valid \Cpp{} program always calls the expected library non-member function. An implementation can also define additional non-member functions that would otherwise not be called by a valid \Cpp{} program. \end{footnote} \pnum An implementation shall not declare a non-member function signature with additional default arguments. \pnum Unless otherwise specified, calls made by functions in the standard library to non-operator, non-member functions do not use functions from another namespace which are found through argument-dependent name lookup\iref{basic.lookup.argdep}. \begin{note} The phrase ``unless otherwise specified'' applies to cases such as the swappable with requirements\iref{swappable.requirements}. The exception for overloaded operators allows argument-dependent lookup in cases like that of \tcode{ostream_iterator::operator=}\iref{ostream.iterator.ops} where lookup for the expression \tcode{*out_stream << value} includes the associated namespaces of \tcode{value}'s type. \end{note} \rSec3[member.functions]{Member functions} \pnum It is unspecified whether any member functions in the \Cpp{} standard library are defined as inline\iref{dcl.inline}. \pnum For a non-virtual member function described in the \Cpp{} standard library, an implementation may declare a different set of member function signatures, provided that any call to the member function that would select an overload from the set of declarations described in this document behaves as if that overload were selected. \begin{note} For instance, an implementation can add parameters with default values, or replace a member function with default arguments with two or more member functions with equivalent behavior, or add additional signatures for a member function name. \end{note} \rSec3[hidden.friends]{Friend functions} \pnum Whenever this document specifies a friend declaration of a function or function template within a class or class template definition, that declaration shall be the only declaration of that function or function template provided by an implementation. \begin{note} In particular, a conforming implementation does not provide any additional declarations of that function or function template at namespace scope. \end{note} \begin{note} Such a friend function or function template declaration is known as a hidden friend, as it is visible neither to ordinary unqualified lookup\iref{basic.lookup.unqual} nor to qualified lookup\iref{basic.lookup.qual}. \end{note} \rSec3[constexpr.functions]{Constexpr functions and constructors} \pnum This document explicitly requires that certain standard library functions are \keyword{constexpr}\iref{dcl.constexpr}. An implementation shall not declare any standard library function signature as \keyword{constexpr} except for those where it is explicitly required. Within any header that provides any non-defining declarations of constexpr functions an implementation shall provide corresponding definitions. \rSec3[algorithm.stable]{Requirements for stable algorithms} \pnum \indextext{algorithm!stable}% \indextext{stable algorithm}% When the requirements for an algorithm state that it is ``stable'' without further elaboration, it means: \begin{itemize} \item For the sort algorithms the relative order of equivalent elements is preserved. \item For the remove and copy algorithms the relative order of the elements that are not removed is preserved. \item For the merge algorithms, for equivalent elements in the original two ranges, the elements from the first range (preserving their original order) precede the elements from the second range (preserving their original order). \end{itemize} \rSec3[reentrancy]{Reentrancy} \pnum Except where explicitly specified in this document, it is \impldef{which functions in the \Cpp{} standard library may be recursively reentered} which functions in the \Cpp{} standard library may be recursively reentered. \pnum During the execution of a standard library non-static member function $F$ on an object, if that object is accessed through a glvalue that is not obtained, directly or indirectly, from the object parameter of $F$, in a manner that can conflict\iref{intro.races} with any access that $F$ is permitted to perform\iref{res.on.data.races}, the behavior is undefined unless otherwise specified. \rSec3[res.on.data.races]{Data race avoidance} \pnum This subclause specifies requirements that implementations shall meet to prevent data races\iref{intro.multithread}. Every standard library function shall meet each requirement unless otherwise specified. Implementations may prevent data races in cases other than those specified below. \pnum A \Cpp{} standard library function shall not directly or indirectly access objects\iref{intro.multithread} accessible by threads other than the current thread unless the objects are accessed directly or indirectly via the function's arguments, including \keyword{this}. \pnum A \Cpp{} standard library function shall not directly or indirectly modify objects\iref{intro.multithread} accessible by threads other than the current thread unless the objects are accessed directly or indirectly via the function's non-const arguments, including \keyword{this}. \pnum \begin{note} This means, for example, that implementations can't use an object with static storage duration for internal purposes without synchronization because doing so can cause a data race even in programs that do not explicitly share objects between threads. \end{note} \pnum A \Cpp{} standard library function shall not access objects indirectly accessible via its arguments or via elements of its container arguments except by invoking functions required by its specification on those container elements. \pnum Operations on iterators obtained by calling a standard library container or string member function may access the underlying container, but shall not modify it. \begin{note} In particular, container operations that invalidate iterators conflict with operations on iterators associated with that container. \end{note} \pnum Implementations may share their own internal objects between threads if the objects are not visible to users and are protected against data races. \pnum Unless otherwise specified, \Cpp{} standard library functions shall perform all operations solely within the current thread if those operations have effects that are visible\iref{intro.multithread} to users. \pnum \begin{note} This allows implementations to parallelize operations if there are no visible \indextext{side effects}% side effects. \end{note} \rSec3[library.class.props]{Properties of library classes} \pnum Unless explicitly stated otherwise, it is unspecified whether any class described in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} is a trivially copyable class, a standard-layout class, or an implicit-lifetime class\iref{class.prop}. \rSec3[protection.within.classes]{Protection within classes} \pnum \indextext{protection}% It is unspecified whether any function signature or class described in \ref{\firstlibchapter} through \ref{\lastlibchapter} and \ref{depr} is a friend of another class in the \Cpp{} standard library. \indextext{specifier!\idxcode{friend}} \rSec3[derivation]{Derived classes} \pnum \indextext{class!derived}% \indextext{class!base}% An implementation may derive any class in the \Cpp{} standard library from a class with a name reserved to the implementation. \pnum Certain classes defined in the \Cpp{} standard library are required to be derived from other classes in the \Cpp{} standard library. \indextext{library!\Cpp{} standard}% An implementation may derive such a class directly from the required base or indirectly through a hierarchy of base classes with names reserved to the implementation. \pnum In any case: \begin{itemize} \item Every base class described as \keyword{virtual} shall be virtual; \indextext{class!base}% \item Every base class not specified as \keyword{virtual} shall not be virtual; \item Unless explicitly stated otherwise, types with distinct names shall be distinct types. \begin{note} There is an implicit exception to this rule for types that are described as synonyms\iref{dcl.typedef,namespace.udecl}, such as \tcode{size_t}\iref{support.types} and \tcode{streamoff}\iref{stream.types}. \end{note} \end{itemize} \pnum All types specified in the \Cpp{} standard library shall be non-\tcode{final} types unless otherwise specified. \rSec3[res.on.exception.handling]{Restrictions on exception handling}% \indextext{restriction}% \indextext{exception handling!handler} \pnum Any of the functions defined in the \Cpp{} standard library \indextext{library!\Cpp{} standard}% can report a failure by throwing an exception of a type described in its \throws paragraph, or of a type derived from a type named in the \throws paragraph that would be caught by a \grammarterm{handler}\iref{except.handle} for the base type. \pnum Functions from the C standard library shall not throw exceptions% \indextext{specifications!C standard library exception}% \begin{footnote} That is, the C standard library functions can all be treated as if they are marked \keyword{noexcept}. This allows implementations to make performance optimizations based on the absence of exceptions at runtime. \end{footnote} except when such a function calls a program-supplied function that throws an exception. \begin{footnote} The functions \tcode{qsort()} and \tcode{bsearch()}\iref{alg.c.library} meet this condition. \end{footnote} \pnum Destructor operations defined in the \Cpp{} standard library shall not throw exceptions. Every destructor in the \Cpp{} standard library shall behave as if it had a non-throwing exception specification\iref{except.spec}. \pnum Functions defined in the \Cpp{} standard library \indextext{specifications!\Cpp{}}% that do not have a \throws paragraph but do have a potentially-throwing exception specification may throw \impldef{exceptions thrown by standard library functions that have a potentially-throwing exception specification} exceptions. \begin{footnote} In particular, they can report a failure to allocate storage by throwing an exception of type \tcode{bad_alloc}, or a class derived from \tcode{bad_alloc}\iref{bad.alloc}. \end{footnote} Implementations should report errors by throwing exceptions of or derived from the standard exception classes\iref{bad.alloc,support.exception,std.exceptions}. \pnum An implementation may strengthen the exception specification for a non-virtual function by adding a non-throwing exception specification. \rSec3[res.contract.assertions]{Contract assertions} \pnum Unless specified otherwise, an implementation may check the specified preconditions and postconditions of a function in the \Cpp{} standard library using contract assertions\iref{basic.contract,structure.specifications}. \rSec3[value.error.codes]{Value of error codes} \pnum Certain functions in the \Cpp{} standard library report errors via an \tcode{error_code}\iref{syserr.errcode.overview} object. That object's \tcode{category()} member shall return \tcode{system_category()} for errors originating from the operating system, or a reference to an \impldef{\tcode{error_category} for errors originating outside the operating system} \tcode{error_category} object for errors originating elsewhere. The implementation shall define the possible values of \tcode{value()} for each of these error categories. \begin{example} For operating systems that are based on POSIX, implementations should define the \tcode{std::system_category()} values as identical to the POSIX \tcode{errno} values, with additional values as defined by the operating system's documentation. Implementations for operating systems that are not based on POSIX should define values identical to the operating system's values. For errors that do not originate from the operating system, the implementation may provide enums for the associated values. \end{example} \rSec3[lib.types.movedfrom]{Moved-from state of library types} \pnum Objects of types defined in the \Cpp{} standard library may be moved from\iref{class.copy.ctor}. Move operations may be explicitly specified or implicitly generated. Unless otherwise specified, such moved-from objects shall be placed in a valid but unspecified state\iref{defns.valid}. \pnum An object of a type defined in the \Cpp{} standard library may be move-assigned\iref{class.copy.assign} to itself. Unless otherwise specified, such an assignment places the object in a valid but unspecified state.