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 contains components for: language support, diagnostics, general utilities, 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 elements, such as a predefined storage allocator for dynamic storage management (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 represented as sequences of type char, sequences of type wchar_t, or sequences of any other ``character-like'' type. The localization components 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 structures.

-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 conforming implementations.

17.1 - Definitions [lib.definitions]

-1- intro.defs defines additional terms used elsewhere in this International 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.structure), 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 ??:

-2- Each Library clause contains the following elements, as applicable:*

[Footnote: To save space, items that do not apply to a clause are omitted. For example, if a clause does not specify any requirements, there will be no ``Requirements'' subclause. --- end foonote]

• Summary

• Requirements

• Detailed specifications

• References to the Standard C library

-1- The Summary provides a synopsis of the category, and introduces the first-level subclauses. Each subclause also provides a summary, listing the headers specified in the subclause and the library entities provided in each header.

-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

-1- The library can be extended by a C++ program. Each clause, as applicable, 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 convention

-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 operator++(),'' the interface requires ``for any object x of class X, ++x is defined.'' That is, whether the operator is a member 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 (lib.allocator.requirements, lib.container.requirements, lib.iterator.requirements). Any generic algorithm (clause lib.algorithms) that uses the requirements is described in terms of the valid expressions 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.*

[Footnote: Although in some cases the code given is unambiguously the optimum implementation. --- end foonote]

-1- The detailed specifications each contain the following elements:*

[Footnote: The form of these specifications was designed to follow the conventions established by existing C++ library vendors. --- end foonote]

• 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):*

[Footnote: 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. --- end foonote]

• 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):*

[Footnote: 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. --- end foonote]

• 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.language.support specifies two behaviors for the functions in question: their required and default behavior. The default behavior describes a function definition provided by the implementation. The required behavior describes the semantics of a function definition provided by either the implementation or a C++ program. Where no distinction is explicitly made in the description, the behavior described is the required behavior.

-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 relevant 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.descriptions), 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 specify constraints on template arguments.*

[Footnote: Examples from lib.utility.requirements include: EqualityComparable, LessThanComparable, CopyConstructable, etc. Examples from lib.iterator.requirements include: InputIterator, ForwardIterator, Function, Predicate, etc. --- end foonote]

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

[Footnote: Such as an integer type, with constant integer values (basic.fundamental). --- end foonote]

-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 overloads certain operators, as an integer type, or as a bitset (lib.template.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);
  .....

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

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

• A letter is any of the 26 lowercase or 26 uppercase letters in the basic execution character set.*

  [Footnote: Note that this definition differs from the definition in ISO C subclause 7.1.1. --- end foonote]

• The decimal-point character is the (single-byte) character used by functions that convert between a (single-byte) character sequence and a value of one of the floating-point types. It is used in the character sequence to denote the beginning of a fractional part. It is represented in clauses 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*),*

  [Footnote: declared in <clocale> (lib.c.locales). --- end foonote]

  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.

-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).*

[Footnote: 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. --- end foonote]

-2- The length of an NTBS is the number of elements that precede the terminating 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.*

[Footnote: A string literal, such as "abc", is a static NTBS. --- end foonote]

-1- A null-terminated multibyte string, or NTMBS, is an NTBS that constitutes a sequence of valid multibyte characters, beginning and ending in the initial shift state.*

[Footnote: An NTBS that contains characters only from the basic execution character set is also an NTMBS. Each multibyte character then consists of a single byte. --- end foonote]

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

[Footnote: Many of the objects manipulated by function signatures declared in <cwchar> are wide-character sequences or NTWCSs. --- end foonote]

-3- The length of an NTWCS is the number of elements that precede the terminating 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.*

[Footnote: A wide string literal, such as L"abc" , is a static NTWCS. --- end foonote]

-1- For the sake of exposition, clauses lib.language.support through lib.input.output do not describe copy constructors, assignment operators, or (non-virtual) destructors with the same apparent semantics as those that can be generated by default (class.ctor, class.dtor, class.copy).

-2- It is unspecified whether the implementation provides explicit definitions 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 specify the representation of classes, and intentionally omit specification 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.language.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 representative 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 exposition only , as in:

//	streambuf* sb;	 exposition only

-3- Any alternate implementation that provides equivalent external behavior is equally acceptable.

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 organization (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.*

[Footnote: 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). --- end foonote]

-2- The C++ Standard Library provides 32 C++ headers, as shown in Table ??:

-3- The facilities of the Standard C Library are provided in 18 additional headers, as shown in Table ??:

-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, however, 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 C grants license for implementation 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.*

[Footnote: This disallows the practice, allowed in C, of providing a "masking macro" in addition to the function prototype. The only way to achieve equivalent "inline" behavior in C++ is to provide a definition as an extern inline function. --- end foonote]

-7- depr.c.headers, Standard C library headers, describes the effects of using the name.h (C header) form in a C++ program.*

[Footnote: 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. --- end foonote]

-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 ??:

-3- The supplied version of the header <cstdlib> shall declare at least the functions abort(), atexit(), and exit() (lib.support.start.term).

17.4.2 - Using the library [lib.using]

-1- This subclause describes how a C++ program gains access to the facilities 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.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 current definition of NDEBUG.*

[Footnote: This is the same as the Standard C library. --- end foonote]

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

[Footnote: 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. --- end foonote]

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

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 standard library template to namespace std. Such a specialization (complete 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.*

[Footnote: Any library code that instantiates other library templates must be prepared to work adequately with any user-supplied specialization that meets the minimum requirements of the Standard. --- end foonote]

-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 behavior 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 implementation for any use if the translation unit includes the header.*

[Footnote: It is not permissible to remove a library macro definition by using the #undef directive. --- end foonote]

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

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 implementation for use as a name in the global namespace.*

  [Footnote: Such names are also reserved in namespace ::std (lib.reserved.names). --- end foonote]

-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,*

[Footnote: The list of such reserved names includes errno, declared or defined in <cerrno>. --- end foonote]

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

[Footnote: The list of such reserved function signatures with external linkage includes setjmp(jmp_buf), declared or defined in <csetjmp>, and va_end(va_list), declared or defined in <cstdarg>. --- end foonote]

-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 function signature with both extern "C" and extern "C++" linkage,*

[Footnote: The function signatures declared in <cwchar> and <cwctype> are always reserved, notwithstanding the restrictions imposed in subclause 4.5.1 of Amendment 1 to the C Standard for these headers. --- end foonote]

-1- For each type T from the Standard C library,*

[Footnote: These types are clock_t, div_t, FILE, fpos_t, lconv, ldiv_t, mbstate_t, ptrdiff_t, sig_atomic_t, size_t, time_t, tm, va_list, wctrans_t, wctype_t, and wint_t. --- end foonote]

-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 implementation, 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.

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 descriptions also apply to replacement functions defined in the program (lib.definitions).

-2- A C++ program may provide the definition for any of eight dynamic memory 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 execution, 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.

-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++ program. If these components do not meet their requirements, the Standard 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 applicable 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 semantics of the applicable Requirements subclause (lib.allocator.requirements, lib.container.requirements, lib.iterator.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 operation throws an exception, unless specifically allowed in the applicable Required behavior paragraph.

• if an incomplete type (basic.types) is used as a template argument when instantiating a template component.
  

-1- Each of the following statements applies to all arguments to functions defined in the C++ Standard Library, unless explicitly stated otherwise.

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

-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, implementations 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.protection.within.classes), class derivation (lib.derivation), and exceptions (lib.res.on.exception.handling).

17.4.4.1 - Headers [lib.res.on.headers]

-1- A C++ header may include other C++ headers.*

[Footnote: C++ headers must include a C++ header that contains any needed definition (basic.def.odr). --- end foonote]

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

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

-2- A call to a global function signature described in Clauses lib.language.support through lib.input.output behaves the same as if the implementation declares no additional global function signatures.*

[Footnote: A valid C++ program always calls the expected library global function. An implementation may also define additional global functions that would otherwise not be called by a valid C++ program. --- end foonote]

-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;*

  [Footnote: Hence, taking the address of a member function has an unspecified type. --- end foonote]

  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.

-3- A call to a member function signature described in the C++ Standard library behaves the same as if the implementation declares no additional member function signatures.*

[Footnote: A valid C++ program always calls the expected library member function, or one with equivalent behavior. An implementation may also define additional member functions that would otherwise not be called by a valid C++ program. --- end foonote]

-1- Which of the functions in the C++ Standard Library are not reentrant subroutines is implementation-defined.

17.4.4.6 - Protection within classes [lib.protection.within.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.

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 implementation).

-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 non-virtual is never virtual;

• Unless explicitly stated otherwise, types with distinct names are distinct types.*

  [Footnote: 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). --- end foonote]

-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-specification for a function by removing listed exceptions.*

[Footnote: That is, an implementation of the function will have an explicit exception-specification that lists fewer exceptions than those specified in this International Standard. It may not, however, change the types of exceptions listed in the exception-specficiation from those specified, nor add others. --- end foonote]

-2- None of the functions from the Standard C library shall report an error by throwing an exception,*

[Footnote: That is, the C library functions all have a throw() exception-specification. This allows implementations to make performance optimizations based on the absence of exceptions at runtime. --- end foonote]

[Footnote: The functions qsort() and bsearch() (lib.alg.c.library) meet this condition. --- end foonote]

-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-defined exceptions unless otherwise specified.*

[Footnote: 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). --- end foonote]

[Footnote: That is, an implementation may provide an explicit exception-specification that defines the subset of ``any'' exceptions thrown by that function. This implies that the implementation may list implementation-defined types in such an exception-specification. --- end foonote]