D Programming Language 1.0

Last update Sun Dec 30 20:34:42 2012

# Classes

The object-oriented features of D all come from classes. The class hierarchy has as its root the class Object. Object defines a minimum level of functionality that each derived class has, and a default implementation for that functionality.

Classes are programmer defined types. Support for classes are what make D an object oriented language, giving it encapsulation, inheritance, and polymorphism. D classes support the single inheritance paradigm, extended by adding support for interfaces. Class objects are instantiated by reference only.

A class can be exported, which means its name and all its non-private members are exposed externally to the DLL or EXE.

A class declaration is defined:

    ClassDeclaration:
        class Identifier BaseClassListopt ClassBody
        ClassTemplateDeclaration

    BaseClassList:
        : SuperClass
        : SuperClass , Interfaces
        : Interfaces

    SuperClass:
        Identifier

    Interfaces:
        Interface
        Interface , Interfaces

    Interface:
        Identifier

    ClassBody:
        { }
        { ClassBodyDeclarations }

    ClassBodyDeclarations:
        ClassBodyDeclaration
        ClassBodyDeclaration ClassBodyDeclarations

    ClassBodyDeclaration:
        DeclDef
        Invariant
        ClassAllocator
        ClassDeallocator

Classes consist of:

- a super class
- interfaces
- dynamic fields
- static fields
- types
- member functions
  - static member functions
  - Virtual Functions
  - Synchronized Functions
  - Constructors
  - Destructors
  - Static Constructors
  - Static Destructors
  - SharedStaticConstructors
  - SharedStaticDestructors
  - Class Invariants
  - Unit Tests
  - Class Allocators
  - Class Deallocators

A class is defined:

    class Foo {
      ... members ...
    }

Note that there is no trailing ; after the closing } of the class definition. It is also not possible to declare a variable var like:

    class Foo { } var;

Instead:

    class Foo { }
    Foo var;

### Access Control

Access to class members is controlled using ProtectionAttributes. The default protection attribute is `public`. Access control does not affect visibility.

### Fields

Class members are always accessed with the . operator.

Members of a base class can be accessed by prepending the name of the base class followed by a dot:

    class A { int a; }
    class B : A { int a; }

    void foo(B b) {
      b.a = 3;   // accesses field B.a
      b.A.a = 4; // accesses field A.a

The D compiler is free to rearrange the order of fields in a class to optimally pack them in an implementation-defined manner. Consider the fields much like the local variables in a function - the compiler assigns some to registers and shuffles others around all to get the optimal stack frame layout. This frees the code designer to organize the fields in a manner that makes the code more readable rather than being forced to organize it according to machine optimization rules. Explicit control of field layout is provided by struct/union types, not classes.

### Field Properties

The .offsetof property gives the offset in bytes of the field from the beginning of the class instantiation. .offsetof can only be applied to expressions which produce the type of the field itself, not the class type:

    class Foo {
      int x;
    }
    ...
    void test(Foo foo) {
      size_t o;

      o = Foo.x.offsetof; // error, Foo.x needs a 'this' reference
      o = foo.x.offsetof; // ok
    }

### Class Properties

The .tupleof property returns an ExpressionTuple of all the fields in the class, excluding the hidden fields and the fields in the base class.

    class Foo { int x; long y; }
    void test(Foo foo) {
      foo.tupleof[0] = 1; // set foo.x to 1
      foo.tupleof[1] = 2; // set foo.y to 2
      foreach (x; foo.tupleof)
        writef(x);        // prints 12
    }

The properties .__vptr and .__monitor give access to the class object's vtbl[] and monitor, respectively, but should not be used in user code.

### Super Class

All classes inherit from a super class. If one is not specified, it inherits from Object. Object forms the root of the D class inheritance hierarchy.

### Member Functions

Non-static member functions have an extra hidden parameter called this through which the class object's other members can be accessed.

### Synchronized Functions

Synchronized class member functions have the storage class `synchronized`. A static member function is synchronized on the classinfo object for the class, which means that one monitor is used for all static synchronized member functions for that class. For non-static synchronized functions, the monitor used is part of the class object. For example:

    class Foo {
      synchronized void bar() { ...statements... }
    }

is equivalent to (as far as the monitors go):

    class Foo {
      void bar() {
        synchronized (this) { ...statements... }
      }
    }

Structs do not have synchronized member functions.

### Constructors

    Constructor:
            this Parameters FunctionBody

Members are always initialized to the default initializer for their type, which is usually 0 for integer types and NAN for floating point types. This eliminates an entire class of obscure problems that come from neglecting to initialize a member in one of the constructors. In the class definition, there can be a static initializer to be used instead of the default:

    class Abc {
      int a;      // default initializer for a is 0
      long b = 7; // default initializer for b is 7
      float f;    // default initializer for f is NAN
    }

This static initialization is done before any constructors are called.

Constructors are defined with a function name of this and having no return value:

    class Foo {
      this(int x)  // declare constructor for Foo
      {   ...
      }
      this()
      {   ...
      }
    }

Base class construction is done by calling the base class constructor by the name super:

    class A { this(int y) { } }

    class B : A {
      int j;
      this() {
        ...
        super(3);  // call base constructor A.this(3)
        ...
      }
    }

Constructors can also call other constructors for the same class in order to share common initializations (this is called delegating constructors):

    class C {
      int j;
      this() {
        ...
      }
      this(int i) {
        this();
        j = i;
      }
    }

If no call to constructors via this or super appear in a constructor, and the base class has a constructor, a call to super() is inserted at the beginning of the constructor.

If there is no constructor for a class, but there is a constructor for the base class, a default constructor of the form:

    this() { }

is implicitly generated.

Class object construction is very flexible, but some restrictions apply:

1. It is illegal for constructors to mutually call each other, although the compiler is not required to detect it. It will result in undefined behavior.

       this() { this(1); }
       this(int i) { this(); } // illegal, cyclic constructor calls

2. If any constructor call appears inside a constructor, any path through the constructor must make exactly one constructor call:

       this()  { a || super(); }       // illegal

       this() { (a) ? this(1) : super(); }     // ok

       this() {
         for (...) {
           super();  // illegal, inside loop
         }
       }

3. It is illegal to refer to this implicitly or explicitly prior to making a constructor call.
4. Constructor calls cannot appear after labels (in order to make it easy to check for the previous conditions in the presence of goto's).

Instances of class objects are created with NewExpressions:

    A a = new A(3);

The following steps happen:

1. Storage is allocated for the object. If this fails, rather than return null, an OutOfMemoryError is thrown. Thus, tedious checks for null references are unnecessary.
2. The raw data is statically initialized using the values provided in the class definition. The pointer to the vtbl[] (the array of pointers to virtual functions) is assigned. This ensures that constructors are passed fully formed objects for which virtual functions can be called. This operation is equivalent to doing a memory copy of a static version of the object onto the newly allocated one, although more advanced compilers may be able to optimize much of this away.
3. If there is a constructor defined for the class, the constructor matching the argument list is called.
4. If class invariant checking is turned on, the class invariant is called at the end of the constructor.

### Destructors

    Destructor:
        ~ this ( ) FunctionBody

The garbage collector calls the destructor function when the object is deleted. The syntax is:

    class Foo {
      ~this() // destructor for Foo
      {
      }
    }

There can be only one destructor per class, the destructor does not have any parameters, and has no attributes. It is always virtual.

The destructor is expected to release any resources held by the object.

The program can explicitly inform the garbage collector that an object is no longer referred to (with the delete expression), and then the garbage collector calls the destructor immediately, and adds the object's memory to the free storage. The destructor is guaranteed to never be called twice.

The destructor for the super class automatically gets called when the destructor ends. There is no way to call the super destructor explicitly.

The garbage collector is not guaranteed to run the destructor for all unreferenced objects. Furthermore, the order in which the garbage collector calls destructors for unreference objects is not specified. This means that when the garbage collector calls a destructor for an object of a class that has members that are references to garbage collected objects, those references may no longer be valid. This means that destructors cannot reference sub objects. This rule does not apply to auto objects or objects deleted with the DeleteExpression, as the destructor is not being run by the garbage collector, meaning all references are valid.

Objects referenced from the data segment never get collected by the gc.

### Static Constructors

    StaticConstructor:
        static this ( ) FunctionBody

A static constructor is a function that performs initializations before the `main()` function gets control. Static constructors are used to initialize static class members with values that cannot be computed at compile time.

Static constructors in other languages are built implicitly by using member initializers that can't be computed at compile time. The trouble with this stems from not having good control over exactly when the code is executed, for example:

    class Foo {
      static int a = b + 1;
      static int b = a * 2;
    }

What values do a and b end up with, what order are the initializations executed in, what are the values of a and b before the initializations are run, is this a compile error, or is this a runtime error? Additional confusion comes from it not being obvious if an initializer is static or dynamic.

D makes this simple. All member initializations must be determinable by the compiler at compile time, hence there is no order-of-evaluation dependency for member initializations, and it is not possible to read a value that has not been initialized. Dynamic initialization is performed by a static constructor, defined with a special syntax `static this()`.

    class Foo {
      static int a;         // default initialized to 0
      static int b = 1;
      static int c = b + a; // error, not a constant initializer

      static this()    // static constructor
      {
        a = b + 1;          // a is set to 2
        b = a * 2;          // b is set to 4
      }
    }

If `main()` returns normally (does not throw an exception), the static destructor is added to the list of functions to be called on program termination. Static constructors have empty parameter lists.

Static constructors within a module are executed in the lexical order in which they appear. All the static constructors for modules that are directly or indirectly imported are executed before the static constructors for the importer.

The static in the static constructor declaration is not an attribute, it must appear immediately before the this:

    class Foo {
      static this() { ... } // a static constructor
      static private this() { ... } // not a static constructor
      static {
        this() { ... }      // not a static constructor
      }
      static:
        this() { ... }      // not a static constructor
    }

### Static Destructors

    StaticDestructor:
        static ~ this ( ) FunctionBody

A static destructor is defined as a special static function with the syntax `static ~this()`.

    class Foo {
      static ~this() // static destructor
      {
      }
    }

A static destructor gets called on program termination, but only if the static constructor completed successfully. Static destructors have empty parameter lists. Static destructors get called in the reverse order that the static constructors were called in.

The static in the static destructor declaration is not an attribute, it must appear immediately before the ~this:

    class Foo {
      static ~this() { ... }  // a static destructor
      static private ~this() { ... } // not a static destructor
      static
      {
        ~this() { ... }  // not a static destructor
      }
      static:
        ~this() { ... }  // not a static destructor
    }

### Class Invariants

    Invariant:
        invariant ( ) BlockStatement

Class invariants are used to specify characteristics of a class that always must be true (except while executing a member function). For example, a class representing a date might have an invariant that the day must be 1..31 and the hour must be 0..23:

    class Date {
      int day;
      int hour;

      invariant() {
        assert(1 <= day && day <= 31);
        assert(0 <= hour && hour < 24);
      }
    }

The class invariant is a contract saying that the asserts must hold true. The invariant is checked when a class constructor completes, at the start of the class destructor. For public or exported functions, the order of execution is:

1. preconditions
2. invariant
3. body
4. invariant
5. postconditions

The code in the invariant may not call any public non-static members of the class, either directly or indirectly. Doing so will result in a stack overflow, as the invariant will wind up being called in an infinitely recursive manner.

Since the invariant is called at the start of public or exported members, such members should not be called from constructors.

    class Foo {
      public void f() { }
      private void g() { }

      invariant() {
        f();  // error, cannot call public member function from invariant
        g();  // ok, g() is not public
      }
    }

The invariant can be checked when a class object is the argument to an `assert()` expression, as:

    Date mydate;
    ...
    assert(mydate);         // check that class Date invariant holds

Invariants contain assert expressions, and so when they fail, they throw a `AssertError`s. Class invariants are inherited, that is, any class invariant is implicitly anded with the invariants of its base classes.

There can be only one Invariant per class.

When compiling for release, the invariant code is not generated, and the compiled program runs at maximum speed.

### Class Allocators

    ClassAllocator:
        new Parameters FunctionBody

A class member function of the form:

    new(uint size) {
      ...
    }

is called a class allocator. The class allocator can have any number of parameters, provided the first one is of type uint. Any number can be defined for a class, the correct one is determined by the usual function overloading rules. When a new expression:

    new Foo;

is executed, and Foo is a class that has an allocator, the allocator is called with the first argument set to the size in bytes of the memory to be allocated for the instance. The allocator must allocate the memory and return it as a `void*`. If the allocator fails, it must not return a null, but must throw an exception. If there is more than one parameter to the allocator, the additional arguments are specified within parentheses after the new in the NewExpression:

    class Foo {
      this(char[] a) { ... }

      new(uint size, int x, int y) {
        ...
      }
    }

    ...

    new(1,2) Foo(a);        // calls new(Foo.sizeof,1,2)

Derived classes inherit any allocator from their base class, if one is not specified.

The class allocator is not called if the instance is created on the stack.

See also Explicit Class Instance Allocation.

### Class Deallocators

    ClassDeallocator:
        delete Parameters FunctionBody

A class member function of the form:

    delete(void *p) {
      ...
    }

is called a class deallocator. The deallocator must have exactly one parameter of type `void*`. Only one can be specified for a class. When a delete expression:

    delete f;

is executed, and f is a reference to a class instance that has a deallocator, the deallocator is called with a pointer to the class instance after the destructor (if any) for the class is called. It is the responsibility of the deallocator to free the memory.

Derived classes inherit any deallocator from their base class, if one is not specified.

The class allocator is not called if the instance is created on the stack.

See also Explicit Class Instance Allocation.

### Scope Classes

A scope class is a class with the scope attribute, as in:

    scope class Foo { ... }

The scope characteristic is inherited, so if any classes derived from a scope class are also scope.

An scope class reference can only appear as a function local variable. It must be declared as being scope:

    scope class Foo { ... }

    void func() {
      Foo f;    // error, reference to scope class must be scope
      scope Foo g = new Foo(); // correct
    }

When an scope class reference goes out of scope, the destructor (if any) for it is automatically called. This holds true even if the scope was exited via a thrown exception.

### Final Classes

Final classes cannot be subclassed:

    final class A { }
    class B : A { }  // error, class A is final

## Nested Classes

A nested class is a class that is declared inside the scope of a function or another class. A nested class has access to the variables and other symbols of the classes and functions it is nested inside:

    class Outer {
      int m;

      class Inner {
        int foo() {
          return m;   // Ok to access member of Outer
        }
      }
    }

    void func() {
      int m;

      class Inner {
        int foo() {
          return m; // Ok to access local variable m of func()
        }
      }
    }

If a nested class has the static attribute, then it can not access variables of the enclosing scope that are local to the stack or need a this:

    class Outer {
      int m;
      static int n;

      static class Inner {
        int foo() {
          return m;   // Error, Inner is static and m needs a this
          return n;   // Ok, n is static
        }
      }
    }

    void func() {
      int m;
      static int n;

      static class Inner {
        int foo() {
          return m;   // Error, Inner is static and m is local to the stack
          return n;   // Ok, n is static
        }
      }
    }

Non-static nested classes work by containing an extra hidden member (called the context pointer) that is the frame pointer of the enclosing function if it is nested inside a function, or the this of the enclosing class's instance if it is nested inside a class.

When a non-static nested class is instantiated, the context pointer is assigned before the class's constructor is called, therefore the constructor has full access to the enclosing variables. A non-static nested class can only be instantiated when the necessary context pointer information is available:

    class Outer {
      class Inner { }

      static class SInner { }
    }

    void func() {
      class Nested { }

      Outer o = new Outer;        // Ok
      Outer.Inner oi = new Outer.Inner;   // Error, no 'this' for Outer
      Outer.SInner os = new Outer.SInner; // Ok

      Nested n = new Nested;      // Ok
    }

While a non-static nested class can access the stack variables of its enclosing function, that access becomes invalid once the enclosing function exits:

    class Base {
      int foo() { return 1; }
    }

    Base func() {
      int m = 3;

      class Nested : Base {
        int foo() { return m; }
      }

      Base b = new Nested;

      assert(b.foo() == 3);       // Ok, func() is still active
      return b;
    }

    int test() {
      Base b = func();
      return b.foo();             // Error, func().m is undefined
    }

If this kind of functionality is needed, the way to make it work is to make copies of the needed variables within the nested class's constructor:

    class Base {
      int foo() { return 1; }
    }

    Base func() {
      int m = 3;

      class Nested : Base {
        int m_;

        this() { m_ = m; }
        int foo() { return m_; }
      }

      Base b = new Nested;

      assert(b.foo() == 3);       // Ok, func() is still active
      return b;
    }

    int test() {
      Base b = func();
      return b.foo();             // Ok, using cached copy of func().m
    }

A this can be supplied to the creation of an inner class instance by prefixing it to the NewExpression:

    class Outer {
      int a;

      class Inner {
        int foo() {
          return a;
        }
      }
    }

    int bar() {
      Outer o = new Outer;
      o.a = 3;
      Outer.Inner oi = o.new Inner;
      return oi.foo();    // returns 3
    }

Here o supplies the this to the outer class instance of Outer.

The property .outer used in a nested class gives the this pointer to its enclosing class. If the enclosing context is not a class, the .outer will give the pointer to it as a void* type.

    class Outer {
      class Inner {
        Outer foo() {
          return this.outer;
        }
      }

      void bar() {
        Inner i = new Inner;
        assert(this == i.foo());
      }
    }

    void test() {
      Outer o = new Outer;
      o.bar();
    }

### Anonymous Nested Classes

An anonymous nested class is both defined and instantiated with a NewAnonClassExpression:

    NewAnonClassExpression:
        new AllocatorArgumentsopt class ClassArgumentsopt SuperClassopt Interfacesopt ClassBody

    ClassArguments:
    	( ArgumentListopt )

which is equivalent to:

    class Identifier : SuperClass Interfaces
            ClassBody

    new (ArgumentList) Identifier (ArgumentList);

where Identifier is the name generated for the anonymous nested class.

)
Forums | Comments | D | Search | Downloads | Home
Copyright © 1999-2012 by Digital Mars ®, All Rights Reserved | Page generated by Ddoc.