destroy


Category: allocators	Component type: function

Prototype

Destroy is an overloaded name; there are actually two destroy functions.

template <class T> void destroy(T* pointer);

template <class ForwardIterator>
void destroy(ForwardIterator first
ForwardIterator last);

Description

In C++ the operator delete destroys an object by calling its destructor and then deallocates the memory where that object was stored. Occasionally however it is useful to separate those two operations. [1] Destroy calls an object's destructor without deallocating the memory where the object was stored.

The first version of destroy destroys the object pointed to by pointer by calling the destructor T::~T(). The memory pointed to by pointer is not deallocated and can be reused for some other object.

The second version of destroy destroys all of the objects in the range of elements [first last). It is equivalent to calling destroy(&*i) for each iterator i in the range [first last).

Definition

Defined in the standard header memory and in the nonstandard backward-compatibility header algo.h. The destroy algorithms are no longer part of the C++ standard; they were present in early drafts and they are retained in this implementation for backward compatibility.

Requirements on types

For the first version of destroy:

T's destructor ~T is accessible.

For the second version of destroy:

ForwardIterator is a model of Forward Iterator.
ForwardIterator is mutable.
ForwardIterator's value type has an accessible destructor.

Preconditions

For the first version of destroy:

pointer points to a valid object of type T.

For the second version of destroy:

[first last) is a valid range.
Each iterator i in [first last) points to a valid object.

Complexity

The run-time complexity of the second version is linear: it calls the destructor exactly last - first times.

Example

class Int {
public:
  Int(int x) : val(x) {}
  int get() { return val; }
private:
  int val;
};

int main()
{
  Int A[] = { Int(1)
Int(2)
Int(3)
Int(4) };

  destroy(A
A + 4);
  construct(A
Int(10));
  construct(A + 1
Int(11));
  construct(A + 2
Int(12));
  construct(A + 3
Int(13));
}

Notes

[1] In particular destroy along with other low-level memory allocation primitives is used to implement container classes.