This clause describes components used by other elements of the Standard C + + library. These components may also be used by C + + programs.
The following clauses describe utility and allocator requirements, utility components, function objects,
This section describes the requirements for template arguments, types used to instantiate templates and storage allocators used as general utilities.
The equality comparison operator is required. The (==) expression has a bool return type and specifies that for x == y and y == z that x will equal z. In addition the reciprocal is also true. That is, if x == y then y equals x. Also if x == y and y == z then z will be equal to x.
A less than operator is required. The (<) expression has a bool return type and states that if x < y that x is less than y and that y is not less than x.
A copy constructor for the general utilities library has the following requirements:
TYPE(t) then the argument must be an equivalent of TYPE.
TYPE(const t) then the argument must be the equivalent of const TYPE.
&T, denotes the address of T.
&const T, denotes the address of const T.
A default constructor is not necessary. However, some container class members may specify a default constructor as a default argument. In that case when a default constructor is used as a default argument there must be a default constructor defined.
The general utilities library requirements include requirements for allocators. Allocators are objects that contain information about the container. This includes information concerning pointer types, the type of their difference, the size of objects in this allocation, also the memory allocation and deallocation information. All of the standard containers are parameterized in terms of allocators.
The allocator class includes the following members
| Expression |
Meaning |
|---|---|
| A type identical to the type | |
| A signed integer that can represent the difference between any to pointers in the allocator | |
| Returns the address of the const type | |
Allocator template parameters must meet additional requirements
Implementation-defined allocators are allowed.
The Typedef Members Requirements :
| Member |
Type |
|---|---|
This sub-clause contains some basic template functions and classes that are used throughout the rest of the library.
namespace std {
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&);
}
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&);
}
The Standard C++ library provides general templatized comparison operators that are based on operator== and operator<.
This operator determines if the first argument is not equal to the second argument.
Prototype:
template <class T> bool operator!=(const T& x, const T& y);
This operator determines if the first argument is less than the second argument.
Prototype:
template <class T> bool operator>(const T& x, const T& y);
This operator determines if the first argument is less than or equal to the second argument.
Prototype:
template <class T> bool operator<=(const T& x, const T& y);
This operator determines if the first argument is greater than or equal to the second argument.
Prototype:
template <class T> bool operator>=(const T& x, const T& y);
The utility library includes support for paired values.
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);
};
The pair class contains various constructors to fit each pairs needs.
Prototype:
pair();
Initializes its members as with default type constructors.
Prototype:
template<class U, class V> pair(const pair< U, V> & p);
Initializes and does any implicit conversions if necessary.
The pair equality operator returns true if each pair argument is equal to the other.
Prototype:
template <class T1, class T2>
bool operator==(const pair<T1, T2>& x, const pair<T1, T2>& y); The pair less than operator returns true if the second pair argument is less that the first pair argument.
Prototype:
template <class T1, class T2> bool operator<
(const pair<T1, T2>& x, const pair<T1, T2>& y); Makes a pair of the two arguments.
Prototype:
template <class T1, class T2>
pair<T1, T2> make_pair(const T1& x, const T2& y);Return:
Returns a pair of the two arguments.
Function objects have the operator() defined and used for more effective use of the library. When a pointer to a function would normally be passed to an algorithm function the library is specified to accept an object with operator() defined. The use of function objects with function templates increases the power and efficiency of the library
NOTE In order to manipulate function objects that take one or two arguments it is required that their function objects provide the defined types. If the function object takes one argument then argument_type and result_type are defined. If the function object takes two arguments then the first_argument_type, second_argument_type, and result_type must be defined.
namespace std {
template <class Arg, class Result> struct unary_function;
template <class Arg1, class Arg2,
class Result> struct binary_function;
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;
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;
template <class T> struct logical_and;
template <class T> struct logical_or;
template <class T> struct logical_not;
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&);
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&);
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));
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);
}
Classes are provided to simplify the typedef 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;
};
The utility library provides function object classes with operator() defined for the arithmetic operations.
Adds the first and the second and returns that sum.
Prototype:
template <class T> struct plus :
binary_function<T,T,T> {
T operator()(const T& x, const T& y) const; };
Subtracts the second from the first and returns the difference.
Prototype:
template <class T> struct minus :
binary_function<T,T,T> {
T operator()(const T& x, const T& y) const; };
Multiplies the first times the second and returns the resulting value.
Prototype:
template <class T> struct multiplies :
binary_function<T,T,T> {
T operator()(const T& x, const T& y) const; };
Divides the first by the second and returns the resulting value.
Prototype:
template <class T> struct divides :
binary_function<T,T,T> {
T operator()(const T& x, const T& y) const; };
Determines the modulus of the first by the second argument and returns the result.
Prototype:
template <class T> struct modulus :
binary_function<T,T,T> {
T operator()(const T& x, const T& y) const; };
This function returns the negative value of the argument.
Prototype:
template <class T> struct negate :
unary_function<T,T> {
T operator()(const T& x) const; };
The utility library provides function object classes with operator() defined for the comparison operations.
NOTE For the greater, less, greater_equal and less_equal template classes specializations for pointers yield a total order.
Returns true if the first argument is equal to the second argument.
Prototype:
template <class T> struct equal_to :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the first argument is not equal to the second argument.
Prototype:
template <class T> struct not_equal_to :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the first argument is greater than the second argument.
Prototype:
template <class T> struct greater :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the first argument is less than the second argument.
Prototype:
template <class T> struct less :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the first argument is greater than or equal to the second argument.
Prototype:
template <class T> struct greater_equal :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the first argument is less than or equal to the second argument.
Prototype:
template <class T> struct less_equal :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
The utility library provides function object classes with operator() defined for the logical operations.
Returns true if the first and the second argument are true.
Prototype:
template <class T> struct logical_and :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the first or the second argument are true.
Prototype:
template <class T> struct logical_or :
binary_function<T,T,bool> {
bool operator()(const T& x, const T& y) const; };
Returns true if the argument is zero
Prototype:
template <class T> struct logical_not :
unary_function<T,bool> {
bool operator()(const T& x) const; };
The utility library provides negators not1 and not2 that return the complement of the unary or binary predicate. A
predicate is an object that takes one or two arguments and returns
something convertible to bool.
In the template class unary_negate the operator() returns the compliment of the predicate argument.
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;
};
The template function not1 returns the unary_predicate of the predicate argument.
Prototype:
template <class Predicate>
unary_negate<Predicate>
not1(const Predicate& pred); In the template class binary_negate the operator() returns the compliment of the predicate arguments.
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;
};
The template function not2 returns the binary_predicate of the predicate arguments.
Prototype:
template <class Predicate>
binary_negate<Predicate>
not2(const Predicate& pred); The binders classes, bind1st and bind2nd take a function object and a value and return a function object constructed out of the function bound to the value.
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;
};
The constructor initializes the Operation op with x and value with y.
Return:
Prototype:
template <class Operation, class T>
binder1st<Operation> bind1st(const Operation& op, const T& x);Return:
binder1st<Operation>( op,
typename Operation::first_argument_type( x)).
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;
};
The constructor initializes op with x and value with y.
Prototype:
operator()(const typename Operation::first_argument_type& x) const;Return:
Prototype:
template <class Operation, class T>
binder2nd<Operation> bind2nd (const Operation& op, const T& x); binder2nd<Operation>( op,
typename Operation::second_argument_type( x)). Adaptors for pointers to pointers to both unary and binary functions work with adaptors.
class pointer_to_unary_function:
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;
};
Prototype:
Result operator()(Arg x) const;
Return:
Prototype:
template <class Arg, class Result>
pointer_to_unary_function<Arg, Result> ptr_fun(Result (* f)(Arg)); pointer_to_unary_function<Arg, Result>( f).
A class for pointer to binary binding.
class pointer_to_binary_function:
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;
};
Prototype:
Result operator()(Arg1 x, Arg2 y) const;Return:
Prototype:
template <class Arg1, class Arg2, class Result>
pointer_to_binary_function<Arg1,Arg2,Result ptr_fun(Result (* f)(Arg1, Arg2)); pointer_to_binary_function<Arg1,Arg2,Result>( f).
Adaptors for pointer members are adaptors that allow you to call member functions for elements within a collection.
An adaptor for pointers to member functions.
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;
};
The constructor for mem_fun_t calls the member function it is initialized with a given pointer
argument and an appropriate additional argument.
A class for binding a member function.
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;
};
The constructor for mem_fun1_t calls the member function it is initialized with given a pointer
argument and an appropriate additional argument.
Member to function template functions.
Prototype:
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)); The functions return an object through which X::f can be called given a pointer to an X followed by the argument required for f (if any).
Member to function reference object.
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;
};
The function mem_fun_ref_t calls the member function it is initialized with given a reference
argument.
Member to function reference object.
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;
};
The constructor for 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 function for member to reference.
Prototype:
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)); The template function mem_fun_ref 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).
Provides a constant member to function object.
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;
};
The constructor for const_mem_fun_t calls the member function it is initialized with given a pointer
argument.
Provides a const to member function object.
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;
};
The constructor for const_mem_fun1_t calls the member function it is initialized with given a pointer
argument and an additional argument of the appropriate type.
A constant member to function adaptor.
Prototype:
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); The template function mem_fun 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).
A constant member to function class.
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;
};
The constructor for const_mem_fun_ref_t calls the member function it is initialized with given a reference
argument.
A constant member to function reference adaptor object.
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;
};
The constructor for 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.
A constant member function reference adaptor.
Prototype:
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); The template functions mem_fun_ref 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).
The header <memory> includes functions and classes for the allocation and deallocation
of memory.
namespace std {
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();
template <class OutputIterator, class T>
class raw_storage_iterator;
template <class T>
pair<T*,ptrdiff_t> get_temporary_buffer(ptrdiff_t n);
template <class T>
void return_temporary_buffer(T* p);
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);
template<class X> class auto_ptr;
}
The default allocation classes.
namespace std {
template <class T> class allocator;
template <> class allocator<void> {
public:
typedef void* pointer;
typedef const void* const_pointer;
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);
};
}
Determine the address of the allocation.
Prototype:
pointer address(reference x) const;
const_pointer address(const_reference x) const;Return:
Returns the address of the allocation.
Create an allocation and return a pointer to it.
Prototype:
pointer allocate(size_type n, allocator<void>::const_pointer hint=0);Return:
A pointer to the initial element of an array of storage.
Exception:
Allocate throw a bad_alloc exception if the storage cannot be obtained.
Remove an allocation from memory.
Prototype:
void deallocate(pointer p, size_type n);
Deallocates the storage referenced by p.
Determines the Maximum size for an allocation.
Prototype:
size_type max_size() const throw();
Return:
Returns the largest size of memory that may be.
Determines the Maximum size for an allocation.
Prototype:
void construct(pointer p, const_reference val);Return:
A pointer to the allocated memory.
Prototype:
Provides globals operators in memory allocation.
Prototype:
template <class T1, class T2.bool operator==
(const allocator<T1>&, const allocator<T2>&) throw(); Returns true if the arguments are equal.
Prototype:
template <class T1, class T2> bool operator!=
(const allocator<T1>&, const allocator<T2>&) throw(); Returns true if the arguments are not equal.
A means of storing the results of un-initialized memory.
NOTE 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.
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);
};
}
A constructor for the raw_storage_iterator class.
Prototype:
raw_storage_iterator(OutputIterator x);
Prototype:
raw_storage_iterator<OutputIterator,T>&
operator*(); The dereference operator return *this.
The raw_storage_iterator assignment operator.
Prototype:
raw_storage_iterator<OutputIterator,T>&
operator=(const T& element); 4 Effects: Constructs a value from element at the location to which the iterator points.
Return:
Post and Pre-increment operators for raw_storage_iterator.
Prototype:
raw_storage_iterator<OutputIterator,T>&
operator++(); // Pre-increment raw_storage_iterator<OutputIterator,T>
operator++(int); //Post-increment Returns the old value of the iterator.
Methods for storing and retrieving temporary allocations.
Retrieves a pointer to store temporary objects.
Prototype:
template <class T> pair<T*, ptrdiff_t>
get_temporary_buffer(ptrdiff_t n); An address for the buffer and its size or zero if unsuccessful.
Deallocation for the get_temporary_buffer procedure.
Prototype:
template <class T>
void return_temporary_buffer(T* p); The buffer must have been previously allocated by get_temporary_buffer.
Algorithm necessary to fulfill iterator requirements.
Prototype:
template <class InputIterator,
class ForwardIterator> ForwardIterator uninitialized_copy
(InputIterator first, InputIterator last,ForwardIterator result);Return:
Returns a ForwardIterator to the result argument.
Prototype:
template <class ForwardIterator, class T>
void uninitialized_fill (ForwardIterator first, ForwardIterator last,const T& x); An uninitialized fill with a size limit.
Prototype:
template <class ForwardIterator,
class Size, class T> void uninitialized_fill_n (ForwardIterator first, Size n, const T& x); The auto_ptr class stores a pointer to an object obtained using new and deletes that object when it is destroyed. For example when a local allocation goes out of scope.
The template auto_ptr_ref holds a reference to an auto_ptr, and is used by the auto_ptr conversions. This allows auto_ptr objects to be passed to and returned from functions.
namespace std {
template <class Y> struct auto_ptr_ref {};
template<class X> class auto_ptr {
public:
typedef X element_type;
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();
auto_ptr& operator=(auto_ptr_ref<X> r) throw();
template<class Y> auto_ptr& operator=(auto_ptr<Y>&) throw();
~auto_ptr() throw();
X& operator*() const throw();
X* operator->() const throw();
X* get() const throw();
X* release() throw();
void reset(X* p =0) throw();
auto_ptr(auto_ptr_ref<X>) throw();
template<class Y> operator auto_ptr_ref<Y>() throw();
template<class Y> operator auto_ptr<Y>() throw();
};
}
NOTE An auto_ptr owns the object it holds a pointer to. When copying an auto_ptr the pointer 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.
See the example of using std::auto_ptr and extension version for arrays in Listing 5.23
This extension can be turned off by commenting out #define _MSL_ARRAY_AUTO_PTR in <mslconfig>. No recompile of the C++ lib is necessary, but do rebuild any precompiled headers when making this change.
The functionality provided by the extended std::auto_ptr is very similar to that provided by the newer Metrowerks::alloc_ptr found in <msl_utility>.
#include <iostream>
#include <memory>
using std::auto_ptr;
using std::_Array;
struct A
{
A() {std::cout << "construct A\n";}
virtual ~A() {std::cout << "destruct A\n";}
};
struct B
: A
{
B() {std::cout << "construct B\n";}
virtual ~B() {std::cout << "destruct B\n";}
};
auto_ptr<B> source();
void sink_b(auto_ptr<B>);
void sink_a(auto_ptr<A>);
auto_ptr<B, _Array<B> > array_source();
void array_sink(auto_ptr<B, _Array<B> >);
auto_ptr<B>
source()
{
return auto_ptr<B>(new B);
}
void
sink_b(auto_ptr<B>)
{
}
void
sink_a(auto_ptr<A>)
{
}
auto_ptr<B, _Array<B> >
array_source()
{
return auto_ptr<B, _Array<B> >(new B [2]);
}
void
array_sink(auto_ptr<B, _Array<B> >)
{
}
int main()
{
{
auto_ptr<B> b(new B);
auto_ptr<B> b2(b);
b = b2;
auto_ptr<B> b3(source());
auto_ptr<A> a(b);
a = b3;
b3 = source();
sink_b(source());
auto_ptr<A> a2(source());
a2 = source();
sink_a(source());
}
{
auto_ptr<B, _Array<B> > b(new B [2]);
auto_ptr<B, _Array<B> > b2(b);
b = b2;
auto_ptr<B, _Array<B> > b3(array_source());
b3 = array_source();
array_sink(array_source());
// auto_ptr<A, _Array<A> > a(b3); // Should not compile
// a = b3; // Should not compile
}
Constructs an auto_ptr object.
Prototype:
explicit auto_ptr(X* p =0) throw();
auto_ptr(auto_ptr& a) throw();
template<class Y> auto_ptr(auto_ptr<Y>& a) throw();
An auto_ptr assignment operator.
Prototype:
template<class Y> auto_ptr& operator=(
auto_ptr<Y>& a) throw(); auto_ptr& operator=
(auto_ptr& a) throw(); Prototype:
~auto_ptr() throw();
Prototype:
X& operator*() const throw();Return:
Returns what the derefernced this pointer holds.
The pointer dereference operator.
Prototype:
X* operator->() const throw();Return:
Returns what the derefernced this pointer holds.
Gets the value that the pointer points to.
Prototype:
X* get() const throw();Return:
Returns what the derefernced this pointer holds.
Prototype:
Return:
Returns what the derefernced this pointer holds.
Resets the auto_ptr to zero or another pointer.
Prototype:
void reset(X* p=0) throw();
Conversion functionality for the auto_ptr class for copying and converting.
Prototype:
auto_ptr(auto_ptr_ref<X> r) throw();
Provides a convert to lvalue process.
Prototype:
template<class Y> operator auto_ptr_ref<Y>() throw();
Return:
Returns a reference that holds the this pointer.
Releases the auto_ptr and returns the pointer held.
Prototype:
template<class Y> operator auto_ptr<Y>() throw();
Return:
The MSL C++ memory libraries use the C library memory functions. See the MSL C Reference for <stdlib.h> functions calloc, malloc, free, realloc for more information.
The header <ctime> has the same contents as the Standard C library header <time.h> but within namespace std.