______________________________________________________________________

  17   Library introduction                                [lib.library]

  ______________________________________________________________________

1 This clause describes the contents of the C++ Standard Library, how  a
  well-formed C++ program makes use of the library, and how a conforming
  implementation may provide the entities in the library.

2 The C++ Standard Library provides an extensible  framework,  and  con-
  tains  components  for:  language support, diagnostics, general utili-
  ties, strings, locales, containers, iterators,  algorithms,  numerics,
  and  input/output.   The  language  support components are required by
  certain  parts  of  the  C++  language,  such  as  memory   allocation
  (_expr.new_,   _expr.delete_)   and   exception   processing   (clause
  _except_).

3 The general utilities include components used by  other  library  ele-
  ments, such as a predefined storage allocator for dynamic storage man-
  agement (_basic.stc.dynamic_).  The diagnostics components  provide  a
  consistent  framework for reporting errors in a C++ program, including
  predefined exception classes.

4 The strings components provide support for  manipulating  text  repre-
  sented  as  sequences  of  type  char,  sequences  of type wchar_t, or
  sequences of any other ``character-like'' type.  The localization com-
  ponents  extend internationalization support for such text processing.

5 The containers, iterators, and algorithms provide a C++  program  with
  access  to a subset of the most widely used algorithms and data struc-
  tures.

6 Numeric algorithms and the complex number  components  extend  support
  for  numeric  processing.  The valarray components provide support for
  n-at-a-time processing, potentially implemented as parallel operations
  on platforms that support such processing.

7 The  iostreams  components  are  the primary mechanism for C++ program
  input/output.  They can be used with other elements  of  the  library,
  particularly strings, locales, and iterators.

8 This  library  also  makes  available the facilities of the Standard C
  library, suitably adjusted to ensure static type safety.

9 The following subclauses describe the definitions (_lib.definitions_),
  and method of description (_lib.description_) for the library.  Clause
  _lib.requirements_   and   clauses   _lib.language.support_    through
  _lib.input.output_  specify  the  contents of the library, and library

  requirements and constraints on both well-formed C++ programs and con-
  forming implementations.

  17.1  Definitions                                    [lib.definitions]

  17.1.1  arbitrary-positional stream           [defns.arbitrary.stream]
  a stream (described in clause _lib.input.output_) that can seek to any
  integral position within the length of the stream.   Every  arbitrary-
  positional  stream  is  also  a  repositional  stream  (_defns.reposi-
  tional.stream_).

  17.1.2  character                                    [defns.character]
  in clauses _lib.strings_, _lib.localization_, and  _lib.input.output_,
  means any object which, when treated sequentially, can represent text.
  The term does not only mean char and wchar_t objects,  but  any  value
  that can be represented by a type that provides the definitions speci-
  fied in these clauses.

  17.1.3  character container type           [defns.character.container]
  a class or a type used to represent a  character  (_defns.character_).
  It  is  used  for  one  of  the  template parameters of the string and
  iostream class templates.  A character container class shall be a  POD
  (_basic.types_) type.

  17.1.4  comparison function                         [defns.comparison]
  an operator function (_over.oper_) for any of the equality (_expr.eq_)
  or relational (_expr.rel_) operators.

  17.1.5  component                                    [defns.component]
  a group of library entities directly related as  members,  parameters,
  or return types.  For example, the class template basic_string and the
  non-member template functions that operate on strings are referred  to
  as the string component.

  17.1.6  default behavior                      [defns.default.behavior]
  a  description of replacement function and handler function semantics.
  Any specific behavior provided by the implementation, within the scope
  of the required behavior.

  17.1.7  handler function                               [defns.handler]
  a reserved function whose definition may be provided by a C++ program.
  A C++ program may designate a handler function at  various  points  in
  its execution, by supplying a pointer to the function when calling any
  of the  library  functions  that  install  handler  functions  (clause
  _lib.language.support_).

  17.1.8  iostream class templates            [defns.iostream.templates]
  templates,  defined  in  clause _lib.input.output_, that take two tem-
  plate arguments: charT and traits.  The argument charT is a  character
  container  class, and the argument traits is a structure which defines
  additional characteristics and functions of the character type  repre-
  sented by charT necessary to implement the iostream class templates.

  17.1.9  modifier function                             [defns.modifier]
  a  class  member  function  (_class.mfct_),  other  than constructors,
  assignment, or destructor, that alters the state of an object  of  the
  class.

  17.1.10  object state                                [defns.obj.state]
  the  current  value  of  all  nonstatic  class  members  of  an object
  (_class.mem_).  The state of an object can be obtained by using one or
  more observer functions.

  17.1.11  narrow-oriented iostream classes
  the  instantiations  of  the iostream class templates on the character
  container class char and the default value of  the  traits  parameter.
  The  traditional  iostream classes are regarded as the narrow-oriented
  iostream classes (_lib.narrow.stream.objects_).

  17.1.12  NTCTS                                           [defns.ntcts]
  a sequence of values that have character type, that precede the termi-
  nating null character type value charT().

  17.1.13  observer function                            [defns.observer]
  a  class  member function (_class.mfct_) that accesses the state of an
  object of the class, but does not alter that  state.   Observer  func-
  tions are specified as const member functions (_class.this_).

  17.1.14  replacement function                      [defns.replacement]
  a  reserved  function  whose  definition is provided by a C++ program.
  Only one definition for such a function is in effect for the  duration
  of  the  program's  execution,  as  the result of creating the program
  (_lex.phases_) and resolving the definitions of all translation  units
  (_basic.link_).

  17.1.15  required behavior                   [defns.required.behavior]
  a  description of replacement function and handler function semantics,
  applicable to both the behavior provided by the implementation and the
  behavior that shall be provided by any function definition in the pro-
  gram.  If a function defined in  a  C++  program  fails  to  meet  the
  required behavior when it executes, the behavior is undefined.

  17.1.16  repositional stream               [defns.repositional.stream]
  a  stream  (described in clause _lib.input.output_) that can seek only
  to a position that was previously encountered.

  17.1.17  reserved function                   [defns.reserved.function]
  a function, specified as part of the C++ Standard Library,  that  must
  be defined by the implementation.  If a C++ program provides a defini-
  tion for any reserved function, the results are undefined.

  17.1.18  traits class                                   [defns.traits]
  a class that encapsulates a set of types and functions  necessary  for
  template classes and template functions to manipulate objects of types
  for which they are instantiated.  Traits classes  defined  in  clauses
  _lib.strings_, _lib.localization_ and _lib.input.output_ are chararac-
  ter traits, which provide the character handling support needed by the

  string and iostream classes.

  17.1.19  wide-oriented iostream classes
  the  instantiations  of  the iostream class templates on the character
  container class wchar_t and the default value of the traits  parameter
  (_lib.wide.stream.objects_).

  17.2  Additional definitions                        [defns.additional]
  _intro.defs_  defines additional terms used elsewhere in this Interna-
  tional Standard.

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

1 _lib.description_ describes the conventions used to describe  the  C++
  Standard  Library.   It  describes  the  structures  of  the normative
  clauses _lib.language.support_ through _lib.input.output_ (_lib.struc-
  ture_), and other editorial conventions (_lib.conventions_).

  17.3.1  Structure of each subclause                    [lib.structure]

1 _lib.organization_  provides  a  summary of the C++ Standard library's
  contents.  Other Library clauses provide detailed  specifications  for
  each of the components in the library, as shown in Table 1:

                       Table 1--Library Categories

               +-------------------------------------------+
               |        Clause               Category      |
               +-------------------------------------------+
               |_lib.language.support_   Language support  |
               |_lib.diagnostics_        Diagnostics       |
               |_lib.utilities_          General utilities |
               |_lib.strings_            Strings           |
               |_lib.localization_       Localization      |
               |_lib.containers_         Containers        |
               |_lib.iterators_          Iterators         |
               |_lib.algorithms_         Algorithms        |
               |_lib.numerics_           Numerics          |
               |_lib.input.output_       Input/output      |
               +-------------------------------------------+

2 Each Library clause contains the following elements, as applicable:1)

  --Summary

  --Requirements
  _________________________
  1)  To  save  space,  items that do not apply to a clause are omitted.
  For example, if a clause does not specify any requirements, there will
  be no ``Requirements'' subclause.

  --Detailed specifications

  --References to the Standard C library

  17.3.1.1  Summary                              [lib.structure.summary]

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

2 Paragraphs labelled ``Note(s):'' or ``Example(s):''  are  informative,
  other paragraphs are normative.

3 The  summary  and  the  detailed  specifications  are presented in the
  order:

  --Macros

  --Values

  --Types

  --Classes

  --Functions

  --Objects

  17.3.1.2  Requirements                    [lib.structure.requirements]

1 The library can be extended by a C++ program.  Each clause, as  appli-
  cable,  describes  the  requirements  that  such extensions must meet.
  Such extensions are generally one of the following:

  --Template arguments

  --Derived classes

  --Containers, iterators, and/or algorithms that meet an interface con-
    vention

2 The  string and iostreams components use an explicit representation of
  operations required of template arguments.  They use a template  class
  name char_traits to define these constraints.

3 Interface convention requirements are stated as generally as possible.
  Instead of stating ``class X has to define a  member  function  opera-
  tor++(),''  the  interface requires ``for any object x of class X, ++x
  is defined.''  That is, whether the operator is a member  is  unspeci-
  fied.

4 Requirements  are  stated  in terms of well-defined expressions, which
  define valid terms of the types that satisfy  the  requirements.   For

  every  set  of requirements there is a table that specifies an initial
  set  of  the  valid  expressions  and  their  semantics  (_lib.alloca-
  tor.requirements_,      _lib.container.requirements_,      _lib.itera-
  tor.requirements_).  Any generic algorithm  (clause  _lib.algorithms_)
  that  uses the requirements is described in terms of the valid expres-
  sions for its formal type parameters.

5 Template argument requirements are sometimes referenced by name.   See
  _lib.type.descriptions_.

6 In  some  cases  the  semantic requirements are presented as C++ code.
  Such code is intended as a specification of equivalence of a construct
  to another construct, not necessarily as the way the construct must be
  implemented.2)

  17.3.1.3  Specifications                [lib.structure.specifications]

1 The detailed specifications each contain the following elements:3)

  --Name and brief description

  --Synopsis (class definition or function prototype, as appropriate)

  --Restrictions on template arguments, if any

  --Description of class invariants

  --Description of function semantics

2 Descriptions  of  class  member  functions  follow   the   order   (as
  appropriate):4)

  --Constructor(s) and destructor

  --Copying & assignment functions

  --Comparison functions

  --Modifier functions

  --Observer functions

  --Operators and other non-member functions

  _________________________
  2) Although in some cases the code given is unambiguously the  optimum
  implementation.
  3) The form of these specifications was designed to follow the conven-
  tions established by existing C++ library vendors.
  4) To save space, items that do not apply to a class are omitted.  For
  example, if a class does not specify any comparison  functions,  there
  will be no ``Comparison functions'' subclause.

3 Descriptions of function semantics contain the following elements  (as
  appropriate):5)

  --Requires: the preconditions for calling the function

  --Effects: the actions performed by the function

  --Postconditions: the observable results established by the function

  --Returns: a description of the value(s) returned by the function

  --Throws:  any  exceptions  thrown by the function, and the conditions
    that would cause the exception

  --Complexity: the time and/or space complexity of the function

4 For non-reserved replacement and handler functions,  Clause  _lib.lan-
  guage.support_  specifies two behaviors for the functions in question:
  their required and default behavior.  The default behavior describes a
  function  definition  provided  by  the  implementation.  The required
  behavior describes the semantics of a function definition provided  by
  either  the  implementation or a C++ program.  Where no distinction is
  explicitly made in the description,  the  behavior  described  is  the
  required behavior.

5 Complexity  requirements  specified  in  the library clauses are upper
  bounds, and implementations that provide better complexity  guarantees
  satisfy the requirements.

  17.3.1.4  C Library                           [lib.structure.see.also]

1 Paragraphs labelled ``SEE ALSO:'' contain cross-references to the rel-
  evant portions of this Standard and  the  ISO  C  standard,  which  is
  incorporated into this Standard by reference.

  17.3.2  Other conventions                            [lib.conventions]

1 This   subclause  describes  several  editorial  conventions  used  to
  describe the contents of the C++ Standard Library.  These  conventions
  are  for  describing  implementation-defined types (_lib.type.descrip-
  tions_), and member functions (_lib.functions.within.classes_).

  17.3.2.1  Type descriptions                    [lib.type.descriptions]

1 The Requirements subclauses may describe names that are used to  spec-
  ify constraints on template  arguments.6)  These  names  are  used  in
  _________________________
  5)  To  save space, items that do not apply to a function are omitted.
  For example, if a function does not specify any  preconditions,  there
  will be no ``Requires'' paragraph.
  6)  Examples from _lib.utility.requirements_ include: EqualityCompara-
  ble,  LessThanComparable,  CopyConstructable,  etc.    Examples   from
  _lib.iterator.requirements_  include:  InputIterator, ForwardIterator,
  Function, Predicate, etc.

  clauses   _lib.utilities_,   _lib.containers_,  _lib.algorithms_,  and
  _lib.numerics_ to describe the types that may be supplied as arguments
  by  a  C++  program  when  instantiating  template components from the
  library.

2 Certain  types  defined  in  clause  _lib.input.output_  are  used  to
  describe implementation-defined types.  They are based on other types,
  but with added constraints.

  17.3.2.1.1  Enumerated types                    [lib.enumerated.types]

1 Several types defined  in  clause  _lib.input.output_  are  enumerated
  types.   Each  enumerated type may be implemented as an enumeration or
  as a synonym for an enumeration.7)

2 The enumerated type enumerated can be written:
  enum enumerated { V0, V1, V2, V3, .....};

  static const enumerated C0(V0);
  static const enumerated C1(V1);
  static const enumerated C2(V2);
  static const enumerated C3(V3);
    .....

3 Here,  the  names C0, C1, etc.  represent enumerated elements for this
  particular enumerated type.  All such elements have distinct values.

  17.3.2.1.2  Bitmask types                          [lib.bitmask.types]

1 Several types defined in clause _lib.input.output_ are bitmask  types.
  Each  bitmask type can be implemented as an enumerated type that over-
  loads certain operators, as an integer type, or as a bitset (_lib.tem-
  plate.bitset_).

2 The bitmask type bitmask can be written:
  enum bitmask {
    V0 = 1 << 0, V1 = 1 << 1, V2 = 1 << 2, V3 = 1 << 3, .....
  };

  static const bitmask C0(V0);
  static const bitmask C1(V1);
  static const bitmask C2(V2);
  static const bitmask C3(V3);
    .....

  _________________________
  7) Such as an integer type, with constant integer values  (_basic.fun-
  damental_).

  bitmask  operator& (bitmask  X, bitmask Y)
          // For exposition only.
          // int_type is an integral type capable of
          // representing all values of bitmask
          { return static_cast<bitmask>(
                       static_cast<int_type>(X) &
                       static_cast<int_type>(Y)); }
  bitmask  operator| (bitmask  X, bitmask Y)
          { return static_cast<bitmask>(
                       static_cast<int_type>(X) |
                       static_cast<int_type>(Y)); }
  bitmask  operator^ (bitmask  X, bitmask Y)
          { return static_cast<bitmask>(
                       static_cast<int_type>(X) ^
                       static_cast<int_type>(Y)); }
  bitmask  operator~ (bitmask  X)
          { return static_cast<bitmask>(static_cast<int_type>(~X)); }
  bitmask& operator&=(bitmask& X, bitmask Y)
          { X = X & Y; return X; }
  bitmask& operator|=(bitmask& X, bitmask Y)
          { X = X | Y; return X; }
  bitmask& operator^=(bitmask& X, bitmask Y)
          { X = X ^ Y; return X; }

3 Here, the names C0, C1, etc.  represent bitmask elements for this par-
  ticular  bitmask  type.   All  such elements have distinct values such
  that, for any pair Ci and Cj, Ci & Ci is nonzero and Ci & Cj is  zero.

4 The following terms apply to objects and values of bitmask types:

  --To  set  a value Y in an object X is to evaluate the expression X |=
    Y.

  --To clear a value Y in an object X is to evaluate the expression X &=
    ~Y.

  --The  value  Y  is  set  in  the  object X if the expression X & Y is
    nonzero.

  17.3.2.1.3  Character sequences                    [lib.character.seq]

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

  --A  letter  is any of the 26 lowercase or 26 uppercase letters in the
    basic execution character set.8)

  --The  decimal-point  character is the (single-byte) character used by
    functions that convert between a  (single-byte)  character  sequence
    and  a  value of one of the floating-point types.  It is used in the
  _________________________
  8) Note that this definition differs from the definition in ISO C sub-
  clause 7.1.1.

    character sequence to denote the beginning of a fractional part.  It
    is    represented    in   clauses   _lib.language.support_   through
    _lib.input.output_ by a period, '.', which is also its value in  the
    "C"  locale,  but  may  change during program execution by a call to
    setlocale(int, const char*),9) or by a change to a locale object, as
    described in clauses _lib.locales_ and _lib.input.output_.

  --A  character sequence is an array object (_dcl.array_) A that can be
    declared as T A[N], where T is any of the types char, unsigned char,
    or  signed  char  (_basic.fundamental_), optionally qualified by any
    combination of const or volatile.  The initial elements of the array
    have  defined  contents up to and including an element determined by
    some predicate.  A character sequence can be designated by a pointer
    value S that points to its first element.

  17.3.2.1.3.1  Byte strings                          [lib.byte.strings]

1 A  null-terminated byte string, or NTBS, is a character sequence whose
  highest-addressed element with defined content has the value zero (the
  terminating null character).10)

2 The length of an NTBS is the number of elements that precede the  ter-
  minating null character.  An empty NTBS has a length of zero.

3 The  value  of an NTBS is the sequence of values of the elements up to
  and including the terminating null character.

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

  17.3.2.1.3.2  Multibyte strings                [lib.multibyte.strings]

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

2 A static NTMBS is an NTMBS with static storage duration.

  17.3.2.1.3.3  Wide-character sequences           [lib.wide.characters]

1 A wide-character sequence is an array object (_dcl.array_) A that  can
  be  declared as T A[N], where T is type wchar_t (_basic.fundamental_),
  optionally qualified by any combination of  const  or  volatile.   The
  initial  elements  of  the  array  have  defined  contents  up  to and
  _________________________
  9) declared in <clocale> (_lib.c.locales_).
  10) Many of the objects manipulated by function signatures declared in
  <cstring> (_lib.c.strings_) are character  sequences  or  NTBSs.   The
  size  of some of these character sequences is limited by a length val-
  ue, maintained separately from the character sequence.
  11) A string literal, such as "abc", is a static NTBS.
  12) An NTBS that contains characters only  from  the  basic  execution
  character  set  is  also an NTMBS.  Each multibyte character then con-
  sists of a single byte.

  including  an  element  determined  by  some  predicate.   A character
  sequence can be designated by a pointer value S  that  designates  its
  first element.

2 A null-terminated wide-character string, or NTWCS, is a wide-character
  sequence whose highest-addressed element with defined content has  the
  value zero.13)

3 The length of an NTWCS is the number of elements that precede the ter-
  minating null wide character.  An empty NTWCS has a length of zero.

4 The  value of an NTWCS is the sequence of values of the elements up to
  and including the terminating null character.

5 A static NTWCS is an NTWCS with static storage duration.14)

  17.3.2.2  Functions within classes      [lib.functions.within.classes]

1 For  the  sake  of  exposition, clauses _lib.language.support_ through
  _lib.input.output_ do not describe copy constructors, assignment oper-
  ators,  or  (non-virtual) destructors with the same apparent semantics
  as those that can be generated by default (_class.ctor_, _class.dtor_,
  _class.copy_).

2 It is unspecified whether the implementation provides explicit defini-
  tions for such member function signatures, or for virtual  destructors
  that can be generated by default.

  17.3.2.3  Private members                 [lib.objects.within.classes]

1 Clauses _lib.language.support_ through _lib.input.output_ do not spec-
  ify the representation of classes, and intentionally  omit  specifica-
  tion  of  class  members  (_class.mem_).  An implementation may define
  static or non-static class members, or both, as  needed  to  implement
  the  semantics  of the member functions specified in clauses _lib.lan-
  guage.support_ through _lib.input.output_.

2 Objects of certain classes are  sometimes  required  by  the  external
  specifications  of  their  classes to store data, apparently in member
  objects.  For the sake of exposition, some subclauses  provide  repre-
  sentative  declarations, and semantic requirements, for private member
  objects of classes  that  meet  the  external  specifications  of  the
  classes.  The declarations for such member objects and the definitions
  of related member types are enclosed in a comment that ends with expo-
  sition only, as in:
  //      streambuf* sb;  exposition only

3 Any  alternate implementation that provides equivalent external behav-
  ior is equally acceptable.
  _________________________
  13) Many of the objects manipulated by function signatures declared in
  <cwchar> are wide-character sequences or NTWCSs.
  14) A wide string literal, such as L"abc", is a static NTWCS.

  17.4  Library-wide requirements                     [lib.requirements]

1 This subclause specifies requirements that apply  to  the  entire  C++
  Standard     library.     Clauses    _lib.language.support_    through
  _lib.input.output_ specify the  requirements  of  individual  entities
  within the library.

2 The following subclauses describe the library's contents and organiza-
  tion (_lib.organization_), how well-formed C++ programs gain access to
  library   entities   (_lib.using_),   constraints   on  such  programs
  (_lib.constraints_), and  constraints  on  conforming  implementations
  (_lib.conforming_).

  17.4.1  Library contents and organization           [lib.organization]

1 This  subclause  provides a summary of the entities defined in the C++
  Standard Library.  Subclause _lib.contents_ provides  an  alphabetical
  listing of entities by type, while subclause _lib.headers_ provides an
  alphabetical listing of library headers.

  17.4.1.1  Library contents                              [lib.contents]

1 The C++ Standard Library provides definitions for the following  types
  of  entities:  Macros,  Values,  Types, Templates, Classes, Functions,
  Objects.

2 All library entities except macros, operator new and  operator  delete
  are  defined  within  the  namespace  std  or namespaces nested within
  namespace std.

  17.4.1.2  Headers                                        [lib.headers]

1 The elements of the C++ Standard Library are declared or  defined  (as
  appropriate) in a header.15)

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

  _________________________
  15)  A  header is not necessarily a source file, nor are the sequences
  delimited by < and > in header names  necessarily  valid  source  file
  names (_cpp.include_).

                       Table 2--C++ Library Headers

   +------------------------------------------------------------------+
   |<algorithm>    <iomanip>    <list>      <ostream>     <streambuf> |
   |<bitset>       <ios>        <locale>    <queue>       <string>    |
   |<complex>      <iosfwd>     <map>       <set>         <typeinfo>  |
   |<deque>        <iostream>   <memory>    <sstream>     <utility>   |
   |<exception>    <istream>    <new>       <stack>       <valarray>  |
   |<fstream>      <iterator>   <numeric>   <stdexcept>   <vector>    |
   |<functional>   <limits>                                           |
   +------------------------------------------------------------------+

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

              Table 3--C++ Headers for C Library Facilities

           +--------------------------------------------------+
           |<cassert> <ciso646> <csetjmp> <cstdio>  <ctime>   |
           |<cctype>  <climits> <csignal> <cstdlib> <cwchar>  |
           |<cerrno>  <clocale> <cstdarg> <cstring> <cwctype> |
           |<cfloat>  <cmath>   <cstddef>                     |
           +--------------------------------------------------+

4 Except    as   noted   in   clauses   _lib.language.support_   through
  _lib.input.output_, the contents of each header  cname  shall  be  the
  same  as  that  of  the  corresponding  header name.h, as specified in
  ISO/IEC 9899:1990 Programming Languages C (Clause 7), or  ISO/IEC:1990
  Programming  Languages--C  AMENDMENT  1:  C  Integrity, (Clause 7), as
  appropriate, as if by inclusion.  In the C++  Standard  Library,  how-
  ever,  the  declarations  and  definitions (except for names which are
  defined   as   macros   in   C)    are    within    namespace    scope
  (_basic.scope.namespace_) of the namespace std.

5 Names  which  are defined as macros in C shall be defined as macros in
  the C++ Standard Library, even if license is granted in C  for  imple-
  mentation  as  functions.   [Note:  the  names  defined as macros in C
  include  the  following:  assert,  errno,  offsetof,  setjmp,  va_arg,
  va_end, and va_start.   --end note]

6 Names that are defined as functions in C shall be defined as functions
  in the C++ Standard Library.16)

  _________________________
  16) This disallows the practice, allowed in C, of providing a "masking
  macro" in addition to the function prototype.  The only way to achieve
  equivalent "inline" behavior in C++ is to provide a definition  as  an
  extern inline  function.

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

  17.4.1.3  Freestanding implementations                [lib.compliance]

1 Two  kinds  of  implementations  are  defined: hosted and freestanding
  (_intro.compliance_).  For a hosted implementation, this International
  Standard describes the set of available headers.

2 A  freestanding  implementation  has  an implementation-defined set of
  headers.  This set shall include at least the  following  headers,  as
  shown in Table 4:

          Table 4--C++ Headers for Freestanding Implementations

     +--------------------------------------------------------------+
     |                   Subclause                       Header(s)  |
     +--------------------------------------------------------------+
     |_lib.support.types_ Types                         <cstddef>   |
     +--------------------------------------------------------------+
     |_lib.support.limits_ Implementation properties    <limits>    |
     +--------------------------------------------------------------+
     |_lib.support.start.term_ Start and termination    <cstdlib>   |
     +--------------------------------------------------------------+
     |_lib.support.dynamic_ Dynamic memory management   <new>       |
     +--------------------------------------------------------------+
     |_lib.support.rtti_ Type identification            <typeinfo>  |
     +--------------------------------------------------------------+
     |_lib.support.exception_ Exception handling        <exception> |
     +--------------------------------------------------------------+
     |_lib.support.runtime_ Other runtime support       <cstdarg>   |
     +--------------------------------------------------------------+

3 The  supplied  version  of the header <cstdlib> shall declare at least
  the   functions   abort(),    atexit(),    and    exit()    (_lib.sup-
  port.start.term_).

  17.4.2  Using the library                                  [lib.using]

1 This subclause describes how a C++ program gains access to the facili-
  ties of  the  C++  Standard  Library.   _lib.using.headers_  describes
  effects   during   translation   phase  4,  while  _lib.using.linkage_
  describes effects during phase 8 (_lex.phases_).

  _________________________
  17) The ".h" headers dump all their names into the  global  namespace,
  whereas the newer forms keep their names in namespace std.  Therefore,
  the newer forms are the preferred forms for all uses  except  for  C++
  programs which are intended to be strictly compatible with C.

  17.4.2.1  Headers                                  [lib.using.headers]

1 The entities in the C++ Standard Library are defined in headers, whose
  contents are made available to a translation unit when it contains the
  appropriate #include preprocessing directive (_cpp.include_).

2 A translation unit may include library headers in  any  order  (clause
  _lex_).  Each may be included more than once, with no effect different
  from being included exactly once, except that the effect of  including
  either <cassert> or <assert.h> depends each time on the lexically cur-
  rent definition of NDEBUG.18)

3 A translation unit shall include a header only outside of any external
  declaration  or  definition,  and  shall  include the header lexically
  before the first reference to any of the entities it declares or first
  defines in that translation unit.

  17.4.2.2  Linkage                                  [lib.using.linkage]

1 Entities   in   the   C++   Standard  Library  have  external  linkage
  (_basic.link_).  Unless otherwise  specified,  objects  and  functions
  have the default extern "C++" linkage (_dcl.link_).

2 It  is unspecified whether a name from the Standard C library declared
  with  external  linkage  has  either  extern  "C"  or   extern   "C++"
  linkage.19)

3 Objects and functions defined in the library and  required  by  a  C++
  program are included in the program prior to program startup.

  SEE ALSO:  replacement  functions  (_lib.replacement.functions_), run-
  time changes (_lib.handler.functions_).

  17.4.3  Constraints on programs                      [lib.constraints]

1 This subclause describes restrictions on C++  programs  that  use  the
  facilities  of  the  C++  Standard  Library.  The following subclauses
  specify constraints on the program's namespace (_lib.reserved.names_),
  its  use of headers (_lib.alt.headers_), classes derived from standard
  library classes (_lib.derived.classes_),  definitions  of  replacement
  functions  (_lib.replacement.functions_),  and installation of handler
  functions during execution (_lib.handler.functions_).

  _________________________
  18) This is the same as the Standard C library.
  19)  The  only reliable way to declare an object or function signature
  from the Standard C library is by including the header  that  declares
  it,  notwithstanding  the latitude granted in subclause 7.1.7 of the C
  Standard.

  17.4.3.1  Reserved names                          [lib.reserved.names]

1 It is undefined for a C++ program to add declarations  or  definitions
  to  namespace  std or namespaces within namespace std unless otherwise
  specified.  A program may add template specializations for  any  stan-
  dard  library  template to namespace std.  Such a specialization (com-
  plete or partial) of a standard library template results in  undefined
  behavior  unless  the  declaration  depends  on a user-defined name of
  external linkage and unless  the  specialization  meets  the  standard
  library requirements for the original template.20)

2 The C++ Standard Library reserves the following kinds of names:

  --Macros

  --Global names

  --Names with external linkage

3 If  the  program  declares  or defines a name in a context where it is
  reserved, other than as explicitly allowed by this clause, the  behav-
  ior is undefined.

  17.4.3.1.1  Macro names                              [lib.macro.names]

1 Each  name defined as a macro in a header is reserved to the implemen-
  tation for any use if the translation unit includes the header.21)

2 A translation unit that includes a header shall not contain any macros
  that define names declared or defined in that header.  Nor shall  such
  a translation unit define macros for names lexically identical to key-
  words.

  17.4.3.1.2  Global names                            [lib.global.names]

1 Certain sets of names and function signatures are always  reserved  to
  the implementation:

  --Each  name  that  contains a double underscore __) or begins with an
    underscore followed by an uppercase letter (_lex.key_)  is  reserved
    to the implementation for any use.

  --Each  name  that begins with an underscore is reserved to the imple-
    mentation for use as a name in the global namespace.22)

  _________________________
  20) Any library code that instantiates other library templates must be
  prepared to work adequately with any user-supplied specialization that
  meets the minimum requirements of the Standard.
  21) It is not permissible to remove a library macro definition by  us-
  ing the #undef directive.
  22)  Such  names  are  also  reserved  in  namespace  ::std  (_lib.re-
  served.names_).

  17.4.3.1.3  External linkage                        [lib.extern.names]

1 Each name declared as an object with external linkage in a  header  is
  reserved  to  the implementation to designate that library object with
  external  linkage,23)  both  in namespace std and in the global names-
  pace.

2 Each global function signature declared with  external  linkage  in  a
  header  is  reserved  to the implementation to designate that function
  signature with external linkage.24)

3 Each name having two consecutive underscores (_lex.key_)  is  reserved
  to  the  implementation  for  use  as  a name with both extern "C" and
  extern "C++" linkage.

4 Each name from the Standard C library declared with  external  linkage
  is  reserved  to  the implementation for use as a name with extern "C"
  linkage, both in namespace std and in the global namespace.

5 Each function signature from the  Standard  C  library  declared  with
  external  linkage is reserved to the implementation for use as a func-
  tion signature with both extern "C" and extern "C++" linkage,25) or as
  a name of namespace scope in the global namespace.

  17.4.3.1.4  Types                                   [lib.extern.types]

1 For  each  type  T  from  the Standard C library,26) the types ::T and
  std::T are reserved to the implementation and, when defined, ::T shall
  be identical to std::T.

  17.4.3.2  Headers                                    [lib.alt.headers]

1 If  a  file with a name equivalent to the derived file name for one of
  the C++ Standard Library headers is not provided as part of the imple-
  mentation,  and a file with that name is placed in any of the standard
  places for a source file to be included (_cpp.include_), the  behavior
  is undefined.

  _________________________
  23) The list of such reserved names includes errno,  declared  or  de-
  fined in <cerrno>.
  24) The list of such reserved function signatures with external  link-
  age  includes  setjmp(jmp_buf),  declared or defined in <csetjmp>, and
  va_end(va_list), declared or defined in <cstdarg>.
  25) The function signatures declared in <cwchar> and <cwctype> are al-
  ways  reserved,  notwithstanding the restrictions imposed in subclause
  4.5.1 of Amendment 1 to the C Standard for these headers.
  26)  These  types are clock_t, div_t, FILE, fpos_t, lconv, ldiv_t, mb-
  state_t, ptrdiff_t, sig_atomic_t, size_t,  time_t,  tm,  va_list,  wc-
  trans_t, wctype_t, and wint_t.

  17.4.3.3  Derived classes                        [lib.derived.classes]

1 Virtual member function signatures defined for a base class in the C++
  Standard  library  may be overridden in a derived class defined in the
  program (_class.virtual_).

  17.4.3.4  Replacement functions            [lib.replacement.functions]

1 Clauses _lib.language.support_ through _lib.input.output_ describe the
  behavior  of  numerous  functions defined by the C++ Standard Library.
  Under some circumstances, however, certain of these function  descrip-
  tions  also  apply  to  replacement  functions  defined in the program
  (_lib.definitions_).

2 A C++ program may provide the definition for any of eight dynamic mem-
  ory   allocation   function   signatures   declared  in  header  <new>
  (_basic.stc.dynamic_, clause _lib.language.support_):

  --operator new(size_t)

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

  --operator new[](size_t)

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

  --operator delete(void*)

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

  --operator delete[](void*)

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

3 The program's definitions are used instead  of  the  default  versions
  supplied  by  the  implementation  (_dcl.fct.def_).   Such replacement
  occurs prior to program startup (_basic.def.odr_, _basic.start_).

  17.4.3.5  Handler functions                    [lib.handler.functions]

1 The C++ Standard Library provides default versions  of  the  following
  handler functions (clause _lib.language.support_):

  --unexpected_handler

  --terminate_handler

2 A  C++  program  may install different handler functions during execu-
  tion, by supplying a pointer to a function defined in the  program  or
  the library as an argument to (respectively):

  --set_new_handler

  --set_unexpected

  --set_terminate

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

  17.4.3.6  Other functions                       [lib.res.on.functions]

1 In certain cases (replacement functions, handler functions, operations
  on types used to instantiate standard  library  template  components),
  the  C++ Standard Library depends on components supplied by a C++ pro-
  gram.  If these components do not meet their requirements,  the  Stan-
  dard places no requirements on the implementation.

2 In particular, the effects are undefined in the following cases:

  --for  replacement  functions  (_lib.new.delete_),  if  the  installed
    replacement function does not implement the semantics of the  appli-
    cable Required behavior paragraph.

  --for  handler  functions (_lib.new.handler_, _lib.terminate.handler_,
    _lib.unexpected.handler_), if the installed  handler  function  does
    not  implement  the  semantics  of  the applicable Required behavior
    paragraph

  --for types used as template arguments when instantiating  a  template
    component, if the operations on the type do not implement the seman-
    tics  of  the  applicable   Requirements   subclause   (_lib.alloca-
    tor.requirements_,     _lib.container.requirements_,     _lib.itera-
    tor.requirements_, _lib.numeric.requirements_).  Operations on  such
    types can report a failure by throwing an exception unless otherwise
    specified.

  --if any replacement function or handler function or destructor opera-
    tion  throws an exception, unless specifically allowed in the appli-
    cable Required behavior paragraph.

  --if an incomplete type (_basic.types_) is used as a template argument
    when instantiating a template component.

  17.4.3.7  Function arguments                    [lib.res.on.arguments]

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

  --If  an  argument to a function has an invalid value (such as a value
    outside the domain of the function, or a  pointer  invalid  for  its
    intended use), the behavior is undefined.

  --If  a  function argument is described as being an array, the pointer
    actually passed to the function shall have a  value  such  that  all
    address computations and accesses to objects (that would be valid if
    the pointer did point to the first element of such an array) are  in
    fact valid.

  17.4.3.8  Required paragraph                     [lib.res.on.required]

1 Violation of the preconditions  specified  in  a  function's  Required
  behavior paragraph results in undefined behavior unless the function's
  Throws paragraph specifies throwing an exception when the precondition
  is violated.

  17.4.4  Conforming implementations                    [lib.conforming]

1 This subclause describes the constraints upon, and latitude of, imple-
  mentations of the C++  Standard  library.   The  following  subclauses
  describe  an  implementation's  use of headers (_lib.res.on.headers_),
  macros     (_lib.res.on.macro.definitions_),     global      functions
  (_lib.global.functions_),  member  functions (_lib.member.functions_),
  reentrancy   (_lib.reentrancy_),   access   specifiers   (_lib.protec-
  tion.within.classes_), class derivation (_lib.derivation_), and excep-
  tions (_lib.res.on.exception.handling_).

  17.4.4.1  Headers                                 [lib.res.on.headers]

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

2 Certain  types  and  macros  are defined in more than one header.  For
  such an entity, a second or subsequent header that also defines it may
  be  included  after  the  header  that provides its initial definition
  (_basic.def.odr_).

3 Header inclusion is limited as follows:

  --The C headers ( .h form, described  in  Annex  D,  _depr.c.headers_)
    shall  include  only  their  corresponding  C++ header, as described
    above (_lib.headers_).

  17.4.4.2  Restrictions on macro         [lib.res.on.macro.definitions]
       definitions

1 The  names  or  global function signatures described in _lib.contents_
  are reserved to the implementation.

2 All object-like macros defined by the Standard C library and described
  in  this clause as expanding to integral constant expressions are also
  suitable for use in #if preprocessing  directives,  unless  explicitly
  stated otherwise.

  17.4.4.3  Global functions                      [lib.global.functions]

1 It  is  unspecified  whether  any global functions in the C++ Standard
  Library are defined as inline (_dcl.fct.spec_).

  _________________________
  27) C++ headers must include a C++ header  that  contains  any  needed
  definition (_basic.def.odr_).

2 A  call  to a global function signature described in Clauses _lib.lan-
  guage.support_ through _lib.input.output_ behaves the same as  if  the
  implementation declares no additional global function signatures.28)

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

  17.4.4.4  Member functions                      [lib.member.functions]

1 It is unspecified whether any member functions  in  the  C++  Standard
  Library are defined as inline (_dcl.fct.spec_).

2 An  implementation  can declare additional non-virtual member function
  signatures within a class:

  --by adding  arguments  with  default  values  to  a  member  function
    signature;29) The same latitude does not extend to  the  implementa-
    tion of virtual or global functions, however.

  --by  replacing a member function signature with default values by two
    or more member function signatures with equivalent behavior;

  --by adding a member function signature for a member function name.

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

  17.4.4.5  Reentrancy                                  [lib.reentrancy]

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

  17.4.4.6  Protection within            [lib.protection.within.classes]
       classes

1 It  is  unspecified whether a function signature or class described in
  clauses _lib.language.support_ through _lib.input.output_ is a  friend
  of another class in the C++ Standard Library.

  _________________________
  28) A valid C++ program always calls the expected library global func-
  tion.  An implementation may also define additional  global  functions
  that would otherwise not be called by a valid C++ program.
  29)  Hence, taking the address of a member function has an unspecified
  type.
  30) A valid C++ program always calls the expected library member func-
  tion, or one with equivalent behavior.  An implementation may also de-
  fine additional member functions that would otherwise not be called by
  a valid C++ program.

  17.4.4.7  Derived classes                             [lib.derivation]

1 It is unspecified whether a class  in  the  C++  Standard  Library  is
  itself  derived  from other classes (with names reserved to the imple-
  mentation).

2 Certain classes defined in the C++ Standard Library are  derived  from
  other classes in the C++ Standard Library:

  --It  is  unspecified  whether  a  class described in the C++ Standard
    Library as derived from another class is  derived  from  that  class
    directly,  or  through  other  classes  (with  names reserved to the
    implementation) that are derived from the specified base class.

3 In any case:

  --A base class described as virtual is always virtual;

  --A base class described as virtual is never virtual;

  --Unless explicitly stated otherwise, types with  distinct  names  are
    distinct types.31)

  17.4.4.8  Restrictions on              [lib.res.on.exception.handling]
       exception handling

1 Any of the functions defined in the C++ Standard Library can report  a
  failure  by  throwing  an  exception of the type(s) described in their
  Throws:     paragraph     and/or     their     exception-specification
  (_except.spec_).  An implementation may strengthen the exception-spec-
  ification for a function by removing listed exceptions.32)

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

3 No destructor operation defined in the C++ Standard Library will throw
  an exception.  Any other functions defined in the C++ Standard Library
  that  do not have an exception-specification may throw implementation-
  _________________________
  31) An implicit exception to this rule are types described as synonyms
  for basic integral types, such  as  size_t  (_lib.support.types_)  and
  streamoff (_lib.stream.types_).
  32) That is, an implementation of the function will have  an  explicit
  exception-specification  that lists fewer exceptions than those speci-
  fied in this International Standard.  It may not, however, change  the
  types  of  exceptions listed in the exception-specficiation from those
  specified, nor add others.
  33)  That  is,  the  C library functions all have a throw() exception-
  specification.  This allows implementations to make performance  opti-
  mizations based on the absence of exceptions at runtime.
  34) The functions qsort()  and  bsearch()  (_lib.alg.c.library_)  meet
  this condition.

  defined exceptions unless otherwise  specified.35)  An  implementation
  may  strengthen  this  implicit  exception-specification  by adding an
  explicit one.36)

  _________________________
  35)  In  particular,  they can report a failure to allocate storage by
  throwing an exception of type  bad_alloc,  or  a  class  derived  from
  bad_alloc  (_lib.bad.alloc_).   Library implementations are encouraged
  (but not required) to report errors by throwing  exceptions  from  (or
  derived   from)   the  standard  exception  classes  (_lib.bad.alloc_,
  _lib.support.exception_, _lib.std.exceptions_).
  36) That is, an implementation may provide an explicit exception-spec-
  ification that defines the subset of ``any'' exceptions thrown by that
  function.  This implies that the implementation may  list  implementa-
  tion-defined types in such an exception-specification.