declaration.dd

Ddoc

$(SPEC_S Declarations,

$(GRAMMAR
$(GNAME Declaration):
    $(GLINK AliasDeclaration)
    $(GLINK AliasThisDeclaration)
    $(GLINK Decl)

$(GNAME AliasDeclaration):
    $(D alias) $(GLINK BasicType) $(GLINK Declarator)
    $(D alias) $(GLINK AliasInitializerList)

$(GNAME AliasInitializerList):
    $(GLINK AliasInitializer)
    $(GLINK AliasInitializer) $(D ,) $(I AliasInitializerList)

$(GNAME AliasInitializer):
    $(I Identifier) $(D =) $(GLINK Type)

$(GNAME AliasThisDeclaration):
    $(D alias) $(I Identifier) $(D this)

$(GNAME Decl):
    $(GLINK StorageClasses) $(I Decl)
    $(GLINK BasicType) $(GLINK Declarators) $(D ;)
    $(GLINK BasicType) $(GLINK Declarator) $(GLINK2 function, FunctionBody)
    $(GLINK AutoDeclaration)

$(GNAME Declarators):
    $(I DeclaratorInitializer)
    $(I DeclaratorInitializer) $(D ,) $(GLINK DeclaratorIdentifierList)

$(GNAME DeclaratorInitializer):
    $(GLINK Declarator)
    $(GLINK Declarator) $(D =) $(GLINK Initializer)

$(GNAME DeclaratorIdentifierList):
    $(GLINK DeclaratorIdentifier)
    $(GLINK DeclaratorIdentifier) $(D ,) $(I DeclaratorIdentifierList)

$(GNAME DeclaratorIdentifier):
    $(I Identifier)
    $(I Identifier) $(D =) $(GLINK Initializer)

$(GNAME BasicType):
    $(GLINK BasicTypeX)
    $(D .)$(GLINK IdentifierList)
    $(GLINK IdentifierList)
    $(GLINK Typeof)
    $(GLINK Typeof) $(D .) $(GLINK IdentifierList)
    $(D const$(LPAREN)) $(GLINK Type) $(D $(RPAREN))
    $(D immutable$(LPAREN)) $(GLINK Type) $(D $(RPAREN))
    $(D shared$(LPAREN)) $(GLINK Type) $(D $(RPAREN))
    $(D inout$(LPAREN)) $(GLINK Type) $(D $(RPAREN))

$(GNAME BasicTypeX):
$(MULTICOLS 5,
    $(D bool)
    $(D byte)
    $(D ubyte)
    $(D short)
    $(D ushort)
    $(D int)
    $(D uint)
    $(D long)
    $(D ulong)
    $(D char)
    $(D wchar)
    $(D dchar)
    $(D float)
    $(D double)
    $(D real)
    $(D ifloat)
    $(D idouble)
    $(D ireal)
    $(D cfloat)
    $(D cdouble)
    $(D creal)
    $(D void))

$(GNAME BasicType2):
    $(D *)
    $(D [ ])
    $(D [) $(VEXPRESSION) $(D ])
    $(D [) $(VEXPRESSION) .. $(VEXPRESSION) $(D ])
    $(D [) $(GLINK Type) $(D ])
    $(D delegate) $(GLINK Parameters) $(GLINK MemberFunctionAttributes)$(OPT)
    $(D function) $(GLINK Parameters) $(GLINK FunctionAttributes)$(OPT)

$(GNAME Declarator):
    $(GLINK BasicType2)$(OPT) $(D $(LPAREN)) $(I Declarator) $(D $(RPAREN)) $(GLINK DeclaratorSuffixes)$(OPT)
    $(GLINK BasicType2)$(OPT) $(I Identifier) $(GLINK DeclaratorSuffixes)$(OPT)

$(GNAME DeclaratorSuffixes):
    $(GLINK DeclaratorSuffix)
    $(GLINK DeclaratorSuffix) $(I DeclaratorSuffixes)

$(GNAME DeclaratorSuffix):
    $(D [ ])
    $(D [) $(VEXPRESSION) $(D ])
    $(D [) $(GLINK Type) $(D ])
    $(GLINK2 template, TemplateParameters)$(OPT) $(GLINK Parameters) $(GLINK MemberFunctionAttributes)$(OPT) $(GLINK2 template, Constraint)$(OPT)

$(GNAME IdentifierList):
    $(I Identifier)
    $(I Identifier) $(D .) $(I IdentifierList)
    $(GLINK2 template, TemplateInstance)
    $(GLINK2 template, TemplateInstance) $(D .) $(I IdentifierList)

$(GNAME StorageClasses):
    $(GLINK StorageClass)
    $(GLINK StorageClass) $(I StorageClasses)

$(GNAME StorageClass):
$(MULTICOLS 5,     $(D abstract)
    $(D auto)
    $(GLINK TypeCtor)
    $(D deprecated)
    $(D enum)
    $(RELATIVE_LINK2 extern, $(D extern))
    $(D final)
    $(D nothrow)
    $(D override)
    $(D pure)
    $(D __gshared)
    $(GLINK Property)
    $(D scope)
    $(D static)
    $(D synchronized)

$(GNAME Property):
    $(D @) $(GLINK PropertyIdentifier)

$(GNAME PropertyIdentifier):
    $(D property)
    $(D safe)
    $(D trusted)
    $(D system)
    $(D disable)

$(GNAME TypeCtors):
    $(GLINK TypeCtor)
    $(GLINK TypeCtor) $(I TypeCtors)

$(GNAME TypeCtor):
    $(D const)
    $(D immutable)
    $(D inout)
    $(D shared)

$(GNAME Type):
    $(GLINK TypeCtors)$(OPT) $(GLINK BasicType)
    $(GLINK TypeCtors)$(OPT) $(GLINK BasicType) $(GLINK Declarator2)

$(GNAME Declarator2):
    $(GLINK BasicType2)$(OPT) $(GLINK DeclaratorSuffixes)$(OPT)
    $(GLINK BasicType2)$(OPT) $(D $(LPAREN)) $(I Declarator2) $(D $(RPAREN)) $(GLINK DeclaratorSuffixes)$(OPT)

$(GNAME Parameters):
    $(D $(LPAREN)) $(GLINK ParameterList) $(D $(RPAREN))
    $(D ( ))

$(GNAME ParameterList):
    $(GLINK Parameter)
    $(GLINK Parameter) $(D ,) $(I ParameterList)
    $(D ...)

$(GNAME Parameter):
    $(I InOut)$(OPT) $(GLINK BasicType) $(GLINK Declarator)
    $(I InOut)$(OPT) $(GLINK BasicType) $(GLINK Declarator) $(D ...)
    $(I InOut)$(OPT) $(GLINK BasicType) $(GLINK Declarator) = $(GLINK DefaultInitializerExpression)
    $(I InOut)$(OPT) $(GLINK Type)
    $(I InOut)$(OPT) $(GLINK Type) $(D ...)

$(GNAME InOut):
    $(I InOutX)
    $(I InOut InOutX)

$(GNAME InOutX):
    $(D auto)
    $(GLINK TypeCtor)
    $(D final)
    $(D in)
    $(D lazy)
    $(D out)
    $(D ref)
    $(D scope)

$(GNAME FunctionAttributes):
    $(GLINK FunctionAttribute)
    $(GLINK FunctionAttribute) $(I FunctionAttributes)

$(GNAME FunctionAttribute):
    $(D nothrow)
    $(D pure)
    $(GLINK Property)

$(GNAME MemberFunctionAttributes):
    $(GLINK MemberFunctionAttribute)
    $(GLINK MemberFunctionAttribute) $(I MemberFunctionAttributes)

$(GNAME MemberFunctionAttribute):
    $(D const)
    $(D immutable)
    $(D inout)
    $(D shared)
    $(GLINK FunctionAttribute)

$(GNAME DefaultInitializerExpression):
    $(ASSIGNEXPRESSION)
    $(D $(XLINK2 traits.html#specialkeywords, __FILE__))
    $(D $(XLINK2 traits.html#specialkeywords, __MODULE__))
    $(D $(XLINK2 traits.html#specialkeywords, __LINE__))
    $(D $(XLINK2 traits.html#specialkeywords, __FUNCTION__))
    $(D $(XLINK2 traits.html#specialkeywords, __PRETTY_FUNCTION__))

$(GNAME Initializer):
    $(GLINK VoidInitializer)
    $(GLINK NonVoidInitializer)

$(GNAME NonVoidInitializer):
    $(ASSIGNEXPRESSION)
    $(GLINK ArrayInitializer)
    $(GLINK StructInitializer)

$(GNAME ArrayInitializer):
    $(D [ ])
    $(D [) $(GLINK ArrayMemberInitializations) $(D ])

$(GNAME ArrayMemberInitializations):
    $(GLINK ArrayMemberInitialization)
    $(GLINK ArrayMemberInitialization) $(D ,)
    $(GLINK ArrayMemberInitialization) $(D ,) $(I ArrayMemberInitializations)

$(GNAME ArrayMemberInitialization):
    $(GLINK NonVoidInitializer)
    $(ASSIGNEXPRESSION) $(D :) $(GLINK NonVoidInitializer)

$(GNAME StructInitializer):
    $(D {  })
    $(D {) $(GLINK StructMemberInitializers) $(D })

$(GNAME StructMemberInitializers):
    $(GLINK StructMemberInitializer)
    $(GLINK StructMemberInitializer) $(D ,)
    $(GLINK StructMemberInitializer) $(D ,) $(I StructMemberInitializers)

$(GNAME StructMemberInitializer):
    $(GLINK NonVoidInitializer)
    $(I Identifier) $(D :) $(GLINK NonVoidInitializer))
)

$(H3 Declaration Syntax)

$(P Declaration syntax generally reads right to left:)

--------------------
int x;    // x is an int
int* x;   // x is a pointer to int
int** x;  // x is a pointer to a pointer to int
int[] x;  // x is an array of ints
int*[] x; // x is an array of pointers to ints
int[]* x; // x is a pointer to an array of ints
--------------------

$(P Arrays read right to left as well:)

--------------------
int[3] x;     // x is an array of 3 ints
int[3][5] x;  // x is an array of 5 arrays of 3 ints
int[3]*[5] x; // x is an array of 5 pointers to arrays of 3 ints
--------------------

$(P
Pointers to functions are declared using the $(D function) keyword:
)

--------------------
int function(char) x; // x is a pointer to
                     // a function taking a char argument
                     // and returning an int
int function(char)[] x; // x is an array of
                     // pointers to functions
                     // taking a char argument
                     // and returning an int
--------------------

$(P
C-style array, function pointer and pointer to array declarations are deprecated:
)

--------------------
int x[3];          // x is an array of 3 ints
int x[3][5];       // x is an array of 3 arrays of 5 ints
int (*x[5])[3];    // x is an array of 5 pointers to arrays of 3 ints
int (*x)(char);    // x is a pointer to a function taking a char argument
                   // and returning an int
int (*[] x)(char); // x is an array of pointers to functions
                   // taking a char argument and returning an int
--------------------

$(P
In a declaration declaring multiple symbols, all the declarations
must be of the same type:
)

--------------------
int x,y;   // x and y are ints
int* x,y;  // x and y are pointers to ints
int x,*y;  // error, multiple types
int[] x,y; // x and y are arrays of ints
int x[],y; // error, multiple types
--------------------

$(H3 $(LNAME2 AutoDeclaration, Implicit Type Inference))

$(GRAMMAR
$(GNAME AutoDeclaration):
    $(GLINK StorageClasses) $(I AutoDeclarationX) $(D ;)

$(GNAME AutoDeclarationX):
    $(I Identifier) $(D =) $(GLINK Initializer)
    $(I AutoDeclarationX) $(D ,) $(I Identifier) $(D =) $(GLINK Initializer)
)

        $(P If a declaration starts with a $(I StorageClass) and has
        a $(I NonVoidInitializer) from which the type can be inferred,
        the type on the declaration can be omitted.
        )

----------
static x = 3;      // x is type int
auto y = 4u;       // y is type uint

auto s = "string"; // s is type immutable(char)[]

class C { ... }

auto c = new C();  // c is a handle to an instance of class C
----------

        $(P The $(I NonVoidInitializer) cannot contain forward references
        (this restriction may be removed in the future).
        The implicitly inferred type is statically bound
        to the declaration at compile time, not run time.
        )

        $(P An $(GLINK2 expression, ArrayLiteral)
        is inferred to be a dynamic array
        type rather than a static array:)

---
auto v = ["hello", "world"]; // type is string[], not string[2]
---




$(H3 $(LNAME2 alias, Type Aliasing))

        $(P
	$(GLINK AliasDeclaration)s create a symbol that is an alias for another type,
	and can be used anywhere that other type may appear.
        )

--------------------
alias abc.Foo.bar myint;
--------------------

        $(P
        Aliased types are semantically identical to the types they are aliased to. The
        debugger cannot distinguish between them, and there is no difference as far as function
        overloading is concerned. For example:
        )

--------------------
alias int myint;

void foo(int x) { . }
void foo(myint m) { . } // error, multiply defined function foo
--------------------



$(H3 Alias Declarations)

        $(P
        A symbol can be declared as an $(I alias) of another symbol.
        For example:
        )

--------------------
import string;

alias string.strlen mylen;
 ...
int len = mylen("hello"); // actually calls string.strlen()
--------------------

        $(P
        The following alias declarations are valid:
        )

--------------------
template Foo2(T) { alias T t; }
alias Foo2!(int) t1;
alias Foo2!(int).t t2;
alias t1.t t3;
alias t2 t4;

t1.t v1;  // v1 is type int
t2 v2;    // v2 is type int
t3 v3;    // v3 is type int
t4 v4;    // v4 is type int
--------------------

        $(P
        Aliased symbols are useful as a shorthand for a long qualified
        symbol name, or as a way to redirect references from one symbol
        to another:
        )

--------------------
version (Win32)
{
    alias win32.foo myfoo;
}
version (linux)
{
    alias linux.bar myfoo;
}
--------------------

        $(P
        Aliasing can be used to $(SINGLEQUOTE import) a symbol from an import into the
        current scope:
        )

--------------------
alias string.strlen strlen;
--------------------

        $(P
        Aliases can also $(SINGLEQUOTE import) a set of overloaded functions, that can
        be overloaded with functions in the current scope:
        )

--------------------
class A {
    int foo(int a) { return 1; }
}

class B : A {
    int foo( int a, uint b ) { return 2; }
}

class C : B {
    int foo( int a ) { return 3; }
    alias B.foo foo;
}

class D : C  {
}


void test()
{
    D b = new D();
    int i;

    i = b.foo(1, 2u);   // calls B.foo
    i = b.foo(1);       // calls C.foo
}
--------------------

        $(P
        $(B Note:) Type aliases can sometimes look indistinguishable from
        alias declarations:
        )

--------------------
alias foo.bar abc; // is it a type or a symbol?
--------------------

        $(P
        The distinction is made in the semantic analysis pass.
        )

        $(P Aliases cannot be used for expressions:)

-----------
struct S { static int i; }
S s;

alias s.i a; // illegal, s.i is an expression
alias S.i b; // ok
b = 4;       // sets S.i to 4
-----------

$(H3 $(LNAME2 extern, Extern Declarations))

        Variable declarations with the storage class $(D extern) are
        not allocated storage within the module.
        They must be defined in some other object file with a matching
        name which is then linked in.
        The primary usefulness of this is to connect with global
        variable declarations in C files.

        $(P An $(D extern) declaration can optionally be followed by an
        $(D extern) $(XLINK2 attribute.html#linkage, linkage attribute).
        If there is no linkage attribute it defaults to $(D extern(D)):)

---------------
extern(C) int foo;  // variable allocated and initialized in this module with C linkage
extern extern(C) int bar; // variable allocated outside this module with C linkage
                          // (e.g. in a statically linked C library or another module)
---------------


$(H3 $(LNAME2 typeof, $(D typeof)))

$(GRAMMAR
$(GNAME Typeof):
    $(D typeof $(LPAREN)) $(EXPRESSION) $(D $(RPAREN))
    $(D typeof $(LPAREN)) $(D return) $(D $(RPAREN)))

        $(P
        $(I Typeof) is a way to specify a type based on the type
        of an expression. For example:
        )

--------------------
void func(int i) {
 typeof(i) j;       // j is of type int
 typeof(3 + 6.0) x; // x is of type double
 typeof(1)* p;      // p is of type pointer to int
 int[typeof(p)] a;  // a is of type int[int*]

 writefln("%d", typeof('c').sizeof); // prints 1
 double c = cast(typeof(1.0))j; // cast j to double
}
--------------------

        $(P
        $(I Expression) is not evaluated, just the type of it is
        generated:
        )

--------------------
void func() {
 int i = 1;
 typeof(++i) j; // j is declared to be an int, i is not incremented
 writefln("%d", i);  // prints 1
}
--------------------

        $(P There are  three special cases: )
        $(OL
        $(LI $(D typeof(this)) will generate the type of what $(D this)
        would be in a non-static member function, even if not in a member
        function.
        )
        $(LI Analogously, $(D typeof(super)) will generate the type of what
        $(D super) would be in a non-static member function.
        )
        $(LI $(D typeof(return)) will, when inside a function scope,
        give the return type of that function.
        )

        )


--------------------
class A { }

class B : A {
 typeof(this) x;  // x is declared to be a B
 typeof(super) y; // y is declared to be an A
}

struct C {
   static typeof(this) z;  // z is declared to be a C

  typeof(super) q; // error, no super struct for C
}

typeof(this) r;   // error, no enclosing struct or class
--------------------

        $(P
        Where $(I Typeof) is most useful is in writing generic
        template code.
        )

$(H3 Void Initializations)

$(GRAMMAR
$(GNAME VoidInitializer):
    $(D void)
)

        $(P Normally, variables are initialized either with an explicit
        $(I Initializer) or are set to the default value for the
        type of the variable. If the $(I Initializer) is $(D void),
        however, the variable is not initialized. If its value is
        used before it is set, undefined program behavior will result.
	)

-------------------------
void foo() {
 int x = void;
 writefln(x);  // will print garbage
}
-------------------------

        $(P Therefore, one should only use $(D void) initializers as a
        last resort when optimizing critical code.
	)

$(H3 Global and Static Initializers)

	$(P The $(GLINK Initializer) for a global or static variable must be
	evaluatable at compile time.
	Whether some pointers can be initialized with the addresses of other
	functions or data is implementation defined.
	Runtime initialization can be done with static constructors.
	)
)

Macros:
        TITLE=Declarations
        WIKI=Declaration
        CATEGORY_SPEC=$0
        ASSIGNEXPRESSION=$(GLINK2 expression, AssignExpression)
        EXPRESSION=$(GLINK2 expression, Expression)
        VEXPRESSION=$(ASSIGNEXPRESSION)
        FOO=