# 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.

### See also

Allocators, `construct`, `uninitialized_copy`, `uninitialized_fill`, `uninitialized_fill_n`, `raw_storage_iterator`

Copyright © 1999 Silicon Graphics, Inc. All Rights Reserved. TrademarkInformation