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