      ______________________________________________________________________

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

    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

      conforming implementations.

      17.1  Definitions                                    [lib.definitions]

      --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  template
        basic_string  and  the non-member template functions that operate on
        strings are referred to as the string 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.

      --object 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

      --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.   Clause  _intro.defs_ defines additional terms used
        elsewhere in this International Standard.

      17.2  Method of description (Informative)            [lib.description]

    1 Clause _lib.description_ describes the conventions  used  to  describe
      the  C++  Standard library.  It describes the structures of the norma-
      tive   Clauses   _lib.language.support_   through   _lib.input.output_
      (_lib.structure_),   and  other  editorial  conventions  (_lib.conven-
      tions_).

      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

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

      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 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  (_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.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

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

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

      --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.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.descrip-
      tions_), and member functions (_lib.functions.within.classes_).

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

      _________________________
      6)  Examples from _lib.utility.requirements_ include: EqualityCompara-
      ble,  LessThanComparable,  CopyConstructable,  etc.    Examples   from
      _lib.iterator.requirements_  include:  InputIterator, ForwardIterator,
      Function, Predicate, etc.

      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.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.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, 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);
        .....
      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 |=
      _________________________
      7)  Such as an integer type, with constant integer values (_basic.fun-
      damental_).

        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.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
        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.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).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.
      _________________________
      8) Note that this definition differs from the definition in ISO C sub-
      clause 7.1.1.
      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.

    4 A static NTBS is an NTBS with static storage duration.11)

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

    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.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.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
      that can be generated by default.

      _________________________
      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.
      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.2.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 rep-
      resentative  declarations, and semantic requirements, for private mem-
      ber 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.

      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 except macros, operator new and  operator  delete
      are  defined  within  the  namespace  std  or namespaces nested within
      namespace std.

      17.3.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:

                           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, 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 license is granted in C  for  imple-
      mentation  as  functions.   [Note:  the  names  defined as macros in C
      _________________________
      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_).

      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)

    7 Subclause  _depr.c.headers_, Standard C library headers, describes the
      effects of using the name.h (C header) form in a C++ program.17)

      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 describes the set of available headers.

    2 A freestanding implementation has 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_).
      _________________________
      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.
      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.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.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.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 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.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
      _________________________
      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.

      functions (_lib.replacement.functions_), and installation  of  handler
      functions during execution (_lib.handler.functions_).

      17.3.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
      behaviour 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.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.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.3.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 begins with an underscore  and  either  an  uppercase
        letter  or  another underscore (_lex.key_) is reserved to the imple-
        mentation for any use.

      --Each name that begins with an underscore is reserved to  the  imple-
        mentation  for use as a name with file scope or within the namespace
      _________________________
      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.

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

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

    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.

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

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

      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 defined in the
      program (_class.virtual_).

      17.3.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
      _________________________
      22)  The  list  of such reserved names includes errno, declared or de-
      fined in <cerrno>.
      23) 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>.
      24) 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.

      (_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_, _lib.language.support_):

      --operator new(size_t)

      --operator new(size_t,std::nothrow_t&)

      --operator new[](size_t)

      --operator new[](size_t,std::nothrow_t&)

      --operator delete(void*)

      --operator delete(void*,std::nothrow_t&)

      --operator delete[](void*)

      --operator delete[](void*,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.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

      SEE ALSO: subclauses _lib.alloc.errors_,  Storage  allocation  errors,
      and _lib.support.exception_, Exception handling.

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

      --if  any of these functions or operations throws an exception, unless
        specifically allowed in the applicable Required behavior  paragraph.

      17.3.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.3.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.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_),
      reentrancy   (_lib.reentrancy_),   access   specifiers   (_lib.protec-
      tion.within.classes_), class derivation (_lib.derivation_), and excep-
      tions (_lib.res.on.exception.handling_).

      17.3.4.1  Headers                                 [lib.res.on.headers]

    1 A C++ header may include other C++ headers.25)

    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.3.4.2  Restrictions on macro         [lib.res.on.macro.definitions]
           definitions

    1 The  names  or  global  function  signatures  described  in  subclause
      _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.3.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.lan-
      guage.support_  through  _lib.input.output_ behaves the same as if the
      implementation declares no additional global function signatures.26)

      _________________________
      25) C++ headers must include a C++ header  that  contains  any  needed
      definition (_basic.def.odr_).
      26) 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.

    3 A  global  function cannot be declared by the implementation as taking
      additional default arguments.

      17.3.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;27) 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.28)

    4 Throughout    the   C++   Library   clauses   (_lib.library_   through
      _lib.input.output_), whenever a template member function  is  declared
      with one or more default arguments, this is to be understood as speci-
      fying a set of two or more overloaded template member functions.   The
      version  with  the most parameters defines the interface; the versions
      with fewer parameters are to be understood  as  functions  with  fewer
      parameters, in which the corresponding default argument is substituted
      in-place.  [Example: From _lib.set.cons_:

      explicit set(const Compare &comp = Compare(),
                   const Allocator& = Allocator());

      This declaration is to be understood as a shorthand for the  following
      three declarations:

      explicit set(const Compare& comp, const Allocator&);
      explicit set(const Compare& comp);
      explicit set();

      _________________________
      27)  Hence, taking the address of a member function has an unspecified
      type.
      28) 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.

      In  the  second and third declarations, the default values Allocator()
      and Compare() are used in  place  of  the  missing  explicit  function
      parameters.   --end example]

      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 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.3.4.7  Derived classes                             [lib.derivation]
      It  is  unspecified  whether  a  class  in the C++ Standard Library is
      itself derived from other classes (with names reserved to  the  imple-
      mentation).

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

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

      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 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.30)
      _________________________
      29) 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_).
      30)  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

    2 None  of  the  functions  from  the Standard C library shall report an
      error by throwing an exception,31) unless it calls a  program-supplied
      function that throws an exception.32)

    3 Any of the functions defined in the C++ Standard library that  do  not
      have   an  exception-specification  may  throw  implementation-defined
      exceptions.33)  An  implementation may strengthen this implicit excep-
      tion-specification by adding an explicit one.34)

      _________________________
      specified, nor add others.
      31) 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.
      32)  The  functions  qsort()  and bsearch() (_lib.alg.c.library_) meet
      this condition.
      33) 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_).
      34) 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.