root/trunk/docsrc/interface.dd

Ddoc

$(SPEC_S Interfaces,

$(GRAMMAR
$(GNAME InterfaceDeclaration):
    $(B interface) $(I Identifier) $(GLINK BaseInterfaceList) $(GLINK InterfaceBody)
    $(LINK2 template.html#InterfaceTemplateDeclaration, $(I InterfaceTemplateDeclaration))

$(GNAME BaseInterfaceList):
    $(I Empty)
    $(B :) $(LINK2 class.html#InterfaceClasses, $(I InterfaceClasses))

$(GNAME InterfaceBody):
    $(B { })
    $(B {) $(GLINK InterfaceBodyDeclarations) $(B })

$(GNAME InterfaceBodyDeclarations):
    $(GLINK InterfaceBodyDeclaration)
    $(GLINK InterfaceBodyDeclaration) $(I InterfaceBodyDeclarations)

$(GNAME InterfaceBodyDeclaration):
    $(B {) $(LINK2 module.html#DeclDef, $(I DeclDef)) $(B })
)

    $(P Interfaces describe a list of functions that a class that inherits
    from the interface must implement.
    A class that implements an interface can be converted to a reference
    to that interface.)

    $(P Some operating system objects, like COM/OLE/ActiveX for Win32,
    have specialized interfaces. D interfaces that are compatible with
    COM/OLE/ActiveX are called $(LINK2 #COM-Interfaces, $(I COM Interfaces)).
    )

$(V2
    $(P $(LINK2 #CPP-Interfaces, $(I C++ Interfaces)) are another
    form of interfaces, meant to be binary compatible with C++.
    )
)

    $(P Interfaces cannot derive from classes; only from other interfaces.
    Classes cannot derive from an interface multiple times.
    )

------
interface D
{
    void foo();
}

class A : D, D  // error, duplicate interface
{
}
------

    An instance of an interface cannot be created.


------
interface D
{
    void foo();
}

...

D d = new D();      // error, cannot create instance of interface
------

$(V1
    $(P Interface member functions do not have implementations.)

------
interface D
{
    void bar() { }  // error, implementation not allowed
}
------
)
$(V2
    $(P Virtual interface member functions do not have implementations.
    Interfaces are expected to implement static or final functions.
    )

------
interface D
{
    void bar() { }  // error, implementation not allowed
    static void foo() { } // ok
    final void abc() { } // ok
}
------

    $(P Classes that inherit from an interface may not override final or
    static interface member functions.)

------
interface D {
    void bar();
    static void foo() { }
    final void abc() { }
}

class C : D {
    void bar() { } // ok
    void foo() { } // error, cannot override static D.foo()
    void abc() { } // error, cannot override final D.abc()
}
------

)
    $(P All interface functions must be defined in a class that inherits
    from that interface:
    )
------
interface D
{
    void foo();
}

class A : D
{
    void foo() { }  // ok, provides implementation
}

class B : D
{
    int foo() { }   // error, no void foo() implementation
}
------

    Interfaces can be inherited and functions overridden:

------
interface D
{
    int foo();
}

class A : D
{
    int foo() { return 1; }
}

class B : A
{
    int foo() { return 2; }
}

...

B b = new B();
b.foo();        // returns 2
D d = cast(D) b;    // ok since B inherits A's D implementation
d.foo();        // returns 2;
------

    $(P Interfaces can be reimplemented in derived classes:)

------
interface D
{
    int foo();
}

class A : D
{
    int foo() { return 1; }
}

class B : A, D
{
    int foo() { return 2; }
}

...

B b = new B();
b.foo();        // returns 2
D d = cast(D) b;
d.foo();        // returns 2
A a = cast(A) b;
D d2 = cast(D) a;
d2.foo();       // returns 2, even though it is A's D, not B's D
------

    $(P A reimplemented interface must implement all the interface
    functions, it does not inherit them from a super class:
    )

------
interface D
{
    int foo();
}

class A : D
{
    int foo() { return 1; }
}

class B : A, D
{
}       // error, no foo() for interface D
------

$(V2
$(SECTION2 $(LNAME2 InterfaceContracts, Interfaces with Contracts),

    $(P Interface member functions can have contracts even though there
    is no body for the function. The contracts are inherited by any
    class member function that implements that interface member function.
    )

---
interface I
{
    int foo(int i)
      in { assert(i > 7); }
      out (result) { assert(result & 1); }

    void bar();
}
---
)

$(SECTION2 $(LNAME2 ConstInterface, Const and Immutable Interfaces),
    $(P If an interface has $(CODE const) or $(CODE immutable) storage
    class, then all members of the interface are
    $(CODE const) or $(CODE immutable).
    This storage class is not inherited.
    )
)
)

$(SECTION2 $(LNAME2 COM-Interfaces, COM Interfaces),

    $(P A variant on interfaces is the COM interface. A COM interface is
    designed to map directly onto a Windows COM object. Any COM object
    can be represented by a COM interface, and any D object with
    a COM interface can be used by external COM clients.
    )

    $(P A COM interface is defined as one that derives from the interface
    $(TT std.c.windows.com.IUnknown). A COM interface differs from
    a regular D interface in that:
    )

    $(UL
    $(LI It derives from the interface $(TT std.c.windows.com.IUnknown).)
    $(LI It cannot be the argument of a $(I DeleteExpression).)
    $(LI References cannot be upcast to the enclosing class object, nor
    can they be downcast to a derived interface. To accomplish this,
    an appropriate $(TT QueryInterface()) would have to be implemented
    for that interface in standard COM fashion.)
    $(LI Classes derived from COM interfaces are COM classes.)
    $(LI The default linkage for member functions of COM classes
    is $(TT extern(System)).)
    $(LI The first member of the $(TT vtbl[]) is not the pointer
    to the InterfaceInfo, but the first virtual function pointer.)
    )
)

$(V2
$(SECTION2 $(LNAME2 CPP-Interfaces, C++ Interfaces),

    $(P C++ interfaces are interfaces declared with C++ linkage:
    )

---
extern (C++) interface Ifoo
{
    void foo();
    void bar();
}
---

    $(P which is meant to correspond with the following C++ declaration:)

$(CPPCODE
class Ifoo
{
    virtual void foo();
    virtual void bar();
};
)

    $(P Any interface that derives from a C++ interface is also
    a C++ interface.
    A C++ interface differs from a D interface in that:
    )

    $(UL
    $(LI It cannot be the argument of a $(I DeleteExpression).)
    $(LI References cannot be upcast to the enclosing class object, nor
    can they be downcast to a derived interface.)
    $(LI The C++ calling convention is the default convention
    for its member functions, rather than the D calling convention.)
    $(LI The first member of the $(TT vtbl[]) is not the pointer
    to the $(TT Interface), but the first virtual function pointer.)
    )
)
)

)

Macros:
    TITLE=Interfaces
    WIKI=Interface