memory(C++std)

allocator , allocator<void> , raw_storage_iterator , auto_ptr , operator== , operator!= , get_temporary_buffer , return_temporary_buffer , uninitialized_copy , uninitialized_fill , uninitialized_fill_n - defines several templates that allocate and free storage for various container classes (standard template library)

Synopsis

   namespace std {
   template<class T>
       class allocator;
   template<>
       class allocator<void>;
   template<class FwdIt, class T>
       class raw_storage_iterator;
   template<class T>
       class auto_ptr;

           // TEMPLATE OPERATORS
   template<class T>
       bool operator==(allocator<T>& lhs,
           allocator<T>& rhs);
   template<class T>
       bool operator!=(allocator<T>& lhs,
           allocator<T>& rhs);

           // TEMPLATE FUNCTIONS
   template<class T>
       pair<T *, ptrdiff_t>
           get_temporary_buffer(ptrdiff_t n);
   template<class T>
       void return_temporary_buffer(T *p);
   template<class InIt, class FwdIt>
       FwdIt uninitialized_copy(InIt first, InIt last,
           FwdIt result);
   template<class FwdIt, class T>
       void uninitialized_fill(FwdIt first, FwdIt last,
           const T& x);
   template<class FwdIt, class Size, class T>
       void uninitialized_fill_n(FwdIt first, Size n,
           const T& x);
       };

Description

Include the STL standard header <memory> to define a class, an operator, and several templates that help allocate and free objects.

allocator

address , allocate , allocator , const_pointer , const_reference , construct , deallocate , destroy , difference_type , max_size , operator= , pointer , rebind , reference , size_type , value_type

   template<class T>
       class allocator {
       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;
       pointer address(reference x) const;
       const_pointer address(const_reference x) const;
       template<class U>
           struct rebind;
       allocator();
       template<class U>
           allocator(const allocator<U>& x);
       template<class U>
           allocator& operator=(const allocator<U>& x);
       template<class U>
           pointer allocate(size_type n, const U *hint = 0);
       void deallocate(pointer p, size_type n);
       void construct(pointer p, const T& val);
       void destroy(pointer p);
       size_type max_size() const;
       };

The template class describes an object that manages storage allocation and freeing for arrays of objects of type T. An object of class allocator is the default allocator object specified in the constructors for several container template classes in the Standard C++ library.

Template class allocator supplies several type definitions that are rather pedestrian. They hardly seem worth defining. But another class with the same members might choose more interesting alternatives. Constructing a container with an allocator object of such a class gives individual control over allocation and freeing of elements controlled by that container.

For example, an allocator object might allocate storage on a private heap. Or it might allocate storage on a far heap, requiring nonstandard pointers to access the allocated objects. Or it might specify, through the type definitions it supplies, that elements be accessed through special accessor objects that manage shared memory, or perform automatic garbage collection. Hence, a class that allocates storage using an allocator object should use these types religiously for declaring pointer and reference objects (as do the containers in the Standard C++ library).

Thus, an allocator defines the types (among others):

pointer -- behaves like a pointer to T
const_pointer -- behaves like a const pointer to T
reference -- behaves like a reference to T
const_reference -- behaves like a const reference to T

These types specify the form that pointers and references must take for allocated elements. (allocator::pointer is not necessarily the same as T * for all allocator objects, even though it has this obvious definition for class allocator.)

`allocator::address`

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

The member functions return the address of x, in the form that pointers must take for allocated elements.

`allocator::allocate`

   template<class U>
       pointer allocate(size_type n, const U *hint = 0);

The member function allocates storage for an array of n elements of type T, by calling operator new(n). It returns a pointer to the allocated object. The hint argument helps some allocators in improving locality of reference -- a valid choice is the address of an object earlier allocated by the same allocator object, and not yet deallocated. To supply no hint, use a null pointer argument instead.

`allocator::allocator`

   allocator();
   template<class U>
       allocator(const allocator<U>& x);

The constructor does nothing. In general, however, an allocator object constructed from another allocator object should compare equal to it (and hence permit intermixing of object allocation and freeing between the two allocator objects).

`allocator::const_pointer`

   typedef const T *pointer;

The pointer type describes an object p that can designate, via the expression *p, any const object that an object of template class allocator can allocate.

allocator::const_reference

   typedef const T& const_reference;

The reference type describes an object x that can designate any const object that an object of template class allocator can allocate.

allocator::construct

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

The member function constructs an object of type T at p by evaluating the placement new expression new ((void *)p) T(val).

`allocator::deallocate`

   void deallocate(pointer p, size_type n);

The member function frees storage for the array of n objects of type T beginning at p, by calling operator delete(p). The pointer p must have been earlier returned by a call to allocate for an allocator object that compares equal to *this, allocating an array object of the same size and type. deallocate never throws an exception.

allocator::destroy

   void destroy(pointer p);

The member function destroys the object designated by p, by calling the destructor p->T::~T().

`allocator::difference_type`

   typedef ptrdiff_t difference_type;

The signed integer type describes an object that can represent the difference between the addresses of any two elements in a sequence that an object of template class allocator can allocate.

`allocator::max_size`

   size_type max_size() const;

The member function returns the length of the longest sequence of elements of type T that an object of class allocator might be able to allocate.

`allocator::operator=`

   template<class U>
       allocator& operator=(const allocator<U>& x);

The template assignment operator does nothing. In general, however, an allocator object assigned to another allocator object should compare equal to it (and hence permit intermixing of object allocation and freeing between the two allocator objects).

allocator::pointer

   typedef T *pointer;

The pointer type describes an object p that can designate, via the expression *p, any object that an object of template class allocator can allocate.

allocator::rebind

   template<class U>
       struct rebind {
       typedef allocator<U> other;
       };

The member template class defines the type other. Its sole purpose is to provide the type name allocator given the type name allocator<T>.

For example, given an allocator object al of type A, you can allocate an object of type U with the expression:

   A::rebind<U>::other(al).allocate(1, (U *)0)

Or, you can simply name its pointer type by writing the type:

   A::rebind<U>::other::pointer

allocator::reference

   typedef T& reference;

The reference type describes an object x that can designate any object that an object of template class allocator can allocate.

`allocator::size_type`

   typedef size_t size_type;

The unsigned integer type describes an object that can represent the length of any sequence that an object of template class allocator can allocate.

allocator::value_type

   typedef T value_type;

The type is a synonym for the template parameter T.

allocator<void>

   template<>
       class allocator<void> {
       typedef void *pointer;
       typedef const void *const_pointer;
       typedef void value_type;
       template<class U>
           struct rebind;
       allocator();
       template<class U>
           allocator(const allocator<U>);
       template<class U>
           allocator<void>& operator=(const allocator<U>);
       };

The class explicitly specializes template class allocator for type void. Its constructors and assignment operator behave the same as for the template class, but it defines only the types const_pointer, pointer, value_type, and the nested template class rebind.

auto_ptr

auto_ptr , auto_ptr_ref , element_type , get , operator auto_ptr , operator auto_ptr_ref , operator* , operator-> , operator= , release , reset , ~auto_ptr

   template<class T>
       class auto_ptr {
       template<U>
           struct auto_ptr_ref;
   public:
       typedef T element_type;
       explicit auto_ptr(T *p = 0) throw();
       auto_ptr(auto_ptr<T>& rhs) throw();
       template<class U>
           auto_ptr(auto_ptr<U>& rhs) throw();
       auto_ptr(auto_ptr_ref<T> rhs) throw();
       ~auto_ptr();
       template<class U>
           operator auto_ptr<U>() throw();
       template<class U>
           operator auto_ptr_ref<U>() throw();
       template<class U>
           auto_ptr<T>& operator=(auto_ptr<U>& rhs) throw();
       auto_ptr<T>& operator=(auto_ptr<T>& rhs) throw();
       T& operator*() const throw();
       T *operator->() const throw();
       T *get() const throw();
       T *release() const throw();
       void reset(T *p = 0);
       };

The class describes an object that stores a pointer to an allocated object of type T. The stored pointer must either be null or designate an object allocated by a new expression. An object constructed with a non-null pointer owns the pointer. It transfers ownership if its stored value is assigned to another object. (It replaces the stored value after a transfer with a null pointer.) The destructor for auto_ptr<T> deletes the allocated object if it owns it. Hence, an object of class auto_ptr<T> ensures that an allocated object is automatically deleted when control leaves a block, even via a thrown excepiton. You should not construct two auto_ptr<T> objects that own the same object.

You can pass an auto_ptr<T> object by value as an argument to a function call. You can return such an object by value as well. (Both operations depend on the implicit construction of intermediate objects of class auto_ptr<T>::auto_ptr_ref, by various subtle conversion rules.) You cannot, however, reliably manage a sequence of auto_ptr<T> objects with an STL container.

auto_ptr::auto_ptr

   explicit auto_ptr(T *p = 0) throw();
   auto_ptr(auto_ptr<T>& rhs) throw();
   auto_ptr(auto_ptr_ref<T> rhs) throw();
   template<class U>
       auto_ptr(auto_ptr<U>& rhs) throw();

The first constructor stores p as the pointer to the allocated object. The second constructor transfers ownership of the pointer stored in rhs, by storing rhs.release(). in the constructed object. The third constructor behaves the same as the second, except that it stores rhs.ref.release(), where ref is the reference stored in rhs.

The template constructor behaves the same as the second constructor, provided that a pointer to U can be implicitly converted to a pointer to T.

auto_ptr::auto_ptr_ref

   template<U>
       struct auto_ptr_ref {
       auto_ptr_ref(auto_ptr<U>& rhs);
       };

The member class describes an object that stores a reference to an object of class auto_ptr<T>.

auto_ptr::~auto_ptr

   ~auto_ptr();

The destructor evaluates the expression delete q.

auto_ptr::element_type

   typedef T element_type;

The type is a synonym for the template parameter T.

auto_ptr::get

   T *get() const throw();

The member function returns the stored pointer.

auto_ptr::operator=

   template<class U>
       auto_ptr<T>& operator=(auto_ptr<U>& rhs) throw();
   auto_ptr<T>& operator=(auto_ptr<>& rhs) throw();

The assignment evaluates the expression delete q, but only if the stored pointer value q changes as a result of the assignment. It then transfers ownership of the pointer stored in rhs, by storing rhs.release() in *this. The function returns *this.

auto_ptr::operator*

   T& operator*() const throw();

The indirection operator returns *get(). Hence, the stored pointer must not be null.

auto_ptr::operator->

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

The selection operator returns get(), so that the expression al->m behaves the same as (al.get())->m, where al is an object of class auto_ptr<T>. Hence, the stored pointer must not be null, and T must be a class, structure, or union type with a member m.

auto_ptr::operator auto_ptr

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

The type cast operator returns auto_ptr(*this).

auto_ptr::operator auto_ptr_ref

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

The type cast operator returns auto_ptr_ref(*this).

auto_ptr::release

   T *release() throw();

The member replaces the stored pointer with a null pointer and returns the previously stored pointer.

auto_ptr::reset

   void reset(T *p = 0);

The member function evaluates the expression delete q, but only if the stored pointer value q changes as a result of function call. It then replaces the stored pointer with p.

get_temporary_buffer

   template<class T>
       pair<T *, ptrdiff_t>
           get_temporary_buffer(ptrdiff_t n);

The template function allocates storage for a sequence of at most n elements of type T, from an unspecified source (which may well be the standard heap used by operator new). It returns a value pr, of type pair<T *, ptrdiff_t>. If the function allocates storage, pr.first designates the allocated storage and pr.second is the number of elements in the longest sequence the storage can hold. Otherwise, pr.first is a null pointer.

In this implementation, if a translator does not support member template functions, the template:

   template<class T>
       pair<T *, ptrdiff_t>
           get_temporary_buffer(ptrdiff_t n);

is replaced by:

   template<class T>
       pair<T *, ptrdiff_t>
           get_temporary_buffer(ptrdiff_t n, T *);

operator!=

   template<class T>
       bool operator!=(allocator<T>& lhs,
           allocator<T>& rhs);

The template operator returns false.

operator==

   template<class T>
       bool operator==(allocator<T>& lhs,
           allocator<T>& rhs);

The template operator returns true. (Two allocator objects should compare equal only if an object allocated through one can be deallocated through the other. If the value of one object is determined from another by assignment or by construction, the two object should compare equal.)

`raw_storage_iterator`

iter_type , element_type , raw_storage_iterator , operator* , operator= , operator++ , operator++

   template<class FwdIt, class T>
       class raw_storage_iterator
            : public iterator<output_iterator_tag,
                void, void, void, void> {
   public:
       typedef FwdIt iter_type;
       typedef T element_type;
       explicit raw_storage_iterator(FwdIt it);
       raw_storage_iterator<FwdIt, T>& operator*();
       raw_storage_iterator<FwdIt, T>&
           operator=(const T& val);
       raw_storage_iterator<FwdIt, T>& operator++();
       raw_storage_iterator<FwdIt, T> operator++(int);
       };

The class describes an output iterator that constructs objects of type T in the sequence it generates. An object of class raw_storage_iterator<FwdIt, T> accesses storage through a forward iterator object, of class FwdIt, that you specify when you construct the object. For an object it of class FwdIt, the expression &*it must designate unconstructed storage for the next object (of type T) in the generated sequence.

`raw_storage_iterator::element_type`

   typedef T element_type;

The type is a synonym for the template parameter T.

`raw_storage_iterator::iter_type`

   typedef FwdIt iter_type;

The type is a synonym for the template parameter FwdIt.

`raw_storage_iterator::operator*`

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

The indirection operator returns *this (so that operator=(const T&) can perform the actual store in an expression such as *x = val).

`raw_storage_iterator::operator=`

   raw_storage_iterator<FwdIt, T>& operator=(const T& val);

The assignment operator constructs the next object in the output sequence using the stored iterator value it, by evaluating the placement new expression new ((void *)&*it) T(val). The function returns *this.

`raw_storage_iterator::operator++`

   raw_storage_iterator<FwdIt, T>& operator++();
   raw_storage_iterator<FwdIt, T> operator++(int);

The first (preincrement) operator increments the stored output iterator object, then returns *this.

The second (postincrement) operator makes a copy of *this, increments the stored output iterator object, then returns the copy.

`raw_storage_iterator::raw_storage_iterator`

   explicit raw_storage_iterator(FwdIt it);

The constructor stores it as the output iterator object.

`return_temporary_buffer`

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

The template function frees the storage designated by p, which must be earlier allocated by a call to get_temporary_buffer.

uninitialized_copy

   template<class InIt, class FwdIt>
       FwdIt uninitialized_copy(InIt first, InIt last,
           FwdIt result);

The template function effectively executes:

   while (first != last)
       new ((void *)&*result++) U(*first++);
   return first;

where U is iterator_traits<InIt>::value_type, unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.

uninitialized_fill

   template<class FwdIt, class T>
       void uninitialized_fill(FwdIt first, FwdIt last,
           const T& x);

The template function effectively executes:

   while (first != last)
       new ((void *)&*first++) U(x);

where U is iterator_traits<FwdIt>::value_type, unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.

uninitialized_fill_n

   template<class FwdIt, class Size, class T>
       void uninitialized_fill_n(FwdIt first, Size n,
           const T& x);

The template function effectively executes:

   while (0 < n--)
       new ((void *)&*first++) U(x);

where U is iterator_traits<FwdIt>::value_type, unless the code throws an exception. In that case, all constructed objects are destroyed and the exception is rethrown.

References

iterator(C++std) , utility(C++std)