import std.meta : AliasSeq;

void main()
{
    alias Seq = AliasSeq!(int, "literal", main);

    foreach (int i, sym; Seq)
    {
        pragma(msg, i, ": ", sym.stringof);
    }
}

Output:

0: int
1: "literal"
2: main()

void fun()
{
    import std.meta : AliasSeq;

    alias values = AliasSeq!(7.4, "hi", [2,5]);

    foreach (sym; values)
    {
        pragma(msg, sym, " has type ", typeof(sym));
    }
}

Output:

7.4 has type double
hi has type string
[2, 5] has type int[]

Foreach Ref Parameters

ref can be used to modify the elements of the <em>ForeachAggregate</em>. This works for containers that expose lvalue elements, and lvalue sequences.

uint[2] a = [7, 8];

foreach (ref u; a)
{
    u++;
}
foreach (u; a)
{
    writeln(u);
}

which would print:

8
9

ref cannot be applied to an array index variable.

Foreach Restrictions

The aggregate itself must not be resized, reallocated, free'd, reassigned or destructed while foreach is iterating over the elements.

int[] a = [1, 2, 3];
auto fun = { a ~= 4; };

foreach (int v; a)
{
    // resizing is unspecified!
    fun();
    a ~= 4;
    a.length += 10;

    // reallocating is unspecified!
    a.reserve(10);

    // reassigning is unspecified!
    a = null;
    a = [5, 6];
}
a ~= 4;   // OK
a = null; // OK

auto aa = [1: 1, 2: 2];

foreach (v; aa)
{
    aa[3] = 3; // unspecified resize
    aa.rehash; // unspecified reallocation
    aa = [4: 4]; // unspecified reassign
}
aa[3] = 3; // OK
aa = null; // OK

Note: Resizing or reassigning a dynamic or associative array during foreach is still @safe.

Foreach Range Statement

A foreach range statement loops over the specified range.

 RangeForeach:
    Foreach ( ForeachType ; LwrExpression .. UprExpression )
 LwrExpression:
    expression, Expression
 UprExpression:
    expression, Expression
 ForeachRangeStatement:
    RangeForeach ScopeStatement

ForeachType declares a variable with either an explicit type, or a common type inferred from LwrExpression and UprExpression. The ScopeStatement is then executed n times, where n is the result of UprExpression - LwrExpression. If UprExpression is less than or equal to LwrExpression, the ScopeStatement is not executed.

If Foreach is foreach, then the variable is set to LwrExpression, then incremented at the end of each iteration. If Foreach is foreach_reverse, then the variable is set to UprExpression, then decremented before each iteration. LwrExpression and UprExpression are each evaluated exactly once, regardless of how many times the ScopeStatement is executed.

import std.stdio;

int foo()
{
    write("foo");
    return 10;
}

void main()
{
    foreach (i; 0 .. foo())
    {
        write(i);
    }
}

prints:

foo0123456789

Switch Statement

A switch statement goes to one of a collection of case statements depending on the value of the switch expression.

 SwitchStatement:
    switch ( IfCondition ) ScopeStatement
 CaseStatement:
    case expression, ArgumentList : ScopeStatementListopt
 DefaultStatement:
    default : ScopeStatementListopt
 ScopeStatementList:
    StatementListNoCaseNoDefault
 StatementListNoCaseNoDefault:
    StatementNoCaseNoDefault
StatementNoCaseNoDefault StatementListNoCaseNoDefault
 StatementNoCaseNoDefault:
    EmptyStatement
NonEmptyStatementNoCaseNoDefault
ScopeBlockStatement

The <em>Expression</em> from the IfCondition is evaluated. If the type of the <em>Expression</em> is an enum, it is (recursively) converted to its enum, EnumBaseType. Then, if the type is an integral, the <em>Expression</em> undergoes Integer Promotions. Then, the type of the <em>Expression</em> must be either an integral or a static or dynamic array of char, wchar, or dchar.

If an Identifier = prefix is provided, a variable is declared with that name, initialized to the value and type of the <em>Expression</em>. Its scope extends from when it is initialized to the end of the <em>ScopeStatement</em>.

If TypeCtors and/or a specific type is provided for <em>Identifier</em>, those are used for the variable declaration which is initialized by an implicit conversion from the value of the <em>Expression</em>.

The resulting value is compared against each of the case expressions. If there is a match, the corresponding case statement is transferred to.

The case expressions in ArgumentList are a comma separated list of expressions. Each expression must evaluate to a compile-time value or array, or a runtime initialized const or immutable variable of integral type. Each expression must be implicitly convertible to the type of the switch <em>Expression</em>.

Compile-time case values must all be distinct. Const or immutable runtime variables must all have different names. If two case expressions share a value, the first case statement with that value gets control.

The ScopeStatementList introduces a new scope.

A matching break statement will exit the switch BlockStatement.

A switch statement must have exactly one <em>DefaultStatement</em>. If none of the case expressions match, control is transferred to the default statement.

Rationale: This makes it clear that all possible cases are intentionally handled. See also: `final switch`.

foreach (i; 2 .. 10)
{
    bool prime;

    switch (i)
    {
        case 2, 3, 5, 7:
            prime = true;
            break;
        default:
            prime = false;
    }
    writeln(i, ": ", prime);
}

Case statements and default statements associated with the switch can be nested within block statements; they do not have to be in the outermost block. For example, this is allowed:

switch (i)
{
    case 1:
    {
        case 2:
    }
    i++;
    break;
    default:
}

Implementation Note: The compiler's code generator may assume that the case statements are sorted by frequency of use, with the most frequent appearing first and the least frequent last. Although this is irrelevant as far as program correctness is concerned, it is of performance interest.

Case Range Statement

 CaseRangeStatement:
    case FirstExp : .. case LastExp : ScopeStatementListopt
 FirstExp:
    AssignExpression
 LastExp:
    AssignExpression

A CaseRangeStatement is a shorthand for listing a series of case statements from FirstExp to LastExp, inclusive.

case 1: .. case 3:

The above is equivalent to:

case 1, 2, 3:

No Implicit Fall-Through

A ScopeStatementList must either be empty, or be ended with a ContinueStatement, BreakStatement, ReturnStatement, GotoStatement, expression, ThrowExpression or assert(0) expression unless this is the last case.

switch (i)
{
    case 1:
        message ~= "one";
        // ERROR: implicit fall-through
    case 2:
        // valid: the body is empty
    default:
        message ~= "unknown";
}

goto case; can be used for explicit fall-through:

string message;

foreach (i; 1..5)
{
    switch (i)
    {
        default:    // valid: ends with 'throw'
            throw new Exception("unknown number");

        case 3:     // valid: ends with 'break' (break out of the 'switch' only)
            message ~= "three";
            break;

        case 4:     // valid: ends with 'continue' (continue the enclosing loop)
            message ~= "four";
            continue; // don't append a comma

        case 1:     // valid: ends with 'goto' (explicit fall-through to next case.)
            message ~= ">";
            goto case;

        case 2:     // valid: this is the last case in the switch statement.
            message ~= "one or two";
    }
    message ~= ", ";
}
writeln(message);

`goto` also supports jumping to a specific case or the default case statement.

String Switch

Strings can be used in switch expressions. For example:

string name;
...
switch (name)
{
    case "fred":
    case "sally":
        ...
}

For applications like command line switch processing, this can lead to much more straightforward code, being clearer and less error prone. char, wchar and dchar strings are allowed.

Final Switch Statement

 FinalSwitchStatement:
    final switch ( IfCondition ) ScopeStatement

A final switch statement is just like a switch statement, except that:

• No DefaultStatement is allowed.
• No CaseRangeStatements are allowed.
• If the switch <em>Expression</em> is of enum type, all the enum members must appear in the CaseStatements.
• The case expressions cannot evaluate to a run time initialized value.

Continue Statement

 ContinueStatement:
    continue Identifieropt ;

continue aborts the current iteration of its innermost enclosing loop statement, and starts the next iteration. If the enclosing loop is a for statement, its Increment clause is executed.

string[] words = ["OK", "just", "longer", "words", "now"];

foreach (w; words)
{
    if (w.length < 4)
        continue; // skip writeln

    writeln(w);
}

Output:

just
longer
words

If continue is followed by Identifier, the Identifier must be the label of an enclosing loop statement, and the next iteration of that loop is executed. It is an error if there is no such statement.

outer:
foreach (item; list)
{
    // try 3 times
    foreach (i; 0 .. 3)
    {
        if (item.buy())
            continue outer; // skip to next item

        log("attempt failed");
    }
}

Any intervening `finally` clauses are executed, and any intervening synchronization objects are released.

Note: If a finally clause executes a throw out of the finally clause, the continue target is never reached.

Break Statement

 BreakStatement:
    break Identifieropt ;

break exits the innermost enclosing loop or `switch` statement, resuming execution at the statement following it.

const n = 55;

// find the smallest factor of n
foreach (i; 2 .. n)
{
    writeln("Trying: ", i);
    if (n % i == 0)
    {
        writeln("smallest factor is ", i);
        break; // stop looking
    }
}
writeln("finished");

Output:

Trying: 2
Trying: 3
Trying: 4
Trying: 5
smallest factor is 5
finished

If break is followed by Identifier, the Identifier must be the label of an enclosing loop or switch statement, and that statement is exited. It is an error if there is no such statement.

// display messages cyclically until the shop is closed
outer:
while (true)
{
    foreach (msg; messages)
    {
        if (shop.isClosed())
            break outer; // end the while loop

        display(msg);
    }
}
display("opens at 9am");

Any intervening `finally` clauses are executed, and any intervening synchronization objects are released.

Note: If a finally clause executes a throw out of the finally clause, the break target is never reached.

Return Statement

 ReturnStatement:
    return expression, Expressionopt ;

return exits the current function and supplies its return value.

<em>Expression</em> is required if the function specifies a return type that is not void. The <em>Expression</em> is implicitly converted to the function return type.

An <em>Expression</em> of type void is allowed if the function specifies a void return type. The <em>Expression</em> will be evaluated, but nothing will be returned. This is useful in generic programming.

Before the function actually returns, any objects with scope storage duration are destroyed, any enclosing finally clauses are executed, any scope(exit) statements are executed, any scope(success) statements are executed, and any enclosing synchronization objects are released.

The function will not return if any enclosing finally clause does a return, goto or throw that exits the finally clause.

If there is an out postcondition, that postcondition is executed after the <em>Expression</em> is evaluated and before the function actually returns.

int foo(int x)
{
    return x + 3;
}

Goto Statement

 GotoStatement:
    goto Identifier ;
    goto default ;
    goto case ;
    goto case expression, Expression ;

goto transfers to the statement labeled with Identifier.

    if (foo)
        goto L1;
    x = 3;
L1:
    x++;

The second form, goto default;, transfers to the innermost DefaultStatement of an enclosing SwitchStatement.

The third form, goto case;, transfers to the next CaseStatement of the innermost enclosing SwitchStatement.

The fourth form, goto case <em>Expression</em>;, transfers to the CaseStatement of the innermost enclosing SwitchStatement

with a matching <em>Expression</em>.

switch (x)
{
    case 3:
        goto case;
    case 4:
        goto default;
    case 5:
        goto case 4;
    default:
        x = 4;
        break;
}

Any intervening finally clauses are executed, along with releasing any intervening synchronization mutexes.

It is illegal for a GotoStatement to be used to skip initializations.

With Statement

The with statement is a way to simplify repeated references to the same object.

 WithStatement:
    with ( expression, Expression ) ScopeStatement
    with ( template, Symbol ) ScopeStatement
    with ( template, TemplateInstance ) ScopeStatement

where <em>Expression</em> evaluates to one of:

• a class reference
• a struct instance
• an enum instance
• a pointer to one of the above

Within the with body the referenced object is searched first for identifier symbols.

enum E { A, B }

void test(E e)
{
    with (e)       // affects the switch statement
    switch (e)
    {
        case A:    // no need for E.A
        case B:
        default:
            break;
    }
}

Below, if ident is a member of the type of expression, the WithStatement:

with (expression)
{
    ...
    ident;
}

is semantically equivalent to:

(auto ref tmp)
{
    ...
    tmp.ident;
}(expression);

Note that <em>Expression</em> only gets evaluated once and is not copied. The with statement does not change what this or super refer to.

For Symbol which is a scope or TemplateInstance, the corresponding scope is searched when looking up symbols. For example:

struct Foo
{
    alias Y = int;
}
...
Y y;        // error, Y undefined
with (Foo)
{
    Y y;    // same as Foo.Y y;
}

Use of with object symbols that shadow local symbols with the same identifier are not allowed. This is to reduce the risk of inadvertent breakage of with statements when new members are added to the object declaration.

struct S
{
    float x;
}

void main()
{
    int x;
    S s;
    with (s)
    {
        x++;  // error, shadows the int x declaration
    }
}

In nested WithStatements, the inner-most scope takes precedence. If a symbol cannot be resolved at the inner-most scope, resolution is forwarded incrementally up the scope hierarchy.

1 import std.stdio;
2 
3 struct Foo
4 {
5     void f() { writeln("Foo.f"); }
6 }
7 
8 struct Bar
9 {
10     void f() { writeln("Bar.f"); }
11 }
12 
13 struct Baz
14 {
15     // f() is not implemented
16 }
17 
18 void f()
19 {
20     writeln("f");
21 }
22 
23 void main()
24 {
25     Foo foo;
26     Bar bar;
27     Baz baz;
28 
29     f();               // prints "f"
30 
31     with(foo)
32     {
33         f();           // prints "Foo.f"
34 
35         with(bar)
36         {
37             f();       // prints "Bar.f"
38 
39             with(baz)
40             {
41                 f();   // prints "Bar.f".  `Baz` does not implement `f()` so
42                        // resolution is forwarded to `with(bar)`'s scope
43             }
44         }
45         with(baz)
46         {
47             f();       // prints "Foo.f".  `Baz` does not implement `f()` so
48                        // resolution is forwarded to `with(foo)`'s scope
49         }
50     }
51     with(baz)
52     {
53         f();           // prints "f".  `Baz` does not implement `f()` so
54                        // resolution is forwarded to `main`'s scope. `f()` is
55                        // not implemented in `main`'s scope, so resolution is
56                        // subsequently forward to module scope.
57     }
58 }

Synchronized Statement

The synchronized statement wraps a statement with mutex locking and unlocking to synchronize access among multiple threads.

 SynchronizedStatement:
    synchronized ScopeStatement
    synchronized ( expression, Expression ) ScopeStatement

A synchronized statement without <em>Expression</em> allows only one thread at a time to execute ScopeStatement by locking a mutex. A global mutex is created, one per synchronized statement. Different synchronized statements will have different global mutexes.

If there is an <em>Expression</em>, it must evaluate to either an Object or an instance of an Interfaces, in which case it is cast to the Object instance that implemented that interface. The mutex used is specific to that Object instance, and is shared by all synchronized statements referring to that instance. If the object's mutex is already locked when reaching the synchronized statement, it will block every thread until that mutex is unlocked by other code.

void work();

void f(Object o)
{
    synchronized (o) work();
}

void g(Object o)
{
    synchronized (o) work();
}

The synchronization gets released even if ScopeStatement terminates with an exception, goto, or return.

This implements a standard critical section.

Synchronized statements support recursive locking; that is, a function wrapped in synchronized is allowed to recursively call itself and the behavior will be as expected: The mutex will be locked and unlocked as many times as there is recursion.

See also synchronized classes.

Try Statement

Exception handling is done with the try-catch-finally statement.

 TryStatement:
    try ScopeStatement Catches
    try ScopeStatement Catches FinallyStatement
    try ScopeStatement FinallyStatement
 Catches:
    Catch
Catch Catches
 Catch:
    catch ( CatchParameter ) NoScopeNonEmptyStatement
 CatchParameter:
    type, BasicType Identifieropt
 FinallyStatement:
    finally NoScopeNonEmptyStatement

CatchParameter declares a variable v of type T, where T is Throwable or derived from Throwable. v is initialized by the throw expression if T is of the same type or a base class of the throw expression. The catch clause will be executed if the exception object is of type T or derived from T.

If just type T is given and no variable v, then the catch clause is still executed.

It is an error if any CatchParameter type T1 hides a subsequent Catch with type T2, i.e. it is an error if T1 is the same type as or a base class of T2.

The FinallyStatement is always executed, whether the try ScopeStatement exits with a goto, break, continue, return, exception, or fall-through.

If an exception is raised in the FinallyStatement and is not caught before the original exception is caught, it is chained to the previous exception via the next member of Throwable. Note that, in contrast to most other programming languages, the new exception does not replace the original exception. Instead, later exceptions are regarded as 'collateral damage' caused by the first exception. The original exception must be caught, and this results in the capture of the entire chain.

Thrown objects derived from the Error class are treated differently. They bypass the normal chaining mechanism, such that the chain can only be caught by catching the first Error. In addition to the list of subsequent exceptions, Error also contains a pointer that points to the original exception (the head of the chain) if a bypass occurred, so that the entire exception history is retained.

import std.stdio;

int main()
{
    try
    {
        try
        {
            throw new Exception("first");
        }
        finally
        {
            writeln("finally");
            throw new Exception("second");
        }
    }
    catch (Exception e)
    {
        writefln("catch %s", e.msg);
    }
    writeln("done");
    return 0;
}

prints:

finally
catch first
done

A FinallyStatement may not exit with a goto, break, continue, or return; nor may it be entered with a goto.

A FinallyStatement may not contain any Catches. This restriction may be relaxed in future versions.

Scope Guard Statement

 ScopeGuardStatement:
    scope ( exit ) NonEmptyOrScopeBlockStatement
    scope ( success ) NonEmptyOrScopeBlockStatement
    scope ( failure ) NonEmptyOrScopeBlockStatement

The ScopeGuardStatement executes <em>NonEmptyOrScopeBlockStatement</em> at the close of the current scope, rather than at the point where the ScopeGuardStatement appears. scope(exit) executes <em>NonEmptyOrScopeBlockStatement</em> when the scope exits normally or when it exits due to exception unwinding. scope(failure) executes <em>NonEmptyOrScopeBlockStatement</em> when the scope exits due to exception unwinding. scope(success) executes <em>NonEmptyOrScopeBlockStatement</em> when the scope exits normally.

If there are multiple ScopeGuardStatements in a scope, they will be executed in the reverse lexical order in which they appear. If any scope instances are to be destroyed upon the close of the scope, their destructions will be interleaved with the ScopeGuardStatements in the reverse lexical order in which they appear.

write("1");
{
    write("2");
    scope(exit) write("3");
    scope(exit) write("4");
    write("5");
}
writeln();

writes:

12543

{
    scope(exit) write("1");
    scope(success) write("2");
    scope(exit) write("3");
    scope(success) write("4");
}
writeln();

writes:

4321

struct Foo
{
    this(string s) { write(s); }
    ~this() { write("1"); }
}

try
{
    scope(exit) write("2");
    scope(success) write("3");
    Foo f = Foo("0");
    scope(failure) write("4");
    throw new Exception("msg");
    scope(exit) write("5");
    scope(success) write("6");
    scope(failure) write("7");
}
catch (Exception e)
{
}
writeln();

writes:

0412

A scope(exit) or scope(success) statement may not exit with a throw, goto, break, continue, or return; nor may it be entered with a goto. A scope(failure) statement may not exit with a return.

import std.stdio;

int foo()
{
    scope(exit) writeln("Inside foo()");
    return bar();
}

int bar()
{
    writeln("Inside bar()");
    return 0;
}

int main()
{
    foo();
    return 0;
}

writes:

Inside bar()
Inside foo()

Catching C++ Class Objects

On many platforms, catching C++ class objects is supported. Catching C++ objects and D objects cannot both be done in the same TryStatement. Upon exit from the Catch, any destructors for the C++ object will be run and the storage used for it reclaimed. C++ objects cannot be caught in @safe code.

Asm Statement

Inline assembler is supported with the asm statement:

 AsmStatement:
    asm function, FunctionAttributesopt { AsmInstructionListopt }
 AsmInstructionList:
    iasm, AsmInstruction ;
    iasm, AsmInstruction ; AsmInstructionList

An asm statement enables the direct use of assembly language instructions. This makes it easy to obtain direct access to special CPU features without resorting to an external assembler. The D compiler will take care of the function calling conventions, stack setup, etc.

The format of the instructions is, of course, highly dependent on the native instruction set of the target CPU, and so is Inline Assembler. But, the format will follow the following conventions:

• It must use the same tokens as the D language uses.
• The comment form must match the D language comments.
• Asm instructions are terminated by a ;, not by an end of line.

These rules exist to ensure that D source code can be tokenized independently of syntactic or semantic analysis.

For example, for the Intel Pentium:

int x = 3;
asm
{
    mov EAX,x; // load x and put it in register EAX
}

Inline assembler can be used to access hardware directly:

int gethardware()
{
    asm
    {
        mov EAX, dword ptr 0x1234;
    }
}

For some D implementations, such as a translator from D to C, an inline assembler makes no sense, and need not be implemented. The version statement can be used to account for this:

version (D_InlineAsm_X86)
{
    asm
    {
        ...
    }
}
else
{
    /* ... some workaround ... */
}

Semantically consecutive AsmStatements shall not have any other instructions (such as register save or restores) inserted between them by the compiler.

Pragma Statement

See pragma, PragmaStatement.

Mixin Statement

 MixinStatement:
    mixin ( expression, ArgumentList ) ;

Each expression, AssignExpression in the ArgumentList is evaluated at compile time, and the result must be representable as a string. The resulting strings are concatenated to form a string. The text contents of the string must be compilable as a valid StatementList, and is compiled as such.

import std.stdio;

void main()
{
    int i = 0;
    mixin("
        int x = 3;
        for (; i < 3; i++)
            writeln(x + i, i);
        ");    // ok

    enum s = "int y;";
    mixin(s);  // ok
    y = 4;     // ok, mixin declared y

    string t = "y = 3;";
    //mixin(t);  // error, t is not evaluatable at compile time
    //mixin("y =") 4; // error, string must be complete statement

    mixin("y =" ~ "4;");  // ok
    mixin("y =", 2+2, ";");  // ok
}

expression, Expressions, arrays, Arrays