______________________________________________________________________
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 (_except.intro_).
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 easily 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. Sub
clauses (_lib.requirements_) and (_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
conforming implementations.
17.1 Definitions [lib.definitions]
--category: A logical collection of library entities. Subclauses
_lib.language.support_ through _lib.input.output_ each describe a
single category of entities within the library.
--comparison function: An operator function (_over.oper_) for any of
the equality (_expr.eq_) or relational (_expr.rel_) operators.
--component: A group of library entities directly related as members,
parameters, or return types. For example, the class wstring and the
non-member functions that operate on wide-character strings can be
considered the wstring component.
--default behavior: A description of replacement function and handler
function semantics. Any specific behavior provided by the implemen
tation, within the scope of the required behavior.
--handler function: A non- 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 (_lib.language.support_).
--modifier function: A class member function (_class.mfct_), other
than constructors, assignment, or destructor, that alters the state
of an object of the class. The state of an object can be obtained
by using one or more observer functions
--observer function: A class member function (_class.mfct_) that
accesses the state of an object of the class, but does not alter
that state. Observer functions are specified as const member func
tions (_class.this_).
--replacement function: A non- 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 def
initions of all translation units (_basic.link_).
--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 func
tion definition in the program. If a function defined in a C++ pro
gram fails to meet the required behavior when it executes, the
behavior is undefined.
--reserved function: A function, specified as part of the C++ Standard
library, that must be defined by the implementation. If a C++ pro
gram provides a definition for any reserved function, the results
are undefined. Subclause _intro.defs_ defines additional terms used
elsewhere in this International Standard.
17.2 Method of description (Informative) [lib.description]
1 This subclause 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.structure_), conventions used to specify constraints on template
arguments(_lib.template.constraints_), conventions to describe types
defined by an implementation (_lib.implementation.types_), and other
editorial conventions (_lib.res.and.conventions_).
17.2.1 Structure of each subclause [lib.structure]
1 Subclause _lib.organization_ provides a summary of the C++ Standard
library's contents. Other Library clauses provide detailed specifica
tions 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
--Detailed specifications
--References to the Standard C library
_________________________
1) To save space, items that do not apply to a clause are omitted.
For example, if a clause does not specify any requirements on template
arguments, there will be no ``Requirements'' subclause.
17.2.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.2.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 XXX_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 interfce requires ``for any object x of class X, ++x is
defined.'' That is, whether the operator is a member or a global
function is unspecified.
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. Any generic algo
rithm that uses the requirements is described in terms of the valid
expressions for its formal type parameters.
5 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.2.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
--Decription 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
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
_________________________
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.
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.
--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
4 Complexity, the time and/or space complexity of the function
5 For non-reserved replacement and handler functions, this clause speci
fies two behaviors for the functions in question: their required and
default behavior. The default behavior describes a function defini
tion provided by the implementation. The required behavior describes
the semantics of a function definition provided by either the imple
mentation or a C++ program. Where no distinction is explicitly made
in the description, the behavior described is the required behavior.
6 If an operation is required to be linear time, it means no worse than
linear time, and a constant time operation satisfies the requirement.
17.2.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.2.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.descriptions_), class and class template member functions
(_lib.functions.within.classes_), private members
(_lib.objects.within.classes_), and convenient names
(_lib.unreserved.names_).
+------- BEGIN BOX 1 -------+
ISSUE: this subclause needs more discussion by the Library WG.
+------- END BOX 1 -------+
17.2.2.1 Type descriptions [lib.type.descriptions]
1 The Requirements subclauses describe names that are used to specify
constraints on template arguments. These names are used, instead of
the keyword class, to describe the types that may be supplied as argu
ments by a C++ program when instantiating template components from the
library.
2 Certain types defined in this clause are used to describe implementa
tion-defined types. They are based on other types, but with added
constraints.
17.2.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.
2 The enumerated type enumerated can be written:
enum secret {
V0, V1, V2, V3, .....};
typedef secret enumerated;
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.2.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.
2 The bitmask type bitmask can be written:
enum secret {
V0 = 1 << 0, V1 = 1 << 1, V2 = 1 << 2, V3 = 1 << 3, .....};
typedef secret bitmask;
static const bitmask C0(V0);
static const bitmask C1(V1);
static const bitmask C2(V2);
static const bitmask C3(V3);
.....
bitmask& operator&=(bitmask& X, bitmask Y)
{X = (bitmask)(X & Y); return (X); }
bitmask& operator|=(bitmask& X, bitmask Y)
{X = (bitmask)(X | Y); return (X); }
bitmask& operator^=(bitmask& X, bitmask Y)
{X = (bitmask)(X ^ Y); return (X); }
bitmask operator&(bitmask X, bitmask Y)
{return ((bitmask)(X & Y)); }
bitmask operator|(bitmask X, bitmask Y)
{return ((bitmask)(X | Y)); }
bitmask operator^(bitmask X, bitmask Y)
{return ((bitmask)(X ^ Y)); }
bitmask operator~(bitmask X)
{return ((bitmask)~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.2.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.6)
--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 this clause 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*), declared in <clo
cale>(_lib.c.locales_).
--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.2.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).7)
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.
_________________________
6) Note that this definition differs from the definition in ISO C sub
clause 7.1.1.
7) 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 value,
maintained separately from the character sequence.
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.8)
17.2.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.9)
2 A static NTMBS is an NTMBS with static storage duration.
17.2.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.fundmental_),
optionally qualified by any combination of const or volatile. The
initial elements of the array have defined contents up to and includ
ing 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.10)
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.11)
17.2.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
_________________________
8) A string literal, such as abc, is a static NTBS.
9) 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.
10) Many of the objects manipulated by function signatures declared in
<cwchar> are wide-character sequences or NTWCSs.
11) A wide string literal, such as L"abc", is a static NTWCS.
that can be generated by default.
3 For the sake of exposition, Clauses _lib.language.support_ through
_lib.input.output_ repeat in derived class declarations any virtual
member functions inherited from a base class. All such declarations
are enclosed in a comment that ends with inherited, as in:
// virtual void do_raise(); inherited
4 If a virtual member function in the base class meets the semantic
requirements of the derived class, it is unspecified whether the
derived class provides an overriding definition for the function sig
nature.
17.2.2.3 Private members [lib.objects.within.classes]
1 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, this clause provides representa
tive 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 in this clause are enclosed in a comment that
ends with exposition only, as in:
// streambuf* sb; exposition only
2 Any alternate implementation that provides equivalent external behav
ior is equally acceptable.
+------- BEGIN BOX 2 -------+
Editorial Proposal: Eliminate the ``exposition only'' implementation
specification. Instead, describe member function pre- and post-
conditions in terms of observer functions. Retained state, and side
effects to that state, will require careful wording.
+------- END BOX 2 -------+
17.2.2.4 Convenient names [lib.unreserved.names]
1 Certain types defined in C headers are sometimes needed to express
declarations in other headers, where the required type names are nei
ther defined nor reserved. In such cases, the implementation provides
a synonym for the required type, using a name reserved to the imple
mentation. Such cases are explicitly stated in this clause, and indi
cated by writing the required type name in constant-width italic char
acters.
2 Certain names are sometimes convenient to supply for the sake of expo
sition, in the descriptions in this clause, even though the names are
neither defined nor reserved. In such cases, the implementation
either omits the name, where that is permitted, or provides a name
reserved to the implementation. Such cases are also indicated in this
clause by writing the convenient name in constant-width italic charac
ters.
3 For example:
4 The class filebuf, defined in <fstream>, is described as containing
the private member object:
FILE* file;
5 This notation indicates that the member file is a pointer to the type
FILE, defined in <cstdio>, but the names file and FILE are neither
defined nor reserved in <fstream>. An implementation need not imple
ment class filebuf with an explicit member of type FILE*. If it does
so, it can choose 1) to replace the name file with a name reserved to
the implementation, and 2) to replace FILE with an incomplete type
whose name is reserved, such as in:
struct _Filet* _Fname;
6 If the program needs to have type FILE defined, it must also include
<cstdio>, which completes the definition of _Filet.
17.3 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.3.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.3.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 shall be defined within the namespace std.
3 The C++ Standard library provides 54 standard macros, as shown in
Table 2.
4 The header names (enclosed in < and >) indicate that the macro may be
defined in more than one header. All such definitions shall be equiv
alent (_basic.def.odr_).
Table 2--Standard Macros
+----------------------------------------------------------------------------+
|assert LC_ALL NULL <cstring> SIGILL va_arg |
|BUFSIZ LC_COLLATE NULL <ctime> SIGINT va_end |
|CLOCKS_PER_SEC LC_CTYPE NULL <cwchar> SIGSEGV va_start |
|EDOM LC_MONETARY offsetof SIGTERM WCHAR_MAX |
|EOF LC_NUMERIC RAND_MAX SIG_DFL WCHAR_MIN |
|ERANGE LC_TIME SEEK_CUR SIG_ERR WEOF <cwchar> |
|EXIT_FAILURE L_tmpnam SEEK_END SIG_IGN WEOF <cwctype> |
|EXIT_SUCCESS MB_CUR_MAX SEEK_SET stderr _IOFBF |
|FILENAME_MAX NDEBUG setjmp stdin _IOLBF |
|FOPEN_MAX NULL <cstddef> SIGABRT stdout _IONBF |
|HUGE_VAL NULL <cstdio> SIGFPE TMP_MAX |
+----------------------------------------------------------------------------+
5 The C++ Standard library provides 46 standard values, as shown in
Table 3:
Table 3--Standard Values
+---------------------------------------------------------------+
|CHAR_BIT FLT_DIG INT_MIN MB_LEN_MAX |
|CHAR_MAX FLT_EPSILON LDBL_DIG NPOS |
|CHAR_MIN FLT_MANT_DIG LDBL_EPSILON SCHAR_MAX |
|DBL_DIG FLT_MAX LDBL_MANT_DIG SCHAR_MIN |
|DBL_EPSILON FLT_MAX_10_EXP LDBL_MAX SHRT_MAX |
|DBL_MANT_DIG FLT_MAX_EXP LDBL_MAX_10_EXP SHRT_MIN |
|DBL_MAX FLT_MIN LDBL_MAX_EXP UCHAR_MAX |
|DBL_MAX_10_EXP FLT_MIN_10_EXP LDBL_MIN UINT_MAX |
|DBL_MAX_EXP FLT_MIN_DIG LDBL_MIN_10_EXP ULONG_MAX |
|DBL_MIN FLT_RADIX LDBL_MIN_DIG USHRT_MAX |
|DBL_MIN_10_EXP FLT_ROUNDS LONG_MAX |
|DBL_MIN_DIG INT_MAX LONG_MIN |
+---------------------------------------------------------------+
6 The C++ Standard library provides 51 standard types, as shown in Table
4:
Table 4--Standard Types
+--------------------------------------------------------------------------+
|clock_t new_handler streamoff wint_t <stddef> |
|div_t ofstream streampos wios |
|FILE ostream string wios |
|filebuf ostringstream stringbuf wistream |
|fpos_t ptrdiff_t <stddef> terminate_handler wistringstream |
|fvoid_t ptrdiff_t<cstddef> unexpected_handler wofstream |
|ifstream sig_atomic_t va_list wostream |
|ios size_t <cstddef> wctrans_t wostringstream |
|istream size_t <cstdio> wctype_t wstreambuf |
|istringstream size_t <cstring> wfilebuf wstreampos |
|jmp_buf size_t <ctime> wifstream wstring |
|ldiv_t size_t <stddef> wint_t <cwchar> wstringbuf |
|mbstate_t streambuf wint_t <cwctype> |
+--------------------------------------------------------------------------+
7 The C++ Standard library provides 68 standard template classes, as
shown in Table 5:
Table 5--Standard Template classes
+--------------------------------------------------+
|allocator mask_array |
|auto_ptr messages |
|back_insert_iterator messages_byname |
|basic_convbuf moneypunct |
|basic_filebuf moneypunct_byname |
|basic_ifstream money_get |
|basic_ios money_put |
|basic_istream multimap |
|basic_istringstream multiset |
|basic_ofstream numeric_limits |
|basic_ostream numpunct |
|basic_ostringstream num_get |
|basic_streambuf num_put |
|basic_string ostreambuf_iterator |
|basic_stringbuf ostream_iterator |
|binary_negate pointer_to_binary_function |
|binder1st pointer_to_unary_function |
|binder2nd priority_queue |
+--------------------------------------------------+
+-------------------------------------------------------+
|bits queue |
|codecvt raw_storage_iterator |
|codecvt_byname restrictor |
|collate reverse_bidirectional_iterator |
|collate_byname reverse_iterator |
|complex set |
|ctype slice_array |
|ctype_byname stack |
|deque time_get |
|front_insert_iterator time_get_byname |
|gslice_array time_put |
|indirect_array time_put_byname |
|insert_iterator unary_negate |
|istreambuf_iterator valarray |
|istream_iterator vector |
|list |
|map |
+-------------------------------------------------------+
8 The C++ Standard library provides 26 standard template structures, as
shown in Table 6:
Table 6--Standard Template structs
+------------------------------------------------------------------+
|bidirectional_iterator ios_conv_traits negate |
|binary_function ios_traits not_equal_to |
|conv_traits less pair |
|divides less_equal plus |
|equal_to logical_and random_access_iterator |
|forward_iterator logical_not string_char_traits |
|greater logical_or times |
|greater_equal minus unary_function |
|input_iterator modulus |
+------------------------------------------------------------------+
9 The C++ Standard library provides 78 standard template operator func
tions, as shown in Table 7.
10Types shown (enclosed in ( and ) ) indicate that the given function is
overloaded by that type. Numbers shown (enclosed in [ and ] ) indi
cate how many overloaded functions are overloaded by that type.
Table 7--Standard Template operators
+--------------------------------------------------------------------+
|operator!= (basic_string) [5] operator< (vector) |
|operator!= (complex) [3] operator<< (complex) |
|operator!= (istreambuf_iterator) operator<< (valarray) [3] |
|operator!= (ostreambuf_iterator) operator<<=(valarray) [2] |
|operator!= (T) operator<= (T) |
|operator!= (valarray) [3] operator<= (valarray) [3] |
|operator% (valarray) [3] operator== (basic_string) [5] |
|operator%= (valarray) [2] operator== (complex) [3] |
|operator& (valarray) [3] operator== (deque) |
|operator&& (valarray) [3] operator== (istreambuf_iterator) |
|operator&= (valarray) [2] operator== (istream_iterator) |
|operator* (complex) [3] operator== (list) |
|operator* (valarray) [3] operator== (map) |
|operator*= (complex) operator== (multimap) |
|operator*= (valarray) [2] operator== (multiset) |
|operator+ (basic_string) [5] operator== (ostreambuf_iterator) |
|operator+ (complex) [4] operator== (pair) |
|operator+ (reverse_iterator) operator== (queue) |
|operator+ (valarray) [3] operator== (restrictor) |
|operator+= (complex) operator== (reverse_bidir_iter) |
|operator+= (valarray) [2] operator== (reverse_iterator) |
|operator- (complex) [4] operator== (set) |
|operator- (reverse_iterator) operator== (stack) |
|operator- (valarray) [3] operator== (valarray) [3] |
|operator-= (complex) operator== (vector) |
|operator-= (valarray) [2] operator> (T) |
|operator/ (complex) [3] operator> (valarray) [3] |
|operator/ (valarray) [3] operator>= (T) |
|operator/= (complex) operator>= (valarray) [3] |
|operator/= (valarray) [2] operator>> (basic_string) |
|operator< (deque) operator>> (complex) |
|operator< (list) operator>> (valarray) [3] |
|operator< (map) operator>>=(valarray) [2] |
|operator< (multimap) operator^ (valarray) [3] |
|operator< (multiset) operator^= (valarray) [2] |
|operator< (pair) operator| (valarray) [3] |
|operator< (restrictor) operator|= (valarray) [2] |
|operator< (reverse_iterator) operator|| (valarray) [3] |
|operator< (set) |
|operator< (valarray) [3] |
+--------------------------------------------------------------------+
11The C++ Standard library provides 135 standard template functions, as
shown in Table 8:
Table 8--Standard Template functions
+-------------------------------------------------------------------+
|abs (complex) make_heap [2] |
|abs (valarray) make_pair |
|accumulate [2] max [2] |
|acos (valarray) max_element [2] |
|adjacent_difference [2] merge [2] |
|adjacent_find [2] min [2] |
|advance min_element [2] |
|allocate mismatch [2] |
|arg (complex) next_permutation [2] |
|asin (valarray) norm (complex) |
|atan (valarray) not1 |
|atan2(valarray) [3] not2 |
|back_inserter nth_element [2] |
|binary_search [2] partial_sort [2] |
|bind1st partial_sort_copy [2] |
|bind2nd partial_sum [2] |
|conj (complex) partition |
|construct polar(complex) |
|copy pop_heap [2] |
|copy_backward pow (complex) |
|cos (complex) pow (valarray) [3] |
|cos (valarray) prev_permutation [2] |
|cosh (complex) ptr_fun [2] |
|cosh (valarray) push_heap [2] |
|count random_shuffle [2] |
|count_if real (complex) |
|deallocate remove |
|destroy [2] remove_copy |
|distance remove_copy_if |
|distance_type (istreambuf_iterator) remove_if |
|distance_type [5] replace |
|equal [2] replace_copy |
|equal_range [2] replace_copy_if |
|exp (complex) replace_if |
|exp (valarray) reverse |
|fill reverse_copy |
|fill_n rotate |
|find rotate_copy |
|find_end [4] search [4] |
|find_first_of [2] set_difference [2] |
|find_if set_intersection [2] |
|for_each set_symmetric_difference [2] |
|front_inserter set_union [2] |
|generate sin (complex) |
+-------------------------------------------------------------------+
+---------------------------------------------------+
|generate_n sin (valarray) |
|get_temporary_buffer sinh (complex) |
|imag (complex) sinh (valarray) |
|includes [2] sort [2] |
|inner_product [2] sort_heap [2] |
|inplace_merge [2] sqrt (complex) |
|inserter sqrt (valarray) |
|isalnum stable_partition |
|isalpha stable_sort [2] |
|iscntrl swap |
|isdigit swap_ranges |
|isgraph tan (valarray) |
|islower tanh (valarray) |
|isprint tolower |
|ispunct toupper |
|isspace transform [2] |
|isupper uninitialized_copy |
|isxdigit uninitialized_fill_n |
|iterator_category [7] unique [2] |
|lexicographical_compare [2] unique_copy [2] |
|log (complex) unititialized_fill |
|log (valarray) upper_bound [2] |
|log10(valarray) value_type [7] |
|lower_bound [2] |
+---------------------------------------------------+
12The C++ Standard library provides 25 standard classes, as shown in
Table 9.
13Type names (enclosed in < and > ) indicate that these are specific
instances of templates.
Table 9--Standard Classes
+-----------------------------------------------------------------+
|bad_alloc exception out_of_range |
|bad_cast gslice overflow_error |
|bad_typeid invalid_argument range_error |
|complex<double> ios_base runtime_error |
|complex<float> length_error slice |
|complex<long double> locale type_info |
|ctype<char> locale::facet vector<bool,allocator> |
|ctype_byname<char> locale::id |
|domain_error logic_error |
+-----------------------------------------------------------------+
14The C++ Standard library provides 21 standard structures, as shown in
Table 10:
Table 10--Standard Structs
+----------------------------------------------------------+
|bidirectional_iterator_tag money_base |
|codecvt_base money_base::pattern |
|conv_traits<wchar_t> output_iterator |
|ctype_base output_iterator_tag |
|empty random_access_iterator_tag |
|forward_iterator_tag string_char_traits<char> |
|input_iterator_tag string_char_traits<wchar_t> |
|ios_conv_traits<wstreampos> time_base |
|ios_traits<char> tm <ctime> |
|ios_traits<wchar_t> tm <cwchar> |
|lconv |
+----------------------------------------------------------+
15The C++ Standard library provides 18 standard operator functions, as
shown in Table 11:
Table 11--Standard Operator functions
+--------------------------------------------------------------------------+
|operator delete operator<< (bits) |
|operator delete[] operator<< (locale) |
|operator new operator== (empty) |
|operator new (void*) operator== (vector<bool,allocator>) |
|operator new[] operator>> (bits) |
|operator new[] (void*) operator>> (locale) |
|operator& (bits) operator^ (bits) |
|operator< (empty) operator| (bits) |
|operator< (vector<bool,allocator>) |
|operator<< (basic_string) |
+--------------------------------------------------------------------------+
16The C++ Standard library provides 243 standard functions, as shown in
Table 12:
Table 12--Standard Functions
+------------------------------------------------------------+
|abort getenv oct strxfrm |
|abs getline perror swprintf |
|acos gets pow swscanf |
|asctime getwc printf system |
|asin getwchar putc tan |
|atan gmtime puts tanh |
|atan2 hex putwc terminate |
|atexit internal putwchar time |
|atof isalnum qsort tmpfile |
|atoi isalpha raise tmpnam |
|atol iscntrl rand tolower |
|bsearch isdigit realloc toupper |
|btowc isgraph remove towctrans |
|calloc islower rename towlower |
|ceil isprint resetiosflags towupper |
|clearerr ispunct rewind unexpected |
|clock isspace right ungetc |
|cos isupper scanf ungetwc |
|cosh iswalnum scientific uppercase |
|ctime iswalpha setbase vfwprintf |
|dec iswcntrl setbuf vprintf |
|difftime iswctype setfill vprintf |
|div iswdigit setiosflags vsprintf |
|endl iswgraph setlocale vswprintf |
|ends iswlower setprecision vwprintf |
|exit iswprint setvbuf wcrtomb |
|exp iswpunct setw wcscat |
|fabs iswspace set_new_handler wcschr |
|fclose iswupper set_terminate wcscmp |
|feof iswxdigit set_unexpected wcscoll |
|ferror isxdigit showbase wcscpy |
|fflush iterator_category showpoint wcscspn |
|fgetc labs showpos wcsftime |
|fgetpos ldexp signal wcslen |
|fgets ldiv sin wcsncat |
|fgetwc left sinh wcsncmp |
|fgetws localeconv skipws wcsncpy |
|fixed localtime sprintf wcspbrk |
|floor log sqrt wcsrchr |
|flush log10 srand wcsrtombs |
|fmod longjmp sscanf wcsspn |
|fopen malloc strcat wcsstr |
+------------------------------------------------------------+
+---------------------------------------------+
|fprintf mblen strchr wcstod |
|fputc mbrlen strcmp wcstok |
|fputs mbrtowc strcoll wcstol |
|fputwc mbsinit strcpy wcstombs |
|fputws mbsrtowcs strcspn wcstoul |
|fread mbstowcs strerror wcsxfrm |
|free mbtowc strftime wctob |
|freopen memchr strlen wctomb |
|frexp memcmp strncat wctrans |
|fscanf memcpy strncmp wctype |
|fseek memmove strncpy wmemchr |
|fsetpos memset stroul wmemcmp |
|ftell mktime strpbrk wmemcpy |
|fwide modf strrchr wmemmove |
|fwprintf noshowbase strspn wmemset |
|fwrite noshowpoint strstr wprintf |
|fwscanf noshowpos strtod ws |
|getc noskipws strtok wscanf |
|getchar nouppercase strtol |
+---------------------------------------------+
17The C++ Standard library provides 9 standard objects, as shown in
Table 13:
Table 13--Standard Objects
+------------------------------------------------------------+
|cerr cin clog cout errno werr win wlog wout |
+------------------------------------------------------------+
17.3.1.2 Headers [lib.headers]
1 The elements of the C++ Standard library are declared or defined (as
appropriate) in a header.
2 The C++ Standard library provides 34 C++ headers, as shown in Table
14:
_________________________
12) 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 14--C++ Library Headers
+-------------------------------------------------------------------+
|<algorithm> <functional> <limits> <ostream> <streambuf> |
|<bits> <iomanip> <list> <queue> <string> |
|<complex> <ios> <locale> <set> <typeinfo> |
|<cstream> <iosforward> <map> <sstream> <utility> |
|<deque> <iostream> <memory> <stack> <valarray> |
|<exception> <istream> <new> <stddef> <vector> |
|<fstream> <iterator> <numeric> <stdexcept> |
+-------------------------------------------------------------------+
3 The facilities of the Standard C Library are provided in 18 additional
headers, as shown in Table 15:
Table 15--C++ Headers for C Library Facilities
+--------------------------------------------------+
|<cassert> <ciso646> <csetjmp> <cstdio> <cwchar> |
|<cctype> <climits> <csignal> <cstdlib> <cwctype> |
|<cerrno> <clocale> <cstdarg> <cstring> |
|<cfloat> <cmath> <cstddef> <ctime> |
+--------------------------------------------------+
+------- BEGIN BOX 3 -------+
ISSUE: Header <ciso646> is not needed: see _lex.key_, Table 4.
+------- END BOX 3 -------+
4 Except as noted in Clauses _lib.language.support_ through
_lib.input.output_, the contents of each header c name shall be the
same as that of the corresponding header name .h, as specified in ISO
C (Clause 4), or Amendment 1, (Clause 7), as appropriate. In this C++
Standard library, however, the declarations and definitions are within
namespace scope (_basic.scope.namespace_) of the namespace std.
5 Subclause _diff.library_ describes the effects of using the name .h (C
header) form in a C++ program.
17.3.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 definesdescribes the set of available headers.
2 A freestanding implementation is one in which execution may take place
without the benefit of an operating system, and has an implementation-
defined set of headers. This set shall include at least the following
8 headers:
+------- BEGIN BOX 4 -------+
ISSUE: TBS. Requires a definition of a freestanding environment.
+------- END BOX 4 -------+
--the headers <new>, <exception>, and <typeinfo> that provide C++ lan
guage support (as described in _lib.language.support_)
--the C++ headers <cfloat>, <climits>, <cstdarg>, and <cstddef>
--a version of the C++ header <cstdlib> that declares at least the
functions abort, atexit, and exit.
17.3.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. Subclause _lib.using.headers_
describes effects during translation phase 4, while subclause
_lib.using.linkage_ describes effects during phase 8 (_lex.phases_).
17.3.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 (_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.
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.3.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 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.3.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_).
17.3.3.1 Reserved names [lib.reserved.names]
1 The C++ Standard library reserves the following kinds of names:
+------- BEGIN BOX 5 -------+
ISSUE: This topics needs further discussion. For example, implementa
tion names could be required to be in a separate implementation names
pace.
--Macros
--Global names
--Names with external linkage
2 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.3.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.13)
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.3.3.1.2 Global names [lib.global.names]
1 Each header also optionally declares or defines names which are always
reserved to the implementation for any use and names reserved to the
implementation for use at file scope.
2 Certain sets of names and function signatures are reserved whether or
not a translation unit includes a header:
3 Each name that begins with an underscore and either an uppercase let
ter or another underscore (_lex.key_) is reserved to the implementa
tion for any use.
4 Each name that begins with an underscore is reserved to the implemen
tation for use as a name with file scope or within the namespace std
_________________________
13) It is not permissible to remove a library macro definition by us
ing the #undef directive.
in the ordinary name space.
17.3.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.14)
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. 15)
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.
17.3.3.2 Headers [lib.alt.headers]
1 If a file has a name equivalent to the derived file name for one of
the C++ Standard library headers, is not provided as part of the
implementation, and is placed in any of the standard places for a
source file to be included (_cpp.include_), the behavior is undefined.
17.3.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 by definitions
in the program.
17.3.3.4 Replacement functions [lib.replacement.functions]
1 This clause describes the behavior of numerous functions defined by
the C++ Standard library. Under some circumstances, however, certain
of these function descriptions also apply to replacement functions
defined in the program (_lib.definitions_).
2 A C++ program may provide the definition for any of four dynamic mem
ory allocation function signatures declared in <new>
(_basic.stc.dynamic_, _lib.language.support_):16)
--operator new(size_t)
--operator new[](size_t)
--operator delete(void*)
_________________________
14) The list of such reserved names includes errno, declared or de
fined in <cerrno>.
15) 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>.
--operator delete[](void*)
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.3.3.5 Handler functions [lib.handler.functions]
1 The C++ Standard library provides default versions of the three han
dler functions (_lib.language.support_):
--new_handler
--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
3
17.3.3.6 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 in this clause.
--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.3.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_),
access specifiers (_lib.protection.within.classes_), class derivation
(_lib.derivation_), and exceptions (_lib.res.on.exception.handling_).
+------- BEGIN BOX 6 -------+
ISSUE: all of these have to be discussed by the Library WG.
+------- END BOX 6 -------+
17.3.4.1 Headers [lib.res.on.headers]
1 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.
2 None of the C headers includes any of the other headers, except that
each C header includes its corresponding C++ header, as described
above. None of the C++ headers includes any of the C headers. How
ever, any of the C++ headers can include any of the other C++ headers,
and must include a C++ header that contains any needed definition.16)
17.3.4.2 Restrictions on macro [lib.res.on.macro.definitions]
definitions
1 Only the names or global function signatures described in subclause
_lib.contents_ are reserved to the implementation.17)
2 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 #if preprocessing directives, unless
explicitly stated otherwise.
17.3.4.3 Global functions [lib.global.functions]
1 A call to a global function signature described in this clause behaves
the same as if the implementation declares no additional global func
tion signatures.18)
17.3.4.4 Member functions [lib.member.functions]
1 An implementation can declare additional non-virtual member function
signatures within a class:
_________________________
16) Including any one of the C++ headers can introduce all of the C++
headers into a translation unit, or just the one that is named in the
#include preprocessing directive.
17) A global function cannot be declared by the implementation as tak
ing additional default arguments. Also, the use of masking macros for
function signatures declared in C headers is disallowed, notwithstand
ing the latitude granted in subclause 7.1.7 of the C Standard. The
use of a masking macro can often be replaced by defining the function
signature as inline.
18) 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.
--by adding arguments with default values to a member function signa
ture described in this clause; Hence, taking the address of a member
function has an unspecified type. The same latitude does not extend
to the implementation 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
described in this clause.
2 A call to a member function signature described in this clause behaves
the same as if the implementation declares no additional member func
tion signatures.19)
17.3.4.5 Reentrancy [lib.reentrancy]
1 Which of the functions in the C++ Standard Library are not reentrant
subroutines is implementation-defined.
17.3.4.6 Protection within [lib.protection.within.classes]
classes
1 It is unspecified whether a member described in this clause as private
is private, protected, or public. It is unspecified whether a member
described as protected is protected or public.
+------- BEGIN BOX 7 -------+
Does this make any sense?
+------- END BOX 7 -------+
A member described as public is always public.
2 It is unspecified whether a function signature or class described in
this clause is a friend of another class described in this clause.
17.3.4.7 Derived classes [lib.derivation]
1 Certain classes defined in this clause are derived from other classes
in the C++ Standard library:
--It is unspecified whether a class described in this clause as a base
class is itself derived from other base classes (with names reserved
to the implementation).
--It is unspecified whether a class described in this clause as
derived from another class is derived from that class directly, or
_________________________
19) 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.
through other classes (with names reserved to the implementation)
that are derived from the specified base class.
2 In any case:
--A base class described as virtual in this clause is always virtual;
--A base class described as non-virtual in this clause is never vir
tual;
--Unless explicitly stated otherwise, types with distinct names in
this clause are distinct types.20)
17.3.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 to allocate storage by throwing an exception of type
bad_alloc, or a class derived from bad_alloc.
2 Otherwise, none of the functions defined in the C++ Standard library
throw an exception that must be caught outside the function, unless
explicitly stated otherwise.
+------- BEGIN BOX 8 -------+
ISSUE: aren't these two statements conveyed by exception specifica
tions?
+------- END BOX 8 -------+
_________________________
20) An implicit exception to this rule are types described as synonyms
for basic integral types, such as size_t and streamoff.