Each library clause contains the following elements, as applicable:155
Summary
Requirements
Detailed specifications
References to the C standard library
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.
Paragraphs labeled “Note(s):” or “Example(s):” are informative, other paragraphs are normative.
The contents of the summary and the detailed specifications include:
macros
values
types
classes and class templates
functions and function templates
objects
Requirements describe constraints that shall be met by a C++ program that extends the standard library. Such extensions are generally one of the following:
Template arguments
Derived classes
Containers, iterators, and algorithms that meet an interface convention
The string and iostream components use an explicit representation of operations required of template arguments. They use a class template char_traits to define these constraints.
Interface convention requirements are stated as generally as possible. Instead of stating “class X has to define a member function operator++()”, the interface requires “for any object x of class X, ++x is defined”. That is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions that define valid terms of the types that satisfy the requirements. For every set of well-defined expression requirements there is a table that specifies an initial set of the valid expressions and their semantics. Any generic algorithm (Clause [algorithms]) that uses the well-defined expression requirements is described in terms of the valid expressions for its template type parameters.
In some cases the semantic requirements are presented as C++ code. Such code is intended as a specification of equivalence of a construct to another construct, not necessarily as the way the construct must be implemented.156
20.4.1.4 Detailed specifications [structure.specifications]The detailed specifications each contain the following elements:
name and brief description
synopsis (class definition or function declaration, as appropriate)
restrictions on template arguments, if any
description of class invariants
description of function semantics
Descriptions of class member functions follow the order (as appropriate):157
constructor(s) and destructor
copying, moving & assignment functions
comparison functions
modifier functions
observer functions
operators and other non-member functions
Descriptions of function semantics contain the following elements (as appropriate):158
Requires: the preconditions for calling the function
Effects: the actions performed by the function
Synchronization: the synchronization operations ([intro.multithread]) applicable to the function
Postconditions: the observable results established by the function
Returns: a description of the value(s) returned by the function
Throws: any exceptions thrown by the function, and the conditions that would cause the exception
Complexity: the time and/or space complexity of the function
Remarks: additional semantic constraints on the function
Error conditions: the error conditions for error codes reported by the function
Whenever the Effects element specifies that the semantics of some function F are Equivalent to some code sequence, then the various elements are interpreted as follows. If F's semantics specifies a Requires element, then that requirement is logically imposed prior to the equivalent-to semantics. Next, the semantics of the code sequence are determined by the Requires, Effects, Synchronization, Postconditions, Returns, Throws, Complexity, Remarks, and Error conditions specified for the function invocations contained in the code sequence. The value returned from F is specified by F's Returns element, or if F has no Returns element, a non-void return from F is specified by the return statements in the code sequence. If F's semantics contains a Throws, Postconditions, or Complexity element, then that supersedes any occurrences of that element in the code sequence.
For non-reserved replacement and handler functions, Clause [language.support] specifies two behaviors for the functions in question: their required and default behavior. The default behavior describes a function definition provided by the implementation. The required behavior describes the semantics of a function definition provided by either the implementation or a C++ program. Where no distinction is explicitly made in the description, the behavior described is the required behavior.
If the formulation of a complexity requirement calls for a negative number of operations, the actual requirement is zero operations.159
Complexity requirements specified in the library clauses are upper bounds, and implementations that provide better complexity guarantees satisfy the requirements.
Error conditions specify conditions where a function may fail. The conditions are listed, together with a suitable explanation, as the enum class errc constants ([syserr]).
20.4.1.5 C library [structure.see.also]Paragraphs labeled “See also” contain cross-references to the relevant portions of this International Standard and the ISO C standard.
20.4.2 Other conventions [conventions] 20.4.2.1 Type descriptions [type.descriptions] 20.4.2.1.1 General [type.descriptions.general]The Requirements subclauses may describe names that are used to specify constraints on template arguments.160 These names are used in library Clauses to describe the types that may be supplied as arguments by a C++ program when instantiating template components from the library.
Certain types defined in Clause [input.output] are used to describe implementation-defined types. They are based on other types, but with added constraints.
20.4.2.1.2 Exposition-only types [expos.only.types]Several types defined in Clauses [language.support] through [thread] and Annex [depr] that are used as function parameter or return types are defined for the purpose of exposition only in order to capture their language linkage. The declarations of such types are followed by a comment ending in exposition only. [ Example:
namespace std {
extern "C" using some-handler = int(int, void*, double); }
The type placeholder some-handler can now be used to specify a function that takes a callback parameter with C language linkage. — end example ]
20.4.2.1.3 Enumerated types [enumerated.types]Several types defined in Clause [input.output] are enumerated types. Each enumerated type may be implemented as an enumeration or as a synonym for an enumeration.161
The enumerated type enumerated can be written:
enum enumerated { \textit{V}0, \textit{V}1, \textit{V}2, \textit{V}3, ..... };
inline const \textit{enumerated C}0(\textit{V}0);
inline const \textit{enumerated C}1(\textit{V}1);
inline const \textit{enumerated C}2(\textit{V}2);
inline const \textit{enumerated C}3(\textit{V}3);
.....
Here, the names \textit{C}0, \textit{C}1, etc. represent enumerated elements for this particular enumerated type. All such elements have distinct values.
20.4.2.1.4 Bitmask types [bitmask.types]The bitmask type bitmask can be written:
enum bitmask : int_type {
\textit{V}0 = 1 << 0, \textit{V}1 = 1 << 1, \textit{V}2 = 1 << 2, \textit{V}3 = 1 << 3, .....
};
inline constexpr \textit{bitmask C}0(\textit{V}0);
inline constexpr \textit{bitmask C}1(\textit{V}1);
inline constexpr \textit{bitmask C}2(\textit{V}2);
inline constexpr \textit{bitmask C}3(\textit{V}3);
.....
constexpr bitmask operator&(bitmask X, bitmask Y) {
return static_cast<bitmask>(
static_cast<int_type>(X) & static_cast<int_type>(Y));
}
constexpr bitmask operator|(bitmask X, bitmask Y) {
return static_cast<bitmask>(
static_cast<int_type>(X) | static_cast<int_type>(Y));
}
constexpr bitmask operator^(bitmask X, bitmask Y){
return static_cast<bitmask>(
static_cast<int_type>(X) ^ static_cast<int_type>(Y));
}
constexpr bitmask operator~(bitmask X){
return static_cast<bitmask>(~static_cast<int_type>(X));
}
bitmask& operator&=(bitmask& X, bitmask Y){
X = X & Y; return X;
}
bitmask& operator|=(bitmask& X, bitmask Y) {
X = X | Y; return X;
}
bitmask& operator^=(bitmask& X, bitmask Y) {
X = X ^ Y; return X;
}
Here, the names \textit{C}0, \textit{C}1, etc. represent bitmask elements for this particular bitmask type. All such elements have distinct, nonzero values such that, for any pair \textit{C}i and \textit{C}j where i≠j, Ci & Ci is nonzero and Ci & Cj is zero. Additionally, the value 0 is used to represent an empty bitmask, in which no bitmask elements are set.
The following terms apply to objects and values of bitmask types:
To set a value Y in an object X is to evaluate the expression X |= Y.
To clear a value Y in an object X is to evaluate the expression X &= ~Y.
The value Y is set in the object X if the expression X & Y is nonzero.
The C standard library makes widespread use of characters and character sequences that follow a few uniform conventions:
A letter is any of the 26 lowercase or 26 uppercase letters in the basic execution character set.
The decimal-point character is the (single-byte) character used by functions that convert between a (single-byte) character sequence and a value of one of the floating-point types. It is used in the character sequence to denote the beginning of a fractional part. It is represented in Clauses [language.support] through [thread] and Annex [depr] by a period, '.', which is also its value in the "C" locale, but may change during program execution by a call to setlocale(int, const char*),162 or by a change to a locale object, as described in Clauses [locales] and [input.output].
A character sequence is an array object A that can be declared as T A[N], where T is any of the types char, unsigned char, or signed char ([basic.fundamental]), optionally qualified by any combination of const or volatile. The initial elements of the array have defined contents up to and including an element determined by some predicate. A character sequence can be designated by a pointer value S that points to its first element.
The length of an ntbs is the number of elements that precede the terminating null character. An empty ntbs has a length of zero.
The value of an ntbs is the sequence of values of the elements up to and including the terminating null character.
A static ntbs is an ntbs with static storage duration.164
20.4.2.2 Functions within classes [functions.within.classes]For the sake of exposition, Clauses [language.support] through [thread] and Annex [depr] do not describe copy/move constructors, assignment operators, or (non-virtual) destructors with the same apparent semantics as those that can be generated by default ([class.ctor], [class.dtor], [class.copy]). It is unspecified whether the implementation provides explicit definitions for such member function signatures, or for virtual destructors that can be generated by default.
For the sake of exposition, the library clauses sometimes annotate constructors with EXPLICIT. Such a constructor is conditionally declared as either explicit or non-explicit ([class.conv.ctor]). [ Note: This is typically implemented by declaring two such constructors, of which at most one participates in overload resolution. — end note ]
20.4.2.3 Private members [objects.within.classes]For the sake of exposition, some subclauses provide representative declarations, and semantic requirements, for private members of classes that meet the external specifications of the classes. The declarations for such members are followed by a comment that ends with exposition only, as in:
streambuf* sb;
An implementation may use any technique that provides equivalent observable behavior.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4