______________________________________________________________________
17 Library introduction [lib.library]
______________________________________________________________________
1 This clause describes the contents of the C++ Standard Library, how a
well-formed C++ program makes use of the library, and how a conforming
implementation may provide the entities in the library.
2 The C++ Standard Library provides an extensible framework, and con-
tains components for: language support, diagnostics, general utili-
ties, strings, locales, containers, iterators, algorithms, numerics,
and input/output. The language support components are required by
certain parts of the C++ language, such as memory allocation
(_expr.new_, _expr.delete_) and exception processing (clause
_except_).
3 The general utilities include components used by other library ele-
ments, such as a predefined storage allocator for dynamic storage man-
agement (_basic.stc.dynamic_). The diagnostics components provide a
consistent framework for reporting errors in a C++ program, including
predefined exception classes.
4 The strings components provide support for manipulating text repre-
sented as sequences of type char, sequences of type wchar_t, or
sequences of any other ``character-like'' type. The localization com-
ponents extend internationalization support for such text processing.
5 The containers, iterators, and algorithms provide a C++ program with
access to a subset of the most widely used algorithms and data struc-
tures.
6 Numeric algorithms and the complex number components extend support
for numeric processing. The valarray components provide support for
n-at-a-time processing, potentially implemented as parallel operations
on platforms that support such processing.
7 The iostreams components are the primary mechanism for C++ program
input/output. They can be used with other elements of the library,
particularly strings, locales, and iterators.
8 This library also makes available the facilities of the Standard C
library, suitably adjusted to ensure static type safety.
9 The following subclauses describe the definitions (_lib.definitions_),
and method of description (_lib.description_) for the library. Clause
_lib.requirements_ and clauses _lib.language.support_ through
_lib.input.output_ specify the contents of the library, and library
requirements and constraints on both well-formed C++ programs and con-
forming implementations.
17.1 Definitions [lib.definitions]
17.1.1 arbitrary-positional stream [defns.arbitrary.stream]
a stream (described in clause _lib.input.output_) that can seek to any
integral position within the length of the stream. Every arbitrary-
positional stream is also a repositional stream (_defns.reposi-
tional.stream_).
17.1.2 character [defns.character]
in clauses _lib.strings_, _lib.localization_, and _lib.input.output_,
means any object which, when treated sequentially, can represent text.
The term does not only mean char and wchar_t objects, but any value
that can be represented by a type that provides the definitions speci-
fied in these clauses.
17.1.3 character container type [defns.character.container]
a class or a type used to represent a character (_defns.character_).
It is used for one of the template parameters of the string and
iostream class templates. A character container class shall be a POD
(_basic.types_) type.
17.1.4 comparison function [defns.comparison]
an operator function (_over.oper_) for any of the equality (_expr.eq_)
or relational (_expr.rel_) operators.
17.1.5 component [defns.component]
a group of library entities directly related as members, parameters,
or return types. For example, the class template basic_string and the
non-member template functions that operate on strings are referred to
as the string component.
17.1.6 default behavior [defns.default.behavior]
a description of replacement function and handler function semantics.
Any specific behavior provided by the implementation, within the scope
of the required behavior.
17.1.7 handler function [defns.handler]
a reserved function whose definition may be provided by a C++ program.
A C++ program may designate a handler function at various points in
its execution, by supplying a pointer to the function when calling any
of the library functions that install handler functions (clause
_lib.language.support_).
17.1.8 iostream class templates [defns.iostream.templates]
templates, defined in clause _lib.input.output_, that take two tem-
plate arguments: charT and traits. The argument charT is a character
container class, and the argument traits is a structure which defines
additional characteristics and functions of the character type repre-
sented by charT necessary to implement the iostream class templates.
17.1.9 modifier function [defns.modifier]
a class member function (_class.mfct_), other than constructors,
assignment, or destructor, that alters the state of an object of the
class.
17.1.10 object state [defns.obj.state]
the current value of all nonstatic class members of an object
(_class.mem_). The state of an object can be obtained by using one or
more observer functions.
17.1.11 narrow-oriented iostream classes
the instantiations of the iostream class templates on the character
container class char and the default value of the traits parameter.
The traditional iostream classes are regarded as the narrow-oriented
iostream classes (_lib.narrow.stream.objects_).
17.1.12 NTCTS [defns.ntcts]
a sequence of values that have character type, that precede the termi-
nating null character type value charT().
17.1.13 observer function [defns.observer]
a class member function (_class.mfct_) that accesses the state of an
object of the class, but does not alter that state. Observer func-
tions are specified as const member functions (_class.this_).
17.1.14 replacement function [defns.replacement]
a reserved function whose definition is provided by a C++ program.
Only one definition for such a function is in effect for the duration
of the program's execution, as the result of creating the program
(_lex.phases_) and resolving the definitions of all translation units
(_basic.link_).
17.1.15 required behavior [defns.required.behavior]
a description of replacement function and handler function semantics,
applicable to both the behavior provided by the implementation and the
behavior that shall be provided by any function definition in the pro-
gram. If a function defined in a C++ program fails to meet the
required behavior when it executes, the behavior is undefined.
17.1.16 repositional stream [defns.repositional.stream]
a stream (described in clause _lib.input.output_) that can seek only
to a position that was previously encountered.
17.1.17 reserved function [defns.reserved.function]
a function, specified as part of the C++ Standard Library, that must
be defined by the implementation. If a C++ program provides a defini-
tion for any reserved function, the results are undefined.
17.1.18 traits class [defns.traits]
a class that encapsulates a set of types and functions necessary for
template classes and template functions to manipulate objects of types
for which they are instantiated. Traits classes defined in clauses
_lib.strings_, _lib.localization_ and _lib.input.output_ are chararac-
ter traits, which provide the character handling support needed by the
string and iostream classes.
17.1.19 wide-oriented iostream classes
the instantiations of the iostream class templates on the character
container class wchar_t and the default value of the traits parameter
(_lib.wide.stream.objects_).
17.2 Additional definitions [defns.additional]
_intro.defs_ defines additional terms used elsewhere in this Interna-
tional Standard.
17.3 Method of description (Informative) [lib.description]
1 _lib.description_ describes the conventions used to describe the C++
Standard Library. It describes the structures of the normative
clauses _lib.language.support_ through _lib.input.output_ (_lib.struc-
ture_), and other editorial conventions (_lib.conventions_).
17.3.1 Structure of each subclause [lib.structure]
1 _lib.organization_ provides a summary of the C++ Standard library's
contents. Other Library clauses provide detailed specifications for
each of the components in the library, as shown in Table 1:
Table 1--Library Categories
+-------------------------------------------+
| Clause Category |
+-------------------------------------------+
|_lib.language.support_ Language support |
|_lib.diagnostics_ Diagnostics |
|_lib.utilities_ General utilities |
|_lib.strings_ Strings |
|_lib.localization_ Localization |
|_lib.containers_ Containers |
|_lib.iterators_ Iterators |
|_lib.algorithms_ Algorithms |
|_lib.numerics_ Numerics |
|_lib.input.output_ Input/output |
+-------------------------------------------+
2 Each Library clause contains the following elements, as applicable:1)
--Summary
--Requirements
_________________________
1) 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.
--Detailed specifications
--References to the Standard C library
17.3.1.1 Summary [lib.structure.summary]
1 The Summary provides a synopsis of the category, and introduces the
first-level subclauses. Each subclause also provides a summary, list-
ing the headers specified in the subclause and the library entities
provided in each header.
2 Paragraphs labelled ``Note(s):'' or ``Example(s):'' are informative,
other paragraphs are normative.
3 The summary and the detailed specifications are presented in the
order:
--Macros
--Values
--Types
--Classes
--Functions
--Objects
17.3.1.2 Requirements [lib.structure.requirements]
1 The library can be extended by a C++ program. Each clause, as appli-
cable, describes the requirements that such extensions must meet.
Such extensions are generally one of the following:
--Template arguments
--Derived classes
--Containers, iterators, and/or algorithms that meet an interface con-
vention
2 The string and iostreams components use an explicit representation of
operations required of template arguments. They use a template class
name char_traits to define these constraints.
3 Interface convention requirements are stated as generally as possible.
Instead of stating ``class X has to define a member function opera-
tor++(),'' the interface requires ``for any object x of class X, ++x
is defined.'' That is, whether the operator is a member is unspeci-
fied.
4 Requirements are stated in terms of well-defined expressions, which
define valid terms of the types that satisfy the requirements. For
every set of requirements there is a table that specifies an initial
set of the valid expressions and their semantics (_lib.alloca-
tor.requirements_, _lib.container.requirements_, _lib.itera-
tor.requirements_). Any generic algorithm (clause _lib.algorithms_)
that uses the requirements is described in terms of the valid expres-
sions for its formal type parameters.
5 Template argument requirements are sometimes referenced by name. See
_lib.type.descriptions_.
6 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.2)
17.3.1.3 Specifications [lib.structure.specifications]
1 The detailed specifications each contain the following elements:3)
--Name and brief description
--Synopsis (class definition or function prototype, as appropriate)
--Restrictions on template arguments, if any
--Description of class invariants
--Description of function semantics
2 Descriptions of class member functions follow the order (as
appropriate):4)
--Constructor(s) and destructor
--Copying & assignment functions
--Comparison functions
--Modifier functions
--Observer functions
--Operators and other non-member functions
_________________________
2) Although in some cases the code given is unambiguously the optimum
implementation.
3) The form of these specifications was designed to follow the conven-
tions established by existing C++ library vendors.
4) To save space, items that do not apply to a class are omitted. For
example, if a class does not specify any comparison functions, there
will be no ``Comparison functions'' subclause.
3 Descriptions of function semantics contain the following elements (as
appropriate):5)
--Requires: the preconditions for calling the function
--Effects: the actions performed by 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
4 For non-reserved replacement and handler functions, Clause _lib.lan-
guage.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.
5 Complexity requirements specified in the library clauses are upper
bounds, and implementations that provide better complexity guarantees
satisfy the requirements.
17.3.1.4 C Library [lib.structure.see.also]
1 Paragraphs labelled ``SEE ALSO:'' contain cross-references to the rel-
evant portions of this Standard and the ISO C standard, which is
incorporated into this Standard by reference.
17.3.2 Other conventions [lib.conventions]
1 This subclause describes several editorial conventions used to
describe the contents of the C++ Standard Library. These conventions
are for describing implementation-defined types (_lib.type.descrip-
tions_), and member functions (_lib.functions.within.classes_).
17.3.2.1 Type descriptions [lib.type.descriptions]
1 The Requirements subclauses may describe names that are used to spec-
ify constraints on template arguments.6) These names are used in
_________________________
5) To save space, items that do not apply to a function are omitted.
For example, if a function does not specify any preconditions, there
will be no ``Requires'' paragraph.
6) Examples from _lib.utility.requirements_ include: EqualityCompara-
ble, LessThanComparable, CopyConstructable, etc. Examples from
_lib.iterator.requirements_ include: InputIterator, ForwardIterator,
Function, Predicate, etc.
clauses _lib.utilities_, _lib.containers_, _lib.algorithms_, and
_lib.numerics_ to describe the types that may be supplied as arguments
by a C++ program when instantiating template components from the
library.
2 Certain types defined in clause _lib.input.output_ are used to
describe implementation-defined types. They are based on other types,
but with added constraints.
17.3.2.1.1 Enumerated types [lib.enumerated.types]
1 Several types defined in clause _lib.input.output_ are enumerated
types. Each enumerated type may be implemented as an enumeration or
as a synonym for an enumeration.7)
2 The enumerated type enumerated can be written:
enum enumerated { V0, V1, V2, V3, .....};
static const enumerated C0(V0);
static const enumerated C1(V1);
static const enumerated C2(V2);
static const enumerated C3(V3);
.....
3 Here, the names C0, C1, etc. represent enumerated elements for this
particular enumerated type. All such elements have distinct values.
17.3.2.1.2 Bitmask types [lib.bitmask.types]
1 Several types defined in clause _lib.input.output_ are bitmask types.
Each bitmask type can be implemented as an enumerated type that over-
loads certain operators, as an integer type, or as a bitset (_lib.tem-
plate.bitset_).
2 The bitmask type bitmask can be written:
enum bitmask {
V0 = 1 << 0, V1 = 1 << 1, V2 = 1 << 2, V3 = 1 << 3, .....
};
static const bitmask C0(V0);
static const bitmask C1(V1);
static const bitmask C2(V2);
static const bitmask C3(V3);
.....
_________________________
7) Such as an integer type, with constant integer values (_basic.fun-
damental_).
bitmask operator& (bitmask X, bitmask Y)
// For exposition only.
// int_type is an integral type capable of
// representing all values of bitmask
{ return static_cast<bitmask>(
static_cast<int_type>(X) &
static_cast<int_type>(Y)); }
bitmask operator| (bitmask X, bitmask Y)
{ return static_cast<bitmask>(
static_cast<int_type>(X) |
static_cast<int_type>(Y)); }
bitmask operator^ (bitmask X, bitmask Y)
{ return static_cast<bitmask>(
static_cast<int_type>(X) ^
static_cast<int_type>(Y)); }
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; }
3 Here, the names C0, C1, etc. represent bitmask elements for this par-
ticular bitmask type. All such elements have distinct values such
that, for any pair Ci and Cj, Ci & Ci is nonzero and Ci & Cj is zero.
4 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.
17.3.2.1.3 Character sequences [lib.character.seq]
1 The Standard C library makes widespread use of characters and charac-
ter 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.8)
--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
_________________________
8) Note that this definition differs from the definition in ISO C sub-
clause 7.1.1.
character sequence to denote the beginning of a fractional part. It
is represented in clauses _lib.language.support_ through
_lib.input.output_ 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*),9) or by a change to a locale object, as
described in clauses _lib.locales_ and _lib.input.output_.
--A character sequence is an array object (_dcl.array_) 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.
17.3.2.1.3.1 Byte strings [lib.byte.strings]
1 A null-terminated byte string, or NTBS, is a character sequence whose
highest-addressed element with defined content has the value zero (the
terminating null character).10)
2 The length of an NTBS is the number of elements that precede the ter-
minating null character. An empty NTBS has a length of zero.
3 The value of an NTBS is the sequence of values of the elements up to
and including the terminating null character.
4 A static NTBS is an NTBS with static storage duration.11)
17.3.2.1.3.2 Multibyte strings [lib.multibyte.strings]
1 A null-terminated multibyte string, or NTMBS, is an NTBS that consti-
tutes a sequence of valid multibyte characters, beginning and ending
in the initial shift state.12)
2 A static NTMBS is an NTMBS with static storage duration.
17.3.2.1.3.3 Wide-character sequences [lib.wide.characters]
1 A wide-character sequence is an array object (_dcl.array_) A that can
be declared as T A[N], where T is type wchar_t (_basic.fundamental_),
optionally qualified by any combination of const or volatile. The
initial elements of the array have defined contents up to and
_________________________
9) declared in <clocale> (_lib.c.locales_).
10) Many of the objects manipulated by function signatures declared in
<cstring> (_lib.c.strings_) are character sequences or NTBSs. The
size of some of these character sequences is limited by a length val-
ue, maintained separately from the character sequence.
11) A string literal, such as "abc", is a static NTBS.
12) An NTBS that contains characters only from the basic execution
character set is also an NTMBS. Each multibyte character then con-
sists of a single byte.
including an element determined by some predicate. A character
sequence can be designated by a pointer value S that designates its
first element.
2 A null-terminated wide-character string, or NTWCS, is a wide-character
sequence whose highest-addressed element with defined content has the
value zero.13)
3 The length of an NTWCS is the number of elements that precede the ter-
minating null wide character. An empty NTWCS has a length of zero.
4 The value of an NTWCS is the sequence of values of the elements up to
and including the terminating null character.
5 A static NTWCS is an NTWCS with static storage duration.14)
17.3.2.2 Functions within classes [lib.functions.within.classes]
1 For the sake of exposition, clauses _lib.language.support_ through
_lib.input.output_ do not describe copy constructors, assignment oper-
ators, or (non-virtual) destructors with the same apparent semantics
as those that can be generated by default (_class.ctor_, _class.dtor_,
_class.copy_).
2 It is unspecified whether the implementation provides explicit defini-
tions for such member function signatures, or for virtual destructors
that can be generated by default.
17.3.2.3 Private members [lib.objects.within.classes]
1 Clauses _lib.language.support_ through _lib.input.output_ do not spec-
ify the representation of classes, and intentionally omit specifica-
tion of class members (_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 clauses _lib.lan-
guage.support_ through _lib.input.output_.
2 Objects of certain classes are sometimes required by the external
specifications of their classes to store data, apparently in member
objects. For the sake of exposition, some subclauses provide repre-
sentative declarations, and semantic requirements, for private member
objects of classes that meet the external specifications of the
classes. The declarations for such member objects and the definitions
of related member types are enclosed in a comment that ends with expo-
sition only, as in:
// streambuf* sb; exposition only
3 Any alternate implementation that provides equivalent external behav-
ior is equally acceptable.
_________________________
13) Many of the objects manipulated by function signatures declared in
<cwchar> are wide-character sequences or NTWCSs.
14) A wide string literal, such as L"abc", is a static NTWCS.
17.4 Library-wide requirements [lib.requirements]
1 This subclause specifies requirements that apply to the entire C++
Standard library. Clauses _lib.language.support_ through
_lib.input.output_ specify the requirements of individual entities
within the library.
2 The following subclauses describe the library's contents and organiza-
tion (_lib.organization_), how well-formed C++ programs gain access to
library entities (_lib.using_), constraints on such programs
(_lib.constraints_), and constraints on conforming implementations
(_lib.conforming_).
17.4.1 Library contents and organization [lib.organization]
1 This subclause provides a summary of the entities defined in the C++
Standard Library. Subclause _lib.contents_ provides an alphabetical
listing of entities by type, while subclause _lib.headers_ provides an
alphabetical listing of library headers.
17.4.1.1 Library contents [lib.contents]
1 The C++ Standard Library provides definitions for the following types
of entities: Macros, Values, Types, Templates, Classes, Functions,
Objects.
2 All library entities except macros, operator new and operator delete
are defined within the namespace std or namespaces nested within
namespace std.
17.4.1.2 Headers [lib.headers]
1 The elements of the C++ Standard Library are declared or defined (as
appropriate) in a header.15)
2 The C++ Standard Library provides 32 C++ headers, as shown in Table 2:
_________________________
15) A header is not necessarily a source file, nor are the sequences
delimited by < and > in header names necessarily valid source file
names (_cpp.include_).
Table 2--C++ Library Headers
+------------------------------------------------------------------+
|<algorithm> <iomanip> <list> <ostream> <streambuf> |
|<bitset> <ios> <locale> <queue> <string> |
|<complex> <iosfwd> <map> <set> <typeinfo> |
|<deque> <iostream> <memory> <sstream> <utility> |
|<exception> <istream> <new> <stack> <valarray> |
|<fstream> <iterator> <numeric> <stdexcept> <vector> |
|<functional> <limits> |
+------------------------------------------------------------------+
3 The facilities of the Standard C Library are provided in 18 additional
headers, as shown in Table 3:
Table 3--C++ Headers for C Library Facilities
+--------------------------------------------------+
|<cassert> <ciso646> <csetjmp> <cstdio> <ctime> |
|<cctype> <climits> <csignal> <cstdlib> <cwchar> |
|<cerrno> <clocale> <cstdarg> <cstring> <cwctype> |
|<cfloat> <cmath> <cstddef> |
+--------------------------------------------------+
4 Except as noted in clauses _lib.language.support_ through
_lib.input.output_, the contents of each header cname shall be the
same as that of the corresponding header name.h, as specified in
ISO/IEC 9899:1990 Programming Languages C (Clause 7), or ISO/IEC:1990
Programming Languages--C AMENDMENT 1: C Integrity, (Clause 7), as
appropriate, as if by inclusion. In the C++ Standard Library, how-
ever, the declarations and definitions (except for names which are
defined as macros in C) are within namespace scope
(_basic.scope.namespace_) of the namespace std.
5 Names which are defined as macros in C shall be defined as macros in
the C++ Standard Library, even if license is granted in C for imple-
mentation as functions. [Note: the names defined as macros in C
include the following: assert, errno, offsetof, setjmp, va_arg,
va_end, and va_start. --end note]
6 Names that are defined as functions in C shall be defined as functions
in the C++ Standard Library.16)
_________________________
16) 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 C++ is to provide a definition as an
extern inline function.
7 _depr.c.headers_, Standard C library headers, describes the effects of
using the name.h (C header) form in a C++ program.17)
17.4.1.3 Freestanding implementations [lib.compliance]
1 Two kinds of implementations are defined: hosted and freestanding
(_intro.compliance_). For a hosted implementation, this International
Standard describes the set of available headers.
2 A freestanding implementation has an implementation-defined set of
headers. This set shall include at least the following headers, as
shown in Table 4:
Table 4--C++ Headers for Freestanding Implementations
+--------------------------------------------------------------+
| Subclause Header(s) |
+--------------------------------------------------------------+
|_lib.support.types_ Types <cstddef> |
+--------------------------------------------------------------+
|_lib.support.limits_ Implementation properties <limits> |
+--------------------------------------------------------------+
|_lib.support.start.term_ Start and termination <cstdlib> |
+--------------------------------------------------------------+
|_lib.support.dynamic_ Dynamic memory management <new> |
+--------------------------------------------------------------+
|_lib.support.rtti_ Type identification <typeinfo> |
+--------------------------------------------------------------+
|_lib.support.exception_ Exception handling <exception> |
+--------------------------------------------------------------+
|_lib.support.runtime_ Other runtime support <cstdarg> |
+--------------------------------------------------------------+
3 The supplied version of the header <cstdlib> shall declare at least
the functions abort(), atexit(), and exit() (_lib.sup-
port.start.term_).
17.4.2 Using the library [lib.using]
1 This subclause describes how a C++ program gains access to the facili-
ties of the C++ Standard Library. _lib.using.headers_ describes
effects during translation phase 4, while _lib.using.linkage_
describes effects during phase 8 (_lex.phases_).
_________________________
17) The ".h" headers dump all their names into the global namespace,
whereas the newer forms keep their names in namespace std. Therefore,
the newer forms are the preferred forms for all uses except for C++
programs which are intended to be strictly compatible with C.
17.4.2.1 Headers [lib.using.headers]
1 The entities in the C++ Standard Library are defined in headers, whose
contents are made available to a translation unit when it contains the
appropriate #include preprocessing directive (_cpp.include_).
2 A translation unit may include library headers in any order (clause
_lex_). Each may be included more than once, with no effect different
from being included exactly once, except that the effect of including
either <cassert> or <assert.h> depends each time on the lexically cur-
rent definition of NDEBUG.18)
3 A translation unit shall include a header only outside of any external
declaration or definition, and shall include the header lexically
before the first reference to any of the entities it declares or first
defines in that translation unit.
17.4.2.2 Linkage [lib.using.linkage]
1 Entities in the C++ Standard Library have external linkage
(_basic.link_). Unless otherwise specified, objects and functions
have the default extern "C++" linkage (_dcl.link_).
2 It is unspecified whether a name from the Standard C library declared
with external linkage has either extern "C" or extern "C++"
linkage.19)
3 Objects and functions defined in the library and required by a C++
program are included in the program prior to program startup.
SEE ALSO: replacement functions (_lib.replacement.functions_), run-
time changes (_lib.handler.functions_).
17.4.3 Constraints on programs [lib.constraints]
1 This subclause describes restrictions on C++ programs that use the
facilities of the C++ Standard Library. The following subclauses
specify constraints on the program's namespace (_lib.reserved.names_),
its use of headers (_lib.alt.headers_), classes derived from standard
library classes (_lib.derived.classes_), definitions of replacement
functions (_lib.replacement.functions_), and installation of handler
functions during execution (_lib.handler.functions_).
_________________________
18) This is the same as the Standard C library.
19) The only reliable way to declare an object or function signature
from the Standard C library is by including the header that declares
it, notwithstanding the latitude granted in subclause 7.1.7 of the C
Standard.
17.4.3.1 Reserved names [lib.reserved.names]
1 It is undefined for a C++ program to add declarations or definitions
to namespace std or namespaces within namespace std unless otherwise
specified. A program may add template specializations for any stan-
dard library template to namespace std. Such a specialization (com-
plete or partial) of a standard library template results in undefined
behavior unless the declaration depends on a user-defined name of
external linkage and unless the specialization meets the standard
library requirements for the original template.20)
2 The C++ Standard Library reserves the following kinds of names:
--Macros
--Global names
--Names with external linkage
3 If the program declares or defines a name in a context where it is
reserved, other than as explicitly allowed by this clause, the behav-
ior is undefined.
17.4.3.1.1 Macro names [lib.macro.names]
1 Each name defined as a macro in a header is reserved to the implemen-
tation for any use if the translation unit includes the header.21)
2 A translation unit that includes a header shall not contain any macros
that define names declared or defined in that header. Nor shall such
a translation unit define macros for names lexically identical to key-
words.
17.4.3.1.2 Global names [lib.global.names]
1 Certain sets of names and function signatures are always reserved to
the implementation:
--Each name that contains a double underscore __) or begins with an
underscore followed by an uppercase letter (_lex.key_) is reserved
to the implementation for any use.
--Each name that begins with an underscore is reserved to the imple-
mentation for use as a name in the global namespace.22)
_________________________
20) 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 the Standard.
21) It is not permissible to remove a library macro definition by us-
ing the #undef directive.
22) Such names are also reserved in namespace ::std (_lib.re-
served.names_).
17.4.3.1.3 External linkage [lib.extern.names]
1 Each name declared as an object with external linkage in a header is
reserved to the implementation to designate that library object with
external linkage,23) both in namespace std and in the global names-
pace.
2 Each global function signature declared with external linkage in a
header is reserved to the implementation to designate that function
signature with external linkage.24)
3 Each name having two consecutive underscores (_lex.key_) is reserved
to the implementation for use as a name with both extern "C" and
extern "C++" linkage.
4 Each name from the Standard C library declared with external linkage
is reserved to the implementation for use as a name with extern "C"
linkage, both in namespace std and in the global namespace.
5 Each function signature from the Standard C library declared with
external linkage is reserved to the implementation for use as a func-
tion signature with both extern "C" and extern "C++" linkage,25) or as
a name of namespace scope in the global namespace.
17.4.3.1.4 Types [lib.extern.types]
1 For each type T from the Standard C library,26) the types ::T and
std::T are reserved to the implementation and, when defined, ::T shall
be identical to std::T.
17.4.3.2 Headers [lib.alt.headers]
1 If a file with a name equivalent to the derived file name for one of
the C++ Standard Library headers is not provided as part of the imple-
mentation, and a file with that name is placed in any of the standard
places for a source file to be included (_cpp.include_), the behavior
is undefined.
_________________________
23) The list of such reserved names includes errno, declared or de-
fined in <cerrno>.
24) The list of such reserved function signatures with external link-
age includes setjmp(jmp_buf), declared or defined in <csetjmp>, and
va_end(va_list), declared or defined in <cstdarg>.
25) The function signatures declared in <cwchar> and <cwctype> are al-
ways reserved, notwithstanding the restrictions imposed in subclause
4.5.1 of Amendment 1 to the C Standard for these headers.
26) These types are clock_t, div_t, FILE, fpos_t, lconv, ldiv_t, mb-
state_t, ptrdiff_t, sig_atomic_t, size_t, time_t, tm, va_list, wc-
trans_t, wctype_t, and wint_t.
17.4.3.3 Derived classes [lib.derived.classes]
1 Virtual member function signatures defined for a base class in the C++
Standard library may be overridden in a derived class defined in the
program (_class.virtual_).
17.4.3.4 Replacement functions [lib.replacement.functions]
1 Clauses _lib.language.support_ through _lib.input.output_ describe the
behavior of numerous functions defined by the C++ Standard Library.
Under some circumstances, however, certain of these function descrip-
tions also apply to replacement functions defined in the program
(_lib.definitions_).
2 A C++ program may provide the definition for any of eight dynamic mem-
ory allocation function signatures declared in header <new>
(_basic.stc.dynamic_, clause _lib.language.support_):
--operator new(size_t)
--operator new(size_t, const std::nothrow_t&)
--operator new[](size_t)
--operator new[](size_t, const std::nothrow_t&)
--operator delete(void*)
--operator delete(void*, const std::nothrow_t&)
--operator delete[](void*)
--operator delete[](void*, const std::nothrow_t&)
3 The program's definitions are used instead of the default versions
supplied by the implementation (_dcl.fct.def_). Such replacement
occurs prior to program startup (_basic.def.odr_, _basic.start_).
17.4.3.5 Handler functions [lib.handler.functions]
1 The C++ Standard Library provides default versions of the following
handler functions (clause _lib.language.support_):
--unexpected_handler
--terminate_handler
2 A C++ program may install different handler functions during execu-
tion, by supplying a pointer to a function defined in the program or
the library as an argument to (respectively):
--set_new_handler
--set_unexpected
--set_terminate
SEE ALSO: subclauses _lib.alloc.errors_, Storage allocation errors,
and _lib.support.exception_, Exception handling.
17.4.3.6 Other functions [lib.res.on.functions]
1 In certain cases (replacement functions, handler functions, operations
on types used to instantiate standard library template components),
the C++ Standard Library depends on components supplied by a C++ pro-
gram. If these components do not meet their requirements, the Stan-
dard places no requirements on the implementation.
2 In particular, the effects are undefined in the following cases:
--for replacement functions (_lib.new.delete_), if the installed
replacement function does not implement the semantics of the appli-
cable Required behavior paragraph.
--for handler functions (_lib.new.handler_, _lib.terminate.handler_,
_lib.unexpected.handler_), if the installed handler function does
not implement the semantics of the applicable Required behavior
paragraph
--for types used as template arguments when instantiating a template
component, if the operations on the type do not implement the seman-
tics of the applicable Requirements subclause (_lib.alloca-
tor.requirements_, _lib.container.requirements_, _lib.itera-
tor.requirements_, _lib.numeric.requirements_). Operations on such
types can report a failure by throwing an exception unless otherwise
specified.
--if any replacement function or handler function or destructor opera-
tion throws an exception, unless specifically allowed in the appli-
cable Required behavior paragraph.
--if an incomplete type (_basic.types_) is used as a template argument
when instantiating a template component.
17.4.3.7 Function arguments [lib.res.on.arguments]
1 Each of the following statements applies to all arguments to functions
defined in the C++ Standard Library, unless explicitly stated other-
wise.
--If an argument to a function has an invalid value (such as a value
outside the domain of the function, or a pointer invalid for its
intended use), the behavior is undefined.
--If a function argument is described as being an array, 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.
17.4.3.8 Required paragraph [lib.res.on.required]
1 Violation of the preconditions specified in a function's Required
behavior paragraph results in undefined behavior unless the function's
Throws paragraph specifies throwing an exception when the precondition
is violated.
17.4.4 Conforming implementations [lib.conforming]
1 This subclause describes the constraints upon, and latitude of, imple-
mentations of the C++ Standard library. The following subclauses
describe an implementation's use of headers (_lib.res.on.headers_),
macros (_lib.res.on.macro.definitions_), global functions
(_lib.global.functions_), member functions (_lib.member.functions_),
reentrancy (_lib.reentrancy_), access specifiers (_lib.protec-
tion.within.classes_), class derivation (_lib.derivation_), and excep-
tions (_lib.res.on.exception.handling_).
17.4.4.1 Headers [lib.res.on.headers]
1 A C++ header may include other C++ headers.27)
2 Certain types and macros are defined in more than one header. For
such an entity, a second or subsequent header that also defines it may
be included after the header that provides its initial definition
(_basic.def.odr_).
3 Header inclusion is limited as follows:
--The C headers ( .h form, described in Annex D, _depr.c.headers_)
shall include only their corresponding C++ header, as described
above (_lib.headers_).
17.4.4.2 Restrictions on macro [lib.res.on.macro.definitions]
definitions
1 The names or global function signatures described in _lib.contents_
are reserved to the implementation.
2 All object-like macros defined by the Standard C library and described
in this clause as expanding to integral constant expressions are also
suitable for use in #if preprocessing directives, unless explicitly
stated otherwise.
17.4.4.3 Global functions [lib.global.functions]
1 It is unspecified whether any global functions in the C++ Standard
Library are defined as inline (_dcl.fct.spec_).
_________________________
27) C++ headers must include a C++ header that contains any needed
definition (_basic.def.odr_).
2 A call to a global function signature described in Clauses _lib.lan-
guage.support_ through _lib.input.output_ behaves the same as if the
implementation declares no additional global function signatures.28)
3 A global function cannot be declared by the implementation as taking
additional default arguments.
17.4.4.4 Member functions [lib.member.functions]
1 It is unspecified whether any member functions in the C++ Standard
Library are defined as inline (_dcl.fct.spec_).
2 An implementation can declare additional non-virtual member function
signatures within a class:
--by adding arguments with default values to a member function
signature;29) The same latitude does not extend to the implementa-
tion of virtual or global functions, however.
--by replacing a member function signature with default values by two
or more member function signatures with equivalent behavior;
--by adding a member function signature for a member function name.
3 A call to a member function signature described in the C++ Standard
library behaves the same as if the implementation declares no addi-
tional member function signatures.30)
17.4.4.5 Reentrancy [lib.reentrancy]
1 Which of the functions in the C++ Standard Library are not reentrant
subroutines is implementation-defined.
17.4.4.6 Protection within [lib.protection.within.classes]
classes
1 It is unspecified whether a function signature or class described in
clauses _lib.language.support_ through _lib.input.output_ is a friend
of another class in the C++ Standard Library.
_________________________
28) A valid C++ program always calls the expected library global func-
tion. An implementation may also define additional global functions
that would otherwise not be called by a valid C++ program.
29) Hence, taking the address of a member function has an unspecified
type.
30) A valid C++ program always calls the expected library member func-
tion, or one with equivalent behavior. An implementation may also de-
fine additional member functions that would otherwise not be called by
a valid C++ program.
17.4.4.7 Derived classes [lib.derivation]
1 It is unspecified whether a class in the C++ Standard Library is
itself derived from other classes (with names reserved to the imple-
mentation).
2 Certain classes defined in the C++ Standard Library are derived from
other classes in the C++ Standard Library:
--It is unspecified whether a class described in the C++ Standard
Library as derived from another class is derived from that class
directly, or through other classes (with names reserved to the
implementation) that are derived from the specified base class.
3 In any case:
--A base class described as virtual is always virtual;
--A base class described as virtual is never virtual;
--Unless explicitly stated otherwise, types with distinct names are
distinct types.31)
17.4.4.8 Restrictions on [lib.res.on.exception.handling]
exception handling
1 Any of the functions defined in the C++ Standard Library can report a
failure by throwing an exception of the type(s) described in their
Throws: paragraph and/or their exception-specification
(_except.spec_). An implementation may strengthen the exception-spec-
ification for a function by removing listed exceptions.32)
2 None of the functions from the Standard C library shall report an
error by throwing an exception,33) unless it calls a program-supplied
function that throws an exception.34)
3 No destructor operation defined in the C++ Standard Library will throw
an exception. Any other functions defined in the C++ Standard Library
that do not have an exception-specification may throw implementation-
_________________________
31) An implicit exception to this rule are types described as synonyms
for basic integral types, such as size_t (_lib.support.types_) and
streamoff (_lib.stream.types_).
32) That is, an implementation of the function will have an explicit
exception-specification that lists fewer exceptions than those speci-
fied in this International Standard. It may not, however, change the
types of exceptions listed in the exception-specficiation from those
specified, nor add others.
33) That is, the C library functions all have a throw() exception-
specification. This allows implementations to make performance opti-
mizations based on the absence of exceptions at runtime.
34) The functions qsort() and bsearch() (_lib.alg.c.library_) meet
this condition.
defined exceptions unless otherwise specified.35) An implementation
may strengthen this implicit exception-specification by adding an
explicit one.36)
_________________________
35) In particular, they can report a failure to allocate storage by
throwing an exception of type bad_alloc, or a class derived from
bad_alloc (_lib.bad.alloc_). Library implementations are encouraged
(but not required) to report errors by throwing exceptions from (or
derived from) the standard exception classes (_lib.bad.alloc_,
_lib.support.exception_, _lib.std.exceptions_).
36) That is, an implementation may provide an explicit exception-spec-
ification that defines the subset of ``any'' exceptions thrown by that
function. This implies that the implementation may list implementa-
tion-defined types in such an exception-specification.