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 27:
| Table 27---General utilities library summary |
_ _____________________________________ _ Clause Header(s) _ _____________________________________ _____________________________________ _ 20.1 Requirements _____________________________________ _ 20.2 Utility components <utility> _____________________________________ _ 20.3 Function objects <functional> _____________________________________ _ 20.4 Memory <memory> _____________________________________ _ 20.5 Date and time <ctime> _____________________________________ |
1 20.1 describes requirements on template arguments. 20.1.1 through 20.1.3 describe requirements on types used to instantiate templates. 20.1.5 describes the requirements on storage allocators.
1 In Table 28, T is a type to be supplied by a C++ program instantiating a template, a, b and c are values of type T.
| Table 28---EqualityComparable requirements |
_____________________________________________________________________
expression return type requirement
_____________________________________________________________________
_____________________________________________________________________
a == b convertible to bool == is an equivalence rela tion, that is, it satisfies the
following properties:
|
1 In the following Table 29, T is a type to be supplied by a C++ program instantiating a template, a and b are values of type T.
| Table 29---LessThanComparable requirements |
_ __________________________________________________________________ _ expression return type requirement _ __________________________________________________________________ __________________________________________________________________ _ a < b convertible to bool < is a strict weak ordering relation (25.3) __________________________________________________________________ |
1 In the following Table 30, 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.
| Table 30---CopyConstructible requirements |
_ ______________________________________________ _ expression return type requirement _ ______________________________________________ ______________________________________________ _ T(t) t is equivalent to T(t) ______________________________________________ _ T(u) u is equivalent to T(u) ______________________________________________ _ t.~T() ______________________________________________ _ &t T* denotes the address of t ______________________________________________ _ &u const T* denotes the address of u ______________________________________________ |
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 (8.5) if one of those signatures is called using the default argument (8.3.6).
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 23) are parameterized in terms of allocators.
2 Table 31 describes the requirements on types manipulated through allocators. All the operations on the allocators are expected to be amortized constant time. Table 32 describes the requirements on allocator types.
| Table 31---Descriptive variable definitions | ||
_ ___________________________________________________________ _ Variable Definition _ ___________________________________________________________ ___________________________________________________________ _ T, U any type ___________________________________________________________ _ X an Allocator class for type T ___________________________________________________________ _ Y the corresponding Allocator class for type U ___________________________________________________________ _ t a value of type const T& ___________________________________________________________ _ a, a1, a2 values of type X& ___________________________________________________________ _ b a value of type Y ___________________________________________________________ p a value of type X::pointer, obtained by calling _ a1.allocate, where a1 == a. ___________________________________________________________ q a value of type X::const_pointer obtained by _ conversion from a value p. ___________________________________________________________ r a value of type X::reference obtained by _ the expression *p. ___________________________________________________________ s a value of type X::const_reference obtained by _ the expression *q or by conversion from a value r. ___________________________________________________________ u a value of type Y::const_pointer obtained by _ calling Y::allocate, or else 0. ___________________________________________________________ _ n a value of type X::size_type. ___________________________________________________________ |
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 32.
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 32, and the semantics of containers and algorithms when allocator instances compare non-equal, are implementation-defined.
1 This subclause contains some basic template functions and classes that are used throughout the rest of the library. Header <utility> synopsis
namespace std {
// 20.2.1, 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&);
}
// 20.2.2, 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 (20.1.1).
3 Returns: !(x == y).
template <class T> bool operator>(const T& x, const T& y);
4 Requires: Type T is LessThanComparable (20.1.2).
5 Returns: y < x.
template <class T> bool operator<=(const T& x, const T& y);
6 Requires: Type T is LessThanComparable (20.1.2).
7 Returns: !(y < x).
template <class T> bool operator>=(const T& x, const T& y);
8 Requires: Type T is LessThanComparable (20.1.2).
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.
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);
};
pair();
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:
a C++ program may contain:return pair<int, double>(5, 3.1415926); // explicit types
---end example]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 25), 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 {
// 20.3.1, base:
template <class Arg, class Result> struct unary_function;
template <class Arg1, class Arg2, class Result> struct binary_function;
// 20.3.2, 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;
// 20.3.3, 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;
// 20.3.4, logical operations:
template <class T> struct logical_and;
template <class T> struct logical_or;
template <class T> struct logical_not;
// 20.3.5, 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&);
// 20.3.6, 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&);
// 20.3.7, 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));
// 20.3.8, 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:
---end example]transform(a.begin(), a.end(), b.begin(), a.begin(), plus<double>());
4 [Example: To negate every element of a:
The corresponding functions will inline the addition and the negation. ---end example]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.
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 (5.6, 5.7).
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.
1 The library provides basic function object classes for all of the comparison operators in the language (5.9, 5.10).
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.
1 The library provides basic function object classes for all of the logical operators in the language (5.14, 5.15, 5.3.1).
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.
1 Negators not1 and not2 take a unary and a binary predicate, respectively, and return their complements (5.3.1).
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).
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]
template <class Operation, class T> binder1st<Operation> bind1st(const Operation& op, const T& x);
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]
template <class Operation, class T> binder2nd<Operation> bind2nd(const Operation& op, const T& x);
1 Returns: binder2nd<Operation>(op, typename Operation::second_argument_type(x)).
2 [Example:
finds the first integer in vector v greater than 5;find_if(v.begin(), v.end(), bind2nd(greater<int>(), 5));
finds the first integer in v less than 5. ---end example]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:
replaces each C with C++ in sequence v.215) ---end example]replace_if(v.begin(), v.end(), not1(bind2nd(ptr_fun(strcmp), "C")), "C++");
214) 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''. [back to text]215) Implementations that have multiple pointer to function types provide additional ptr_fun template functions. [back to text]
1 The purpose of the following is to provide the same facilities for pointer to members as those provided for pointers to functions in 20.3.7.
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).
namespace std {
// 20.4.1, 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();
// 20.4.2, raw storage iterator:
template <class OutputIterator, class T> class raw_storage_iterator;
// 20.4.3, temporary buffers:
template <class T>
pair<T*,ptrdiff_t> get_temporary_buffer(ptrdiff_t n);
template <class T>
void return_temporary_buffer(T* p);
// 20.4.4, 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);
// 20.4.5, 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);
};
}
pointer address(reference x) const;
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) (18.4.1).
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 performance216).
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*) (18.4.1), 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()
216) In a container member function, the address of an adjacent element is often a good choice to pass for this argument. [back to text]
template <class T1, class T2> bool operator==(const allocator<T1>&, const allocator<T2>&) throw();
1 Returns: true.
template <class T1, class T2> bool operator!=(const allocator<T1>&, const allocator<T2>&) throw();
2 Returns: false.
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 (24.1.2).
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);
};
}
raw_storage_iterator(OutputIterator x);
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.
template <class T> pair<T*, ptrdiff_t> get_temporary_buffer(ptrdiff_t n);
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.
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 (24.1.1). In all of the following algorithms, the formal template parameter ForwardIterator is required to satisfy the requirements of a forward iterator (24.1.3) and also to satisfy the requirements of a mutable iterator (24.1), 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.
template <class InputIterator, class ForwardIterator>
ForwardIterator
uninitialized_copy(InputIterator first, InputIterator last,
ForwardIterator result);
1 Effects:
for (; first != last; ++result, ++first)
new (static_cast<void*>(&*result))
typename iterator_traits<ForwardIterator>::value_type(*first);
2 Returns: result
template <class ForwardIterator, class T>
void uninitialized_fill(ForwardIterator first, ForwardIterator last,
const T& x);
1 Effects:
for (; first != last; ++first)
new (static_cast<void*>(&*first))
typename iterator_traits<ForwardIterator>::value_type(x);
template <class ForwardIterator, class Size, class T> void uninitialized_fill_n(ForwardIterator first, Size n, const T& 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 6.7).
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;
// 20.4.5.1 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();
// 20.4.5.2 members:
X& operator*() const throw();
X* operator->() const throw();
X* get() const throw();
X* release() throw();
void reset(X* p =0) throw();
// 20.4.5.3 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]
explicit auto_ptr(X* p =0) throw();
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().
X& operator*() const throw();
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.
auto_ptr(auto_ptr_ref<X> r) throw();
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().
1 Header <cstdlib> (Table 33):
| Table 33---Header <cstdlib> synopsis |
_ _______________________________ _ Type Name(s) _______________________________ Functions: calloc malloc _ free realloc _______________________________ |
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() (18.4).
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 34):
| Table 34---Header <cstring> synopsis |
_ _______________________________ _ Type Name(s) _______________________________ _ Macro: NULL _______________________________ _ Type: size_t _______________________________ Functions: memchr memcmp _ memcpy memmove memset _______________________________ |
6 The contents are the same as the Standard C library header <string.h>, with the change to memchr() specified in 21.4. SEE ALSO: ISO C clause 7.11.2.
1 Header <ctime> (Table 35):
| Table 35---Header <ctime> synopsis |
_ _______________________________________________________ _ Type Name(s) _______________________________________________________ _ Macros: NULL _______________________________________________________ _ Types: size_t clock_t time_t _______________________________________________________ _ Struct: tm _______________________________________________________ Functions: asctime clock difftime localtime strftime _ ctime gmtime mktime time _______________________________________________________ |
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.