destroy

Category: allocators	Component type: function

Prototype

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

Requirements on types

• T's destructor, ~T, is accessible.

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

Preconditions

• pointer points to a valid object of type T.

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

Complexity

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.

See also