declaration.dd

Ddoc

$(SPEC_S Declarations,

$(HEADERNAV_TOC)

$(GRAMMAR
$(GNAME Declaration):
    $(GLINK2 function, FuncDeclaration)
    $(GLINK VarDeclarations)
    $(GLINK AliasDeclaration)
    $(GLINK2 struct, AggregateDeclaration)
    $(GLINK2 enum, EnumDeclaration)
    $(GLINK2 module, ImportDeclaration)
    $(GLINK2 version, ConditionalDeclaration)
    $(GLINK2 version, StaticForeachDeclaration)
    $(GLINK2 version, StaticAssert)
)

$(GRAMMAR
$(GNAME VarDeclarations):
    $(GLINK StorageClasses)$(OPT) $(GLINK BasicType) $(GLINK Declarators) $(D ;)
    $(GLINK AutoDeclaration)

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

$(GNAME DeclaratorInitializer):
    $(GLINK VarDeclarator)
    $(GLINK VarDeclarator) $(GLINK2 template, TemplateParameters)$(OPT) $(D =) $(GLINK Initializer)
    $(GLINK AltDeclarator)
    $(GLINK AltDeclarator) $(D =) $(GLINK Initializer)

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

$(GNAME DeclaratorIdentifier):
    $(GLINK VarDeclaratorIdentifier)
    $(GLINK AltDeclaratorIdentifier)

$(GNAME VarDeclaratorIdentifier):
    $(GLINK_LEX Identifier)
    $(GLINK_LEX Identifier) $(GLINK2 template, TemplateParameters)$(OPT) $(D =) $(GLINK Initializer)

$(GNAME AltDeclaratorIdentifier):
    $(GLINK BasicType2) $(GLINK_LEX Identifier) $(GLINK AltDeclaratorSuffixes)$(OPT)
    $(GLINK BasicType2) $(GLINK_LEX Identifier) $(GLINK AltDeclaratorSuffixes)$(OPT) $(D =) $(GLINK Initializer)
    $(GLINK BasicType2)$(OPT) $(GLINK_LEX Identifier) $(GLINK AltDeclaratorSuffixes)
    $(GLINK BasicType2)$(OPT) $(GLINK_LEX Identifier) $(GLINK AltDeclaratorSuffixes) $(D =) $(GLINK Initializer)

$(GNAME Declarator):
    $(GLINK VarDeclarator)
    $(GLINK AltDeclarator)

$(GNAME VarDeclarator):
    $(GLINK BasicType2)$(OPT) $(GLINK_LEX Identifier)

$(GNAME AltDeclarator):
    $(GLINK BasicType2)$(OPT) $(GLINK_LEX Identifier) $(GLINK AltDeclaratorSuffixes)
    $(GLINK BasicType2)$(OPT) $(D $(LPAREN)) $(I AltDeclaratorX) $(D $(RPAREN))
    $(GLINK BasicType2)$(OPT) $(D $(LPAREN)) $(I AltDeclaratorX) $(D $(RPAREN)) $(GLINK AltFuncDeclaratorSuffix)
    $(GLINK BasicType2)$(OPT) $(D $(LPAREN)) $(I AltDeclaratorX) $(D $(RPAREN)) $(GLINK AltDeclaratorSuffixes)

$(GNAME AltDeclaratorX):
    $(GLINK BasicType2)$(OPT) $(GLINK_LEX Identifier)
    $(GLINK BasicType2)$(OPT) $(GLINK_LEX Identifier) $(GLINK AltFuncDeclaratorSuffix)
    $(GLINK AltDeclarator)

$(GNAME AltDeclaratorSuffixes):
    $(GLINK AltDeclaratorSuffix)
    $(GLINK AltDeclaratorSuffix) $(I AltDeclaratorSuffixes)

$(GNAME AltDeclaratorSuffix):
    $(D [ ])
    $(D [) $(GLINK2 expression, AssignExpression) $(D ])
    $(D [) $(GLINK Type) $(D ])

$(GNAME AltFuncDeclaratorSuffix):
    $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT)
)

$(GRAMMAR
$(GNAME Type):
    $(GLINK TypeCtors)$(OPT) $(GLINK BasicType) $(GLINK BasicType2)$(OPT)

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

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

$(GNAME BasicType):
    $(GLINK BasicTypeX)
    $(D .) $(GLINK IdentifierList)
    $(GLINK IdentifierList)
    $(GLINK Typeof)
    $(GLINK Typeof) $(D .) $(GLINK IdentifierList)
    $(GLINK TypeCtor) $(D $(LPAREN)) $(GLINK Type) $(D $(RPAREN))
    $(GLINK Vector)
    $(GLINK2 grammar, Traits)

$(GNAME Vector):
    $(D __vector)
    $(D __vector) $(D $(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 cent)
    $(D ucent)
    $(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):
    $(GLINK BasicType2X) $(GLINK BasicType2)$(OPT)

$(GNAME BasicType2X):
    $(D *)
    $(D [ ])
    $(D [) $(GLINK2 expression, AssignExpression) $(D ])
    $(D [) $(GLINK2 expression, AssignExpression) .. $(GLINK2 expression, AssignExpression) $(D ])
    $(D [) $(GLINK Type) $(D ])
    $(D delegate) $(GLINK2 function, Parameters) $(GLINK2 function, MemberFunctionAttributes)$(OPT)
    $(D function) $(GLINK2 function, Parameters) $(GLINK2 function, FunctionAttributes)$(OPT)

$(GNAME IdentifierList):
    $(GLINK_LEX Identifier)
    $(GLINK_LEX Identifier) $(D .) $(I IdentifierList)
    $(GLINK2 template, TemplateInstance)
    $(GLINK2 template, TemplateInstance) $(D .) $(I IdentifierList)
    $(GLINK_LEX Identifier) $(D [) $(GLINK2 expression, AssignExpression) $(D].) $(I IdentifierList)
)

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

$(GNAME StorageClass):
$(MULTICOLS 5,     $(GLINK2 attribute, LinkageAttribute)
    $(GLINK2 attribute, AlignAttribute)
    $(D deprecated)
    $(D enum)
    $(D static)
    $(RELATIVE_LINK2 extern, $(D extern))
    $(D abstract)
    $(D final)
    $(D override)
    $(D synchronized)
    $(D auto)
    $(D scope)
    $(D const)
    $(D immutable)
    $(D inout)
    $(D shared)
    $(D __gshared)
    $(GLINK2 attribute, Property)
    $(D nothrow)
    $(D pure)
    $(D ref))
)

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

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

$(GNAME ExpInitializer):
    $(GLINK2 expression, AssignExpression)

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

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

$(GNAME ArrayMemberInitialization):
    $(GLINK NonVoidInitializer)
    $(GLINK2 expression, AssignExpression) $(D :) $(GLINK NonVoidInitializer)

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

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

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

$(H2 $(LNAME2 declaration_syntax, 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
--------------------

$(H2 $(LEGACY_LNAME2 AutoDeclaration, auto-declaration, Implicit Type Inference))

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

$(GNAME AutoDeclarationX):
    $(GLINK AutoDeclarationY)
    $(I AutoDeclarationX) $(D ,) $(GLINK AutoDeclarationY)

$(GNAME AutoDeclarationY):
    $(GLINK_LEX Identifier) $(GLINK2 template, TemplateParameters)$(OPT) $(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 = "Apollo"; // 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 = ["resistance", "is", "useless"]; // type is string[], not string[3]
        ---


$(H2 $(LNAME2 alias, Alias Declarations))

$(GRAMMAR
$(GNAME AliasDeclaration):
    $(D alias) $(GLINK StorageClasses)$(OPT) $(GLINK BasicType) $(GLINK Declarators) $(D ;)
    $(D alias) $(GLINK StorageClasses)$(OPT) $(GLINK BasicType) $(GLINK2 function, FuncDeclarator) $(D ;)
    $(D alias) $(I AliasDeclarationX) $(D ;)

$(GNAME AliasDeclarationX):
    $(GLINK AliasDeclarationY)
    $(I AliasDeclarationX) $(D ,) $(GLINK AliasDeclarationY)

$(GNAME AliasDeclarationY):
    $(GLINK_LEX Identifier) $(GLINK2 template, TemplateParameters)$(OPT) $(D =) $(GLINK StorageClasses)$(OPT) $(GLINK Type)
    $(GLINK_LEX Identifier) $(GLINK2 template, TemplateParameters)$(OPT) $(D =) $(GLINK2 expression, FunctionLiteral)
)

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

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

        $(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 myint = int;

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

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

        ---
        import planets;

        alias myAlbedo = planets.albedo;
        ...
        int len = myAlbedo("Saturn"); // actually calls planets.albedo()
        ---

        $(P
        The following alias declarations are valid:
        )

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

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 myfoo = win32.foo;
}
version (linux)
{
    alias myfoo = linux.bar;
}
--------------------

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

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

        $(P
        Aliases can also `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 foo = B.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 abc = foo.bar; // 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;
    static int j;
}

alias a = S.i; // OK, `S.i` is a symbol
alias b = S.j; // OK. `S.j` is also a symbol
alias c = a + b; // illegal, `a + b` is an expression
a = 2;         // sets `S.i` to `2`
b = 4;         // sets `S.j` to `4`
-----------

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

$(P 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.)

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

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

        $(BEST_PRACTICE
        $(OL
        $(LI The primary usefulness of $(I Extern Declarations) is to
        connect with global variables declarations and functions in C or C++ files.)
        ))

$(H2 $(LNAME2 typeof, $(D typeof)))

$(GRAMMAR
$(GNAME Typeof):
    $(D typeof $(LPAREN)) $(GLINK2 expression, 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 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 If the expression is a $(DDSUBLINK spec/function, property-functions,
        Property Function), $(D typeof) gives its return type.
        )

        --------------------
        struct S
        {
            @property int foo() { return 1; }
        }
        typeof(S.foo) n;  // n is declared to be an int
        --------------------

        $(BEST_PRACTICE
        $(OL
        $(LI $(I Typeof) is most useful in writing generic
        template code.)
        )
        )

$(H2 $(LNAME2 void_init, Void Initializations))

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

        $(P Normally, variables are initialized either with an explicit
        $(GLINK 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.
        )

        $(UNDEFINED_BEHAVIOR If a void initialized variable's value is
        used before it is set, the behavior is undefined.

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

        $(BEST_PRACTICE
        $(OL
        $(LI Void initializers are useful when a static array is on the stack,
        but may only be partially used, such as as a temporary buffer.
        Void initializers will speed up the code, but of course one must be careful
        that array elements are actually set before read.)
        $(LI The same is true for structs.)
        $(LI Use of void initializers is rarely useful for individual local variables,
        as a modern optimizer will remove the dead store of its initialization if it is
        initialized later.)
        $(LI For hot code paths, it is worthwhile to check to see if the void initializer
        actually improves results before using it.)
        )
        )

$(H2 $(LNAME2 global_static_init, Global and Static Initializers))

        $(P The $(GLINK Initializer) for a global or static variable must be
        evaluatable at compile time.
        Runtime initialization is done with static constructors.
        )

        $(IMPLEMENTATION_DEFINED
        $(OL
        $(LI Whether some pointers can be initialized with the addresses of other
        functions or data.)
        ))

$(H2 $(LNAME2 typequal_vs_storageclass, Type Qualifiers vs. Storage Classes))

        $(P Type qualifer and storage classes are distinct.)

        $(P A $(I type qualifier) creates a derived type from an existing base
        type, and the resulting type may be used to create multiple instances
        of that type.)

        $(P For example, the $(D immutable) type qualifier can be used to
        create variables of immutable type, such as:)

--------
immutable(int)   x; // typeof(x) == immutable(int)
immutable(int)[] y; // typeof(y) == immutable(int)[]
                    // typeof(y[0]) == immutable(int)

// Type constructors create new types that can be aliased:
alias ImmutableInt = immutable(int);
ImmutableInt z;     // typeof(z) == immutable(int)
--------

        $(P A $(I storage class), on the other hand, does not create a new
        type, but describes only the kind of storage used by the variable or
        function being declared. For example, a member function can be declared
        with the $(D const) storage class to indicate that it does not modify
        its implicit $(D this) argument:)

--------
struct S
{
    int x;
    int method() const
    {
        //x++;    // Error: this method is const and cannot modify this.x
        return x; // OK: we can still read this.x
    }
}
--------

        $(P Although some keywords can be used both as a type qualifier and a
        storage class, there are some storage classes that cannot be used to
        construct new types, such as $(D ref):)

--------
// ref declares the parameter x to be passed by reference
void func(ref int x)
{
    x++; // so modifications to x will be visible in the caller
}

void main()
{
    auto x = 1;
    func(x);
    assert(x == 2);

    // However, ref is not a type qualifier, so the following is illegal:
    ref(int) y; // Error: ref is not a type qualifier.
}
--------

        $(P Functions can also be declared as `ref`, meaning their return value is
        passed by reference:)
--------
ref int func2()
{
    static int y = 0;
    return y;
}

void main()
{
    func2() = 2; // The return value of func2() can be modified.
    assert(func2() == 2);

    // However, the reference returned by func2() does not propagate to
    // variables, because the 'ref' only applies to the return value itself,
    // not to any subsequent variable created from it:
    auto x = func2();
    static assert(is(typeof(x) == int)); // N.B.: *not* ref(int);
                                     // there is no such type as ref(int).
    x++;
    assert(x == 3);
    assert(func2() == 2); // x is not a reference to what func2() returned; it
                          // does not inherit the ref storage class from func2().
}
--------

        $(P Some keywords, such as $(D const), can be used
        both as a type qualifier and a storage class.
        The distinction is determined by the syntax where it appears.)

        ---
        struct S
        {
            /* Is const here a type qualifier or a storage class?
             * Is the return value const(int), or is this a const function that returns
             * (mutable) int?
             */
            const int* func() // a const function
            {
                ++p;          // error, this.p is const
                return p;     // error, cannot convert const(int)* to int*
            }

            const(int)* func() // a function returning a pointer to a const int
            {
                ++p;          // ok, this.p is mutable
                return p;     // ok, int* can be implicitly converted to const(int)*
            }

            int* p;
        }
        ---

        $(BEST_PRACTICE To avoid confusion, the type qualifier
        syntax with parentheses should be used for return types,
        and function storage classes should be written on the right-hand side of the
        declaration instead of the left-hand side where it may be visually
        confused with the return type:

        ---
        struct S
        {
            // Now it is clear that the 'const' here applies to the return type:
            const(int) func1() { return 1; }

            // And it is clear that the 'const' here applies to the function:
            int func2() const { return 1; }
        }
        ---
        )

$(SPEC_SUBNAV_PREV_NEXT module, Modules, type, Types)
)


Macros:
        CHAPTER=5
        TITLE=Declarations