Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

core.internal.destruction

This module contains implementations for destroying instances of types
License:
Distributed under the Boost Software License 1.0. (See accompanying file LICENSE)
void destroy(bool initialize = true, T)(ref T obj)
if (is(T == struct));

void destroy(bool initialize = true, T)(T obj)
if (is(T == class));

void destroy(bool initialize = true, T)(T obj)
if (is(T == interface));

void destroy(bool initialize = true, T : U[n], U, size_t n)(ref T obj)
if (!is(T == struct));

void destroy(bool initialize = true, T)(ref T obj)
if (!is(T == struct) && !is(T == interface) && !is(T == class) && !__traits(isStaticArray, T));
Destroys the given object and optionally resets to initial state. It's used to destroy an object, calling its destructor or finalizer so it no longer references any other objects. It does not initiate a GC cycle or free any GC memory. If initialize is supplied false, the object is considered invalid after destruction, and should not be referenced.
Examples:
Reference type demonstration
class C
{
    struct Agg
    {
        static int dtorCount;

        int x = 10;
        ~this() { dtorCount++; }
    }

    static int dtorCount;

    string s = "S";
    Agg a;
    ~this() { dtorCount++; }
}

C c = new C();
assert(c.dtorCount == 0);   // destructor not yet called
assert(c.s == "S");         // initial state `c.s` is `"S"`
assert(c.a.dtorCount == 0); // destructor not yet called
assert(c.a.x == 10);        // initial state `c.a.x` is `10`
c.s = "T";
c.a.x = 30;
assert(c.s == "T");         // `c.s` is `"T"`
destroy(c);
assert(c.dtorCount == 1);   // `c`'s destructor was called
assert(c.s == "S");         // `c.s` is back to its inital state, `"S"`
assert(c.a.dtorCount == 1); // `c.a`'s destructor was called
assert(c.a.x == 10);        // `c.a.x` is back to its inital state, `10`

// check C++ classes work too!
extern (C++) class CPP
{
    struct Agg
    {
        __gshared int dtorCount;

        int x = 10;
        ~this() { dtorCount++; }
    }

    __gshared int dtorCount;

    string s = "S";
    Agg a;
    ~this() { dtorCount++; }
}

CPP cpp = new CPP();
assert(cpp.dtorCount == 0);   // destructor not yet called
assert(cpp.s == "S");         // initial state `cpp.s` is `"S"`
assert(cpp.a.dtorCount == 0); // destructor not yet called
assert(cpp.a.x == 10);        // initial state `cpp.a.x` is `10`
cpp.s = "T";
cpp.a.x = 30;
assert(cpp.s == "T");         // `cpp.s` is `"T"`
destroy!false(cpp);           // destroy without initialization
assert(cpp.dtorCount == 1);   // `cpp`'s destructor was called
assert(cpp.s == "T");         // `cpp.s` is not initialized
assert(cpp.a.dtorCount == 1); // `cpp.a`'s destructor was called
assert(cpp.a.x == 30);        // `cpp.a.x` is not initialized
destroy(cpp);
assert(cpp.dtorCount == 2);   // `cpp`'s destructor was called again
assert(cpp.s == "S");         // `cpp.s` is back to its inital state, `"S"`
assert(cpp.a.dtorCount == 2); // `cpp.a`'s destructor was called again
assert(cpp.a.x == 10);        // `cpp.a.x` is back to its inital state, `10`
Examples:
Value type demonstration
int i;
assert(i == 0);           // `i`'s initial state is `0`
i = 1;
assert(i == 1);           // `i` changed to `1`
destroy!false(i);
assert(i == 1);           // `i` was not initialized
destroy(i);
assert(i == 0);           // `i` is back to its initial state `0`