20 - General utilities library [lib.utilities]

-1- This clause describes components used by other elements of the Standard C++ library. These components may also be used by C++ programs.

-2- The following clauses describe utility and allocator requirements, utility components, function objects, dynamic memory management utilities, and date/time utilities, as summarized in Table ??:

20.1 - Requirements [lib.utility.requirements]

-1- lib.utility.requirements describes requirements on template arguments. lib.equalitycomparable through lib.copyconstructible describe requirements on types used to instantiate templates. lib.allocator.requirements describes the requirements on storage allocators.

20.1.1 - Equality comparison [lib.equalitycomparable]

-1- In Table ??, T is a type to be supplied by a C++ program instantiating a template, a, b and c are values of type T.

20.1.2 - Less than comparison [lib.lessthancomparable]

-1- In the following Table ??, T is a type to be supplied by a C++ program instantiating a template, a and b are values of type T.

20.1.3 - Copy construction [lib.copyconstructible]

-1- In the following Table ??, T is a type to be supplied by a C++ program instantiating a template, t is a value of type T, and u is a value of type const T.

20.1.4 - Default construction [lib.default.con.req]

-1- The default constructor is not required. Certain container class member function signatures specify the default constructor as a default argument. T() must be a well-defined expression (dcl.init) if one of those signatures is called using the default argument (dcl.fct.default).

20.1.5 - Allocator requirements [lib.allocator.requirements]

-1- The library describes a standard set of requirements for allocators, which are objects that encapsulate the information about an allocation model. This information includes the knowledge of pointer types, the type of their difference, the type of the size of objects in this allocation model, as well as the memory allocation and deallocation primitives for it. All of the containers (clause lib.containers) are parameterized in terms of allocators.

-2- Table ?? describes the requirements on types manipulated through allocators. All the operations on the allocators are expected to be amortized constant time. Table ?? describes the requirements on allocator types.

[Footnote: It is intended that a.allocate be an efficient means of allocating a single object of type T , even when sizeof(T) is small. That is, there is no need for a container to maintain its own ``free list''. --- end foonote]

-3- The template class member rebind in the table above is effectively a template typedef: if the name Allocator is bound to SomeAllocator<T>, then Allocator::rebind<U>::other is the same type as SomeAllocator<U>.

-4- Implementations of containers described in this International Standard are permitted to assume that their Allocator template parameter meets the following two additional requirements beyond those in Table ??.

• All instances of a given allocator type are required to be interchangeable and always compare equal to each other.

• The typedef members pointer, const_pointer, size_type, and difference_type are required to be T*, T const*, size_t, and ptrdiff_t, respectively.

-5- Implementors are encouraged to supply libraries that can accept allocators that encapsulate more general memory models and that support non-equal instances. In such implementations, any requirements imposed on allocators by containers beyond those requirements that appear in Table ??, and the semantics of containers and algorithms when allocator instances compare non-equal, are implementation-defined.

20.2 - Utility components [lib.utility]

-1- This subclause contains some basic template functions and classes that are used throughout the rest of the library.

Header <utility> synopsis

namespace std {
  //  lib.operators, operators:
  namespace rel_ops {
    template<class T> bool operator!=(const T&, const T&);
    template<class T> bool operator> (const T&, const T&);
    template<class T> bool operator<=(const T&, const T&);
    template<class T> bool operator>=(const T&, const T&);
  }

  //  lib.pairs, pairs:
  template <class T1, class T2> struct pair;
  template <class T1, class T2>
    bool operator==(const pair<T1,T2>&, const pair<T1,T2>&);
  template <class T1, class T2>
    bool operator< (const pair<T1,T2>&, const pair<T1,T2>&);
  template <class T1, class T2>
    bool operator!=(const pair<T1,T2>&, const pair<T1,T2>&);
  template <class T1, class T2>
    bool operator> (const pair<T1,T2>&, const pair<T1,T2>&);
  template <class T1, class T2>
    bool operator>=(const pair<T1,T2>&, const pair<T1,T2>&);
  template <class T1, class T2>
    bool operator<=(const pair<T1,T2>&, const pair<T1,T2>&);
  template <class T1, class T2> pair<T1,T2> make_pair(const T1&, const T2&);
}

-1- To avoid redundant definitions of operator!= out of operator== and operators >, <=, and >= out of operator<, the library provides the following:

template <class T> bool operator!=(const T& x, const T& y);

-2- Requires: Type T is EqualityComparable (lib.equalitycomparable).

-3- Returns: !(x == y).

template <class T> bool operator>(const T& x, const T& y);

-4- Requires: Type T is LessThanComparable (lib.lessthancomparable).

-5- Returns: y < x.

template <class T> bool operator<=(const T& x, const T& y);

-6- Requires: Type T is LessThanComparable (lib.lessthancomparable).

-7- Returns: !(y < x).

template <class T> bool operator>=(const T& x, const T& y);

-8- Requires: Type T is LessThanComparable (lib.lessthancomparable).

-9- Returns: !(x < y).

-10- In this library, whenever a declaration is provided for an operator!=, operator>, operator>=, or operator<=, and requirements and semantics are not explicitly provided, the requirements and semantics are as specified in this clause.

20.2.2 - Pairs [lib.pairs]

-1- The library provides a template for heterogeneous pairs of values. The library also provides a matching template function to simplify their construction.

template <class T1, class T2>
struct pair {
  typedef T1 first_type;
  typedef T2 second_type;

  T1 first;
  T2 second;
  pair();
  pair(const T1& x, const T2& y);
  template<class U, class V> pair(const pair<U, V> &p);
};

-2- Effects: Initializes its members as if implemented: pair() : first(T1()), second(T2()) {}

pair(const T1& x, const T2& y);

-3- Effects: The constructor initializes first with x and second with y .

template<class U, class V> pair(const pair<U, V> &p);

-4- Effects: Initializes members from the corresponding members of the argument, performing implicit conversions as needed.

template <class T1, class T2>
  bool operator==(const pair<T1, T2>& x, const pair<T1, T2>& y);

-5- Returns: x.first == y.first && x.second == y.second.

template <class T1, class T2>
  bool operator<(const pair<T1, T2>& x, const pair<T1, T2>& y);

-6- Returns: x.first < y.first || (!(y.first < x.first) && x.second < y.second).

template <class T1, class T2>
  pair<T1, T2> make_pair(const T1& x, const T2& y);

-7- Returns: pair<T1, T2>(x, y).

-8- [Example: In place of:

  return pair<int, double>(5, 3.1415926);   //  explicit types

  return make_pair(5, 3.1415926);           //  types are deduced

-1- Function objects are objects with an operator() defined. They are important for the effective use of the library. In the places where one would expect to pass a pointer to a function to an algorithmic template (clause lib.algorithms), the interface is specified to accept an object with an operator() defined. This not only makes algorithmic templates work with pointers to functions, but also enables them to work with arbitrary function objects.

Header <functional> synopsis

namespace std {
  //  lib.base, base:
  template <class Arg, class Result> struct unary_function;
  template <class Arg1, class Arg2, class Result> struct binary_function;

  //  lib.arithmetic.operations, arithmetic operations:
  template <class T> struct plus;
  template <class T> struct minus;
  template <class T> struct multiplies;
  template <class T> struct divides;
  template <class T> struct modulus;
  template <class T> struct negate;

  //  lib.comparisons, comparisons:
  template <class T> struct equal_to;
  template <class T> struct not_equal_to;
  template <class T> struct greater;
  template <class T> struct less;
  template <class T> struct greater_equal;
  template <class T> struct less_equal;

  //  lib.logical.operations, logical operations:
  template <class T> struct logical_and;
  template <class T> struct logical_or;
  template <class T> struct logical_not;

  //  lib.negators, negators:
  template <class Predicate> struct unary_negate;
  template <class Predicate>
    unary_negate<Predicate>  not1(const Predicate&);
  template <class Predicate> struct binary_negate;
  template <class Predicate>
    binary_negate<Predicate> not2(const Predicate&);

  //  lib.binders, binders:
  template <class Operation>  class binder1st;
  template <class Operation, class T>
    binder1st<Operation> bind1st(const Operation&, const T&);
  template <class Operation> class binder2nd;
  template <class Operation, class T>
    binder2nd<Operation> bind2nd(const Operation&, const T&);

  //  lib.function.pointer.adaptors, adaptors:
  template <class Arg, class Result> class pointer_to_unary_function;
  template <class Arg, class Result>
    pointer_to_unary_function<Arg,Result> ptr_fun(Result (*)(Arg));
  template <class Arg1, class Arg2, class Result>
    class pointer_to_binary_function;
  template <class Arg1, class Arg2, class Result>
    pointer_to_binary_function<Arg1,Arg2,Result>
      ptr_fun(Result (*)(Arg1,Arg2));

  //  lib.member.pointer.adaptors, adaptors:
  template<class S, class T> class mem_fun_t;
  template<class S, class T, class A> class mem_fun1_t;
  template<class S, class T>
      mem_fun_t<S,T> mem_fun(S (T::*f)());
  template<class S, class T, class A>
      mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A));
  template<class S, class T> class mem_fun_ref_t;
  template<class S, class T, class A> class mem_fun1_ref_t;
  template<class S, class T>
      mem_fun_ref_t<S,T> mem_fun_ref(S (T::*f)());
  template<class S, class T, class A>
      mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A));

  template <class S, class T> class const_mem_fun_t;
  template <class S, class T, class A> class const_mem_fun1_t;
  template <class S, class T>
    const_mem_fun_t<S,T> mem_fun(S (T::*f)() const);
  template <class S, class T, class A>
    const_mem_fun1_t<S,T,A> mem_fun(S (T::*f)(A) const);
  template <class S, class T> class const_mem_fun_ref_t;
  template <class S, class T, class A> class const_mem_fun1_ref_t;
  template <class S, class T>
    const_mem_fun_ref_t<S,T> mem_fun_ref(S (T::*f)() const);
  template <class S, class T, class A>
    const_mem_fun1_ref_t<S,T,A> mem_fun_ref(S (T::*f)(A) const);
}

-2- Using function objects together with function templates increases the expressive power of the library as well as making the resulting code much more efficient.

-3- [Example: If a C++ program wants to have a by-element addition of two vectors a and b containing double and put the result into a, it can do:

  transform(a.begin(), a.end(), b.begin(), a.begin(), plus<double>());

-4- [Example: To negate every element of a:

  transform(a.begin(), a.end(), a.begin(), negate<double>());

-5- To enable adaptors and other components to manipulate function objects that take one or two arguments it is required that the function objects correspondingly provide typedefs argument_type and result_type for function objects that take one argument and first_argument_type, second_argument_type , and result_type for function objects that take two arguments.

20.3.1 - Base [lib.base]

-1- The following classes are provided to simplify the typedefs of the argument and result types:

  template <class Arg, class Result>
  struct unary_function {
    typedef Arg    argument_type;
    typedef Result result_type;
  };

  template <class Arg1, class Arg2, class Result>
  struct binary_function {
    typedef Arg1   first_argument_type;
    typedef Arg2   second_argument_type;
    typedef Result result_type;
  };

-1- The library provides basic function object classes for all of the arithmetic operators in the language (expr.mul, expr.add).

template <class T> struct plus : binary_function<T,T,T> {
  T operator()(const T& x, const T& y) const;
};

-2- operator() returns x + y.

template <class T> struct minus : binary_function<T,T,T> {
  T operator()(const T& x, const T& y) const;
};

-3- operator() returns x - y.

template <class T> struct multiplies : binary_function<T,T,T> {
  T operator()(const T& x, const T& y) const;
};

-4- operator() returns x * y.

template <class T> struct divides : binary_function<T,T,T> {
  T operator()(const T& x, const T& y) const;
};

-5- operator() returns x / y.

template <class T> struct modulus : binary_function<T,T,T> {
  T operator()(const T& x, const T& y) const;
};

-6- operator() returns x % y.

template <class T> struct negate : unary_function<T,T> {
  T operator()(const T& x) const;
};

-7- operator() returns -x.

20.3.3 - Comparisons [lib.comparisons]

-1- The library provides basic function object classes for all of the comparison operators in the language (expr.rel, expr.eq).

template <class T> struct equal_to : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-2- operator() returns x == y.

template <class T> struct not_equal_to : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-3- operator() returns x != y.

template <class T> struct greater : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-4- operator() returns x > y.

template <class T> struct less : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-5- operator() returns x < y.

template <class T> struct greater_equal : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-6- operator() returns x >= y.

template <class T> struct less_equal : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-7- operator() returns x <= y.

-8- For templates greater, less, greater_equal, and less_equal, the specializations for any pointer type yield a total order, even if the built-in operators <, >, <=, >= do not.

20.3.4 - Logical operations [lib.logical.operations]

-1- The library provides basic function object classes for all of the logical operators in the language (expr.log.and, expr.log.or, expr.unary.op).

template <class T> struct logical_and : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-2- operator() returns x && y.

template <class T> struct logical_or : binary_function<T,T,bool> {
  bool operator()(const T& x, const T& y) const;
};

-3- operator() returns x || y.

template <class T> struct logical_not : unary_function<T,bool> {
  bool operator()(const T& x) const;
};

-4- operator() returns !x.

20.3.5 - Negators [lib.negators]

-1- Negators not1 and not2 take a unary and a binary predicate, respectively, and return their complements (expr.unary.op).

template <class Predicate>
  class unary_negate
    : public unary_function<typename Predicate::argument_type,bool> {
public:
  explicit unary_negate(const Predicate& pred);
  bool operator()(const typename Predicate::argument_type& x) const;
};

-2- operator() returns !pred(x).

template <class Predicate>
  unary_negate<Predicate> not1(const Predicate& pred);

-3- Returns: unary_negate<Predicate>(pred).

template <class Predicate>
  class binary_negate
    : public binary_function<typename Predicate::first_argument_type,
        typename Predicate::second_argument_type, bool> {
  public:
    explicit binary_negate(const Predicate& pred);
    bool operator()(const typename Predicate::first_argument_type&  x,
        const typename Predicate::second_argument_type& y) const;
  };

-4- operator() returns !pred(x,y).

template <class Predicate>
  binary_negate<Predicate> not2(const Predicate& pred);

-5- Returns: binary_negate<Predicate>(pred).

20.3.6 - Binders [lib.binders]

-1- Binders bind1st and bind2nd take a function object f of two arguments and a value x and return a function object of one argument constructed out of f with the first or second argument correspondingly bound to x.

20.3.6.1 - Template class binder1st [lib.binder.1st]

  template <class Operation>
  class binder1st
    : public unary_function<typename Operation::second_argument_type,
                            typename Operation::result_type> {
  protected:
    Operation                      op;
    typename Operation::first_argument_type value;

  public:
    binder1st(const Operation& x,
              const typename Operation::first_argument_type& y);
    typename Operation::result_type
      operator()(const typename Operation::second_argument_type& x) const;
  };

-1- The constructor initializes op with x and value with y .

-2- operator() returns op(value,x).

20.3.6.2 - bind1st [lib.bind.1st]

-1- Returns: binder1st<Operation>(op, typename Operation::first_argument_type(x)).

20.3.6.3 - Template class binder2nd [lib.binder.2nd]

  template <class Operation>
  class binder2nd
    : public unary_function<typename Operation::first_argument_type,
                            typename Operation::result_type> {
  protected:
    Operation                       op;
    typename Operation::second_argument_type value;

  public:
    binder2nd(const Operation& x,
              const typename Operation::second_argument_type& y);
    typename Operation::result_type
      operator()(const typename Operation::first_argument_type& x) const;
  };

-1- The constructor initializes op with x and value with y .

-2- operator() returns op(x,value).

20.3.6.4 - bind2nd [lib.bind.2nd]

-1- Returns: binder2nd<Operation>(op, typename Operation::second_argument_type(x)).

-2- [Example:

  find_if(v.begin(), v.end(), bind2nd(greater<int>(), 5));

  find_if(v.begin(), v.end(), bind1st(greater<int>(), 5));

-1- To allow pointers to (unary and binary) functions to work with function adaptors the library provides:

  template <class Arg, class Result>
  class pointer_to_unary_function : public unary_function<Arg, Result> {
  public:
    explicit pointer_to_unary_function(Result (*f)(Arg));
    Result operator()(Arg x) const;
  };

-2- operator() returns f(x).

template <class Arg, class Result>
  pointer_to_unary_function<Arg, Result> ptr_fun(Result (*f)(Arg));

-3- Returns: pointer_to_unary_function<Arg, Result>(f).

  template <class Arg1, class Arg2, class Result>
  class pointer_to_binary_function :
    public binary_function<Arg1,Arg2,Result> {
  public:
    explicit pointer_to_binary_function(Result (*f)(Arg1, Arg2));
    Result operator()(Arg1 x, Arg2 y) const;
  };

-4- operator() returns f(x,y).

template <class Arg1, class Arg2, class Result>
  pointer_to_binary_function<Arg1,Arg2,Result>
    ptr_fun(Result (*f)(Arg1, Arg2));

-5- Returns: pointer_to_binary_function<Arg1,Arg2,Result>(f).

-6- [Example:

replace_if(v.begin(), v.end(), not1(bind2nd(ptr_fun(strcmp), "C")), "C++");

[Footnote: Implementations that have multiple pointer to function types provide additional ptr_fun template functions. --- end foonote]

-1- The purpose of the following is to provide the same facilities for pointer to members as those provided for pointers to functions in lib.function.pointer.adaptors.

template <class S, class T> class mem_fun_t
        : public unary_function<T*, S> {
public:
  explicit mem_fun_t(S (T::*p)());
  S operator()(T* p) const;
};

-2- mem_fun_t calls the member function it is initialized with given a pointer argument.

  template <class S, class T, class A> class mem_fun1_t
        : public binary_function<T*, A, S> {
  public:
    explicit mem_fun1_t(S (T::*p)(A));
    S operator()(T* p, A x) const;
};

-3- mem_fun1_t calls the member function it is initialized with given a pointer argument and an additional argument of the appropriate type.

  template<class S, class T> mem_fun_t<S,T>
     mem_fun(S (T::*f)());

  template<class S, class T, class A> mem_fun1_t<S,T,A>
     mem_fun(S (T::*f)(A));

-4- mem_fun(&X::f) returns an object through which X::f can be called given a pointer to an X followed by the argument required for f (if any).

  template <class S, class T> class mem_fun_ref_t
        : public unary_function<T, S> {
  public:
    explicit mem_fun_ref_t(S (T::*p)());
    S operator()(T& p) const;
};

-5- mem_fun_ref_t calls the member function it is initialized with given a reference argument.

  template <class S, class T, class A> class mem_fun1_ref_t
        : public binary_function<T, A, S> {
  public:
    explicit mem_fun1_ref_t(S (T::*p)(A));
    S operator()(T& p, A x) const;
};

-6- mem_fun1_ref_t calls the member function it is initialized with given a reference argument and an additional argument of the appropriate type.

  template<class S, class T> mem_fun_ref_t<S,T>
     mem_fun_ref(S (T::*f)());

  template<class S, class T, class A> mem_fun1_ref_t<S,T,A>
     mem_fun_ref(S (T::*f)(A));

-7- mem_fun_ref(&X::f) returns an object through which X::f can be called given a reference to an X followed by the argument required for f (if any).

template <class S, class T> class const_mem_fun_t
      : public unary_function<T*, S> {
public:
  explicit const_mem_fun_t(S (T::*p)() const);
  S operator()(const T* p) const;
};

-8- const_mem_fun_t calls the member function it is initialized with given a pointer argument.

template <class S, class T, class A> class const_mem_fun1_t
      : public binary_function<T*, A, S> {
public:
  explicit const_mem_fun1_t(S (T::*p)(A) const);
  S operator()(const T* p, A x) const;
};

-9- const_mem_fun1_t calls the member function it is initialized with given a pointer argument and an additional argument of the appropriate type.

  template<class S, class T> const_mem_fun_t<S,T>
     mem_fun(S (T::*f)() const);

  template<class S, class T, class A> const_mem_fun1_t<S,T,A>
     mem_fun(S (T::*f)(A) const);

-10- mem_fun(&X::f) returns an object through which X::f can be called given a pointer to an X followed by the argument required for f (if any).

  template <class S, class T> class const_mem_fun_ref_t
        : public unary_function<T, S> {
  public:
    explicit const_mem_fun_ref_t(S (T::*p)() const);
    S operator()(const T& p) const;
};

-11- const_mem_fun_ref_t calls the member function it is initialized with given a reference argument.

  template <class S, class T, class A> class const_mem_fun1_ref_t
        : public binary_function<T, A, S> {
  public:
    explicit const_mem_fun1_ref_t(S (T::*p)(A) const);
    S operator()(const T& p, A x) const;
};

-12- const_mem_fun1_ref_t calls the member function it is initialized with given a reference argument and an additional argument of the appropriate type.

  template<class S, class T> const_mem_fun_ref_t<S,T>
     mem_fun_ref(S (T::*f)() const);

  template<class S, class T, class A> const_mem_fun1_ref_t<S,T,A>
      mem_fun_ref(S (T::*f)(A) const);

-13- mem_fun_ref(&X::f) returns an object through which X::f can be called given a reference to an X followed by the argument required for f (if any).

20.4 - Memory [lib.memory]

Header <memory> synopsis

namespace std {
  //  lib.default.allocator, the default allocator:
  template <class T> class allocator;
  template <> class allocator<void>;
  template <class T, class U>
    bool operator==(const allocator<T>&, const allocator<U>&) throw();
  template <class T, class U>
    bool operator!=(const allocator<T>&, const allocator<U>&) throw();

  //  lib.storage.iterator, raw storage iterator:
  template <class OutputIterator, class T> class raw_storage_iterator;

  //  lib.temporary.buffer, temporary buffers:
  template <class T>
    pair<T*,ptrdiff_t> get_temporary_buffer(ptrdiff_t n);
  template <class T>
    void return_temporary_buffer(T* p);

  //  lib.specialized.algorithms, specialized algorithms:
  template <class InputIterator, class ForwardIterator>
    ForwardIterator
      uninitialized_copy(InputIterator first, InputIterator last,
                         ForwardIterator result);
  template <class ForwardIterator, class T>
    void uninitialized_fill(ForwardIterator first, ForwardIterator last,
                            const T& x);
  template <class ForwardIterator, class Size, class T>
    void uninitialized_fill_n(ForwardIterator first, Size n, const T& x);
  //  lib.auto.ptr, pointers:
  template<class X> class auto_ptr;
}

namespace std {
  template <class T> class allocator;

  //  specialize for  void:
  template <> class allocator<void> {
  public:
    typedef void* 	pointer;
    typedef const void*	const_pointer;
    // reference-to-void  members are impossible.
    typedef void  value_type;
    template <class U> struct rebind { typedef allocator<U> other; };
  };

  template <class T> class allocator {
   public:
    typedef size_t    size_type;
    typedef ptrdiff_t difference_type;
    typedef T*        pointer;
    typedef const T*  const_pointer;
    typedef T&        reference;
    typedef const T&  const_reference;
    typedef T         value_type;
    template <class U> struct rebind { typedef allocator<U> other; };

    allocator() throw();
    allocator(const allocator&) throw();
    template <class U> allocator(const allocator<U>&) throw();
   ~allocator() throw();

    pointer address(reference x) const;
    const_pointer address(const_reference x) const;

    pointer allocate(
      size_type, allocator<void>::const_pointer hint = 0);
    void deallocate(pointer p, size_type n);
    size_type max_size() const throw();

    void construct(pointer p, const T& val);
    void destroy(pointer p);
  };
}

-1- Returns: &x.

const_pointer address(const_reference x) const;

-2- Returns: &x.

pointer allocate(size_type n, allocator<void>::const_pointer hint=0);

-3- Notes: Uses ::operator new(size_t) (lib.new.delete).

-4- Requires: hint either 0 or previously obtained from member allocate and not yet passed to member deallocate. The value hint may be used by an implementation to help improve performance*.

[Footnote: In a container member function, the address of an adjacent element is often a good choice to pass for this argument. --- end foonote]

-5- Returns: a pointer to the initial element of an array of storage of size n * sizeof(T), aligned appropriately for objects of type T.

-6- Note: the storage is obtained by calling ::operator new(size_t), but it is unspecified when or how often this function is called. The use of hint is unspecified, but intended as an aid to locality if an implementation so desires.

-7- Throws: bad_alloc if the storage cannot be obtained.

void deallocate(pointer p, size_type n);

-8- Requires: p shall be a pointer value obtained from allocate(). n shall equal the value passed as the first argument to the invocation of allocate which returned p.

-9- Effects: Deallocates the storage referenced by p .

-10- Notes: Uses ::operator delete(void*) (lib.new.delete), but it is unspecified when this function is called.

size_type max_size() const throw();

-11- Returns: the largest value N for which the call allocate(N,0) might succeed.

void construct(pointer p, const_reference val);

-12- Returns: new((void *)p) T(val)

void destroy(pointer p);

-13- Returns: ((T*)p)->~T()

20.4.1.2 - allocator globals [lib.allocator.globals]

-1- Returns: true.

template <class T1, class T2>
  bool operator!=(const allocator<T1>&, const allocator<T2>&) throw();

-2- Returns: false.

20.4.2 - Raw storage iterator [lib.storage.iterator]

-1- raw_storage_iterator is provided to enable algorithms to store their results into uninitialized memory. The formal template parameter OutputIterator is required to have its operator* return an object for which operator& is defined and returns a pointer to T, and is also required to satisfy the requirements of an output iterator (lib.output.iterators).

namespace std {
  template <class OutputIterator, class T>
  class raw_storage_iterator
    : public iterator<output_iterator_tag,void,void,void,void> {
  public:
    explicit raw_storage_iterator(OutputIterator x);

    raw_storage_iterator<OutputIterator,T>& operator*();
    raw_storage_iterator<OutputIterator,T>& operator=(const T& element);
    raw_storage_iterator<OutputIterator,T>& operator++();
    raw_storage_iterator<OutputIterator,T>  operator++(int);
  };
}

-2- Effects: Initializes the iterator to point to the same value to which x points.

raw_storage_iterator<OutputIterator,T>& operator*();

-3- Returns: *this

raw_storage_iterator<OutputIterator,T>& operator=(const T& element);

-4- Effects: Constructs a value from element at the location to which the iterator points.

-5- Returns: A reference to the iterator.

raw_storage_iterator<OutputIterator,T>& operator++();

-6- Effects: Pre-increment: advances the iterator and returns a reference to the updated iterator.

raw_storage_iterator<OutputIterator,T> operator++(int);

-7- Effects: Post-increment: advances the iterator and returns the old value of the iterator.

20.4.3 - Temporary buffers [lib.temporary.buffer]

-1- Effects: Obtains a pointer to storage sufficient to store up to n adjacent T objects.

-2- Returns: A pair containing the buffer's address and capacity (in the units of sizeof(T)), or a pair of 0 values if no storage can be obtained.

template <class T> void return_temporary_buffer(T* p);

-3- Effects: Deallocates the buffer to which p points.

-4- Requires: The buffer shall have been previously allocated by get_temporary_buffer.

20.4.4 - Specialized algorithms [lib.specialized.algorithms]

-1- All the iterators that are used as formal template parameters in the following algorithms are required to have their operator* return an object for which operator& is defined and returns a pointer to T. In the algorithm uninitialized_copy, the formal template parameter InputIterator is required to satisfy the requirements of an input iterator (lib.input.iterators). In all of the following algorithms, the formal template parameter ForwardIterator is required to satisfy the requirements of a forward iterator (lib.forward.iterators) and also to satisfy the requirements of a mutable iterator (lib.iterator.requirements), and is required to have the property that no exceptions are thrown from increment, assignment, comparison, or dereference of valid iterators. In the following algorithms, if an exception is thrown there are no effects.

20.4.4.1 - uninitialized_copy [lib.uninitialized.copy]

-1- Effects:

for (; first != last; ++result, ++first)
    new (static_cast<void*>(&*result))
            typename iterator_traits<ForwardIterator>::value_type(*first);

-2- Returns: result

20.4.4.2 - uninitialized_fill [lib.uninitialized.fill]

-1- Effects:

for (; first != last; ++first)
    new (static_cast<void*>(&*first))
            typename iterator_traits<ForwardIterator>::value_type(x);

-1- Effects:

for (; n--; ++first)
    new (static_cast<void*>(&*first))
            typename iterator_traits<ForwardIterator>::value_type(x);

-1- Template auto_ptr stores a pointer to an object obtained via new and deletes that object when it itself is destroyed (such as when leaving block scope stmt.dcl).

-2- Template auto_ptr_ref holds a reference to an auto_ptr. It is used by the auto_ptr conversions to allow auto_ptr objects to be passed to and returned from functions.

namespace std {
  template<class X> class auto_ptr {
    template <class Y> struct auto_ptr_ref {};
  public:
    typedef X element_type;

    //  lib.auto.ptr.cons construct/copy/destroy:
    explicit auto_ptr(X* p =0) throw();
    auto_ptr(auto_ptr&) throw();
    template<class Y> auto_ptr(auto_ptr<Y>&) throw();
    auto_ptr& operator=(auto_ptr&) throw();
    template<class Y> auto_ptr& operator=(auto_ptr<Y>&) throw();
   ~auto_ptr() throw();

    //  lib.auto.ptr.members members:
    X& operator*() const throw();
    X* operator->() const throw();
    X* get() const throw();
    X* release() throw();
    void reset(X* p =0) throw();

    //  lib.auto.ptr.conv conversions:
    auto_ptr(auto_ptr_ref<X>) throw();
    template<class Y> operator auto_ptr_ref<Y>() throw();
    template<class Y> operator auto_ptr<Y>() throw();
  };
}

-3- The auto_ptr provides a semantics of strict ownership. An auto_ptr owns the object it holds a pointer to. Copying an auto_ptr copies the pointer and transfers ownership to the destination. If more than one auto_ptr owns the same object at the same time the behavior of the program is undefined. [Note: The uses of auto_ptr include providing temporary exception-safety for dynamically allocated memory, passing ownership of dynamically allocated memory to a function, and returning dynamically allocated memory from a function. auto_ptr does not meet the CopyConstructible and Assignable requirements for Standard Library container elements and thus instantiating a Standard Library container with an auto_ptr results in undefined behavior.
--- end note]

20.4.5.1 - auto_ptr constructors [lib.auto.ptr.cons]

-1- Postconditions: *this holds the pointer p.

auto_ptr(auto_ptr& a) throw();

-2- Effects: Calls a.release().

-3- Postconditions: *this holds the pointer returned from a.release().

template<class Y> auto_ptr(auto_ptr<Y>& a) throw();

-4- Requires: Y* can be implicitly converted to X*.

-5- Effects: Calls a.release().

-6- Postconditions: *this holds the pointer returned from a.release().

auto_ptr& operator=(auto_ptr& a) throw();

-7- Requires: The expression delete get() is well formed.

-8- Effects: reset(a.release()).

-9- Returns: *this.

template<class Y> auto_ptr& operator=(auto_ptr<Y>& a) throw();

-10- Requires: Y* can be implicitly converted to X*. The expression delete get() is well formed.

-11- Effects: reset(a.release()).

-12- Returns: *this.

~auto_ptr() throw();

-13- Requires: The expression delete get() is well formed.

-14- Effects: delete get().

20.4.5.2 - auto_ptr members [lib.auto.ptr.members]

-1- Requires: get() != 0

-2- Returns: *get()

X* operator->() const throw();

-3- Returns: get()

X* get() const throw();

-4- Returns: The pointer *this holds.

X* release() throw();

-5- Returns: get()

-6- Postcondition: *this holds the null pointer.

void reset(X* p=0) throw();

-7- Effects: If get() != p then delete get().

-8- Postconditions: *this holds the pointer p.

20.4.5.3 - auto_ptr conversions [lib.auto.ptr.conv]

-1- Effects: Calls p.release() for the auto_ptr p that r holds.

-2- Postconditions: *this hold the pointer returned from release().

template<class Y> operator auto_ptr_ref<Y>() throw();

-3- Returns: An auto_ptr_ref<Y> that holds *this.

template<class Y> operator auto_ptr<Y>() throw();

-4- Effects: Calls release().

-5- Returns: An auto_ptr<Y> that holds the pointer returned from release().

20.4.6 - C Library [lib.c.malloc]

-1- Header <cstdlib> (Table ??):

-2- The contents are the same as the Standard C library header <stdlib.h>, with the following changes:

-3- The functions calloc(), malloc(), and realloc() do not attempt to allocate storage by calling ::operator new() (lib.support.dynamic).

-4- The function free() does not attempt to deallocate storage by calling ::operator delete().

See also ISO C clause 7.11.2.

-5- Header <cstring> (Table ??):

-6- The contents are the same as the Standard C library header <string.h>, with the change to memchr() specified in lib.c.strings.

See also ISO C clause 7.11.2.

20.5 - Date and time [lib.date.time]

-1- Header <ctime> (Table ??):

-2- The contents are the same as the Standard C library header <time.h>.

See also ISO C clause 7.12, Amendment 1 clause 4.6.4.