Improve this page Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone. Page wiki View or edit the community-maintained wiki page associated with this page.

Attributes

AttributeSpecifier:
    Attribute :
    Attribute DeclarationBlock

Attribute:
    LinkageAttribute
    AlignAttribute
    DeprecatedAttribute
    ProtectionAttribute
    Pragma
    static
    extern
    abstract
    final
    override
    synchronized
    auto
    scope
    const
    immutable
    inout
    shared
    __gshared
    Property
    nothrow
    pure
    ref

Property:
    @ PropertyIdentifier
    UserDefinedAttribute

PropertyIdentifier:
    property
    safe
    trusted
    system
    disable
    nogc

DeclarationBlock:
    DeclDef
    { DeclDefsopt }

Attributes are a way to modify one or more declarations. The general forms are: 

attribute declaration; // affects the declaration

attribute:     // affects all declarations until the end of
               // the current scope
  declaration;
  declaration;
  ...

attribute {    // affects all declarations in the block
  declaration;
  declaration;
  ...
}

Linkage Attribute

LinkageAttribute:
    extern ( LinkageType )
    extern ( C++, IdentifierList )

LinkageType:
    C
    C++
    D
    Windows
    Pascal
    System

D provides an easy way to call C functions and operating system API functions, as compatibility with both is essential. The LinkageType is case sensitive, and is meant to be extensible by the implementation (they are not keywords). C and D must be supplied, the others are what makes sense for the implementation. C++ offers limited compatibility with C++. System is the same as Windows on Windows platforms, and C on other platforms. Implementation Note: for Win32 platforms, Windows and Pascal should exist.

C function calling conventions are specified by: 

extern (C):
  int foo(); // call foo() with C conventions

D conventions are:

extern (D):

Windows API conventions are:

extern (Windows):
  void *VirtualAlloc(
    void *lpAddress,
    uint dwSize,
    uint flAllocationType,
    uint flProtect
    );

The Windows convention is distinct from the C convention only on Win32 platforms, where it is equivalent to the stdcall convention.

Note that a lone extern declaration is used as a storage class.

C++ Namespaces

The linkage form extern ( C++, IdentifierList ) creates C++ declarations that reside in C++ namespaces. The IdentifierList specifies the namespaces. 

extern (C++, N) { void foo(); }

refers to the C++ declaration:

namespace N { void foo(); }

and can be referred to with or without qualification:

foo();
N.foo();

Namespaces create a new named scope that is imported into its enclosing scope.

extern (C++, N) { void foo(); void bar(); }
extern (C++, M) { void foo(); }

bar();   // ok
foo();   // error - N.foo() or M.foo() ?
M.foo(); // ok

Multiple identifiers in the IdentifierList create nested namespaces:

extern (C++, N.M) { extern (C++) { extern (C++, R) { void foo(); } } }
N.M.R.foo();

refers to the C++ declaration:

namespace N { namespace M { namespace R { void foo(); } } }

align Attribute

AlignAttribute:
    align
    align ( IntegerLiteral )

Specifies the alignment of:

  1. variables
  2. struct fields
  3. union fields
  4. class fields
  5. struct, union, and class types

align by itself sets it to the default, which matches the default member alignment of the companion C compiler.

struct S {
  align:
     byte a;   // placed at offset 0
     int b;    // placed at offset 4
     long c;   // placed at offset 8
}

auto sz = S.sizeof;  // 16

IntegerLiteral specifies the alignment which matches the behavior of the companion C compiler when non-default alignments are used. It must be a positive power of 2.

A value of 1 means that no alignment is done; fields are packed together. 

struct S {
  align (1):
     byte a;   // placed at offset 0
     int b;    // placed at offset 1
     long c;   // placed at offset 5
}

auto sz = S.sizeof;  // 16

The alignment for the fields of an aggregate does not affect the alignment of the aggregate itself - that is affected by the alignment setting outside of the aggregate.

align (2) struct S {
  align (1):
     byte a;   // placed at offset 0
     int b;    // placed at offset 1
     long c;   // placed at offset 5
}

auto sz = S.sizeof;  // 14

Setting the alignment of a field aligns it to that power of 2, regardless of the size of the field.

struct S {
  align (4):
     byte a;   // placed at offset 0
     byte b;   // placed at offset 4
     short c;  // placed at offset 8
}

auto sz = S.sizeof;  // 12

Do not align references or pointers that were allocated using NewExpression on boundaries that are not a multiple of size_t. The garbage collector assumes that pointers and references to gc allocated objects will be on size_t byte boundaries. If they are not, undefined behavior will result.

The AlignAttribute is reset to the default when entering a function scope or a non-anonymous struct, union, class, and restored when exiting that scope. It is not inherited from a base class.

deprecated Attribute

DeprecatedAttribute:
    deprecated
    deprecated ( StringLiteral )

It is often necessary to deprecate a feature in a library, yet retain it for backwards compatibility. Such declarations can be marked as deprecated, which means that the compiler can be instructed to produce an error if any code refers to deprecated declarations: 

deprecated
{
  void oldFoo();
}

oldFoo();   // Deprecated: function test.oldFoo is deprecated

Optional StringLiteral can show additional information in the deprecation message. 

deprecated("Don't use bar") void oldBar();
oldBar();   // Deprecated: function test.oldBar is deprecated - Don't use bar

Implementation Note: The compiler should have a switch specifying if deprecated should be ignored, cause a warning, or cause an error during compilation.

Protection Attribute

ProtectionAttribute:
    private
    package
    protected
    public
    export

Protection is an attribute that is one of private, package, protected, public or export.

Private means that only members of the enclosing class can access the member, or members and functions in the same module as the enclosing class. Private members cannot be overridden. Private module members are equivalent to static declarations in C programs.

Package extends private so that package members can be accessed from code in other modules that are in the same package. This applies to the innermost package only, if a module is in nested packages.

Protected means that only members of the enclosing class or any classes derived from that class, or members and functions in the same module as the enclosing class, can access the member. If accessing a protected instance member through a derived class member function, that member can only be accessed for the object instance which can be implicitly cast to the same type as ‘this’. Protected module members are illegal.

Public means that any code within the executable can access the member.

Export means that any code outside the executable can access the member. Export is analogous to exporting definitions from a DLL.

Protection does not participate in name lookup. In particular, if two symbols with the same name are in scope, and that name is used unqualified then the lookup will be ambiguous, even if one of the symbols is inaccessible due to protection. For example: 

module A;
private class Foo {}

module B;
public class Foo {}

import A;
import B;

Foo f1; // error, could be either A.Foo or B.Foo
B.Foo f2; // ok

const Attribute

The const attribute changes the type of the declared symbol from T to const(T), where T is the type specified (or inferred) for the introduced symbol in the absence of const. 

const int foo = 7;
static assert(is(typeof(foo) == const(int)));

const {
  double bar = foo + 6;
}
static assert(is(typeof(bar) == const(double)));

class C {
  const void foo();
  const {
    void bar();
  }
  void baz() const;
}
pragma(msg, typeof(C.foo)); // const void()
pragma(msg, typeof(C.bar)); // const void()
pragma(msg, typeof(C.baz)); // const void()
static assert(is(typeof(C.foo) == typeof(C.bar)) &&
              is(typeof(C.bar) == typeof(C.baz)));

immutable Attribute

The immutable attribute modifies the type from T to immutable(T), the same way as const does.

inout Attribute

The inout attribute modifies the type from T to inout(T), the same way as const does.

shared Attribute

The shared attribute modifies the type from T to shared(T), the same way as const does.

__gshared Attribute

By default, non-immutable global declarations reside in thread local storage. When a global variable is marked with the __gshared attribute, its value is shared across all threads.

int foo;            // Each thread has its own exclusive copy of foo.
__gshared int bar;  // bar is shared by all threads.

__gshared may also be applied to member variables and local variables. In these cases, __gshared is equivalent to static, except that the variable is shared by all threads rather than being thread local.

class Foo {
  __gshared int bar;
}

int foo() {
  __gshared int bar = 0;
  return bar++; // Not thread safe.
}

Unlike the shared attribute, __gshared provides no safe-guards against data races or other multi-threaded synchronization issues. It is the responsibility of the programmer to ensure that access to variables marked __gshared is synchronized correctly.

__gshared is disallowed in safe mode.

@disable Attribute

A reference to a declaration marked with the @disable attribute causes a compile time error. This can be used to explicitly disallow certain operations or overloads at compile time rather than relying on generating a runtime error. 

@disable void foo() { }

void main() {
  foo();   // error, foo is disabled
}

Disabling struct no-arg constructor disallows default construction of the struct.

Disabling struct postblit makes the struct not copyable.

@nogc Attribute

@nogc applies to functions, and means that that function does not allocate memory on the GC heap, either directly such as with NewExpression or indirectly through functions it may call, or through language features such as array concatenation and dynamic closures. 

@nogc void foo(char[] a) {
  auto p = new int;  // error, operator new allocates
  a ~= 'c';          // error, appending to arrays allocates
  bar();             // error, bar() may allocate
}

void bar() { }

@nogc affects the type of the function. An @nogc function is covariant with a non-@nogc function. 

void function() fp;
void function() @nogc gp;  // pointer to @nogc function

void foo();
@nogc void bar();

void test() {
  fp = &foo; // ok
  fp = &bar; // ok, it's covariant
  gp = &foo; // error, not contravariant
  gp = &bar; // ok
}

@property Attribute

See Property Functions.

nothrow Attribute

See Nothrow Functions.

pure Attribute

See Pure Functions.

ref Attribute

See Ref Functions.

override Attribute

The override attribute applies to virtual functions. It means that the function must override a function with the same name and parameters in a base class. The override attribute is useful for catching errors when a base class's member function gets its parameters changed, and all derived classes need to have their overriding functions updated. 

class Foo {
  int bar();
  int abc(int x);
}

class Foo2 : Foo {
  override {
    int bar(char c); // error, no bar(char) in Foo
    int abc(int x);  // ok
  }
}

static Attribute

The static attribute applies to functions and data. It means that the declaration does not apply to a particular instance of an object, but to the type of the object. In other words, it means there is no this reference. static is ignored when applied to other declarations. 

class Foo {
  static int bar() { return 6; }
  int foobar() { return 7; }
}

...

Foo f = new Foo;
Foo.bar();      // produces 6
Foo.foobar();   // error, no instance of Foo
f.bar();        // produces 6;
f.foobar();     // produces 7;

Static functions are never virtual.

Static data has one instance per thread, not one per object.

Static does not have the additional C meaning of being local to a file. Use the private attribute in D to achieve that. For example: 

module foo;
int x = 3;         // x is global
private int y = 4; // y is local to module foo

auto Attribute

The auto attribute is used when there are no other attributes and type inference is desired. 

auto i = 6.8;   // declare i as a double

scope Attribute

The scope attribute is used for local variables and for class declarations. For class declarations, the scope attribute creates a scope class. For local declarations, scope implements the RAII (Resource Acquisition Is Initialization) protocol. This means that the destructor for an object is automatically called when the reference to it goes out of scope. The destructor is called even if the scope is exited via a thrown exception, thus scope is used to guarantee cleanup.

If there is more than one scope variable going out of scope at the same point, then the destructors are called in the reverse order that the variables were constructed.

scope cannot be applied to globals, statics, data members, ref or out parameters. Arrays of scopes are not allowed, and scope function return values are not allowed. Assignment to a scope, other than initialization, is not allowed. Rationale: These restrictions may get relaxed in the future if a compelling reason to appears.

abstract Attribute

If a class is abstract, it cannot be instantiated directly. It can only be instantiated as a base class of another, non-abstract, class.

Classes become abstract if they are defined within an abstract attribute, or if any of the virtual member functions within it are declared as abstract.

Non-virtual functions cannot be declared as abstract.

Functions declared as abstract can still have function bodies. This is so that even though they must be overridden, they can still provide ‘base class functionality.’

User Defined Attributes

User Defined Attributes (UDA) are compile time expressions that can be attached to a declaration. These attributes can then be queried, extracted, and manipulated at compile time. There is no runtime component to them.

Grammatically, a UDA is a StorageClass: 

UserDefinedAttribute:
    @ ( ArgumentList )
    @ Identifier
    @ Identifier ( ArgumentListopt )

And looks like: 

@(3) int a;
@("string", 7) int b;

enum Foo;
@Foo int c;

struct Bar
{
    int x;
}

@Bar(3) int d;

If there are multiple UDAs in scope for a declaration, they are concatenated: 

@(1) {
    @(2) int a;         // has UDA's (1, 2)
    @("string") int b;  // has UDA's (1, "string")
}

UDA's can be extracted into an expression tuple using __traits: 

@('c') string s;
pragma(msg, __traits(getAttributes, s)); // prints tuple('c')

If there are no user defined attributes for the symbol, an empty tuple is returned. The expression tuple can be turned into a manipulatable tuple: 

template Tuple (T...)
{
    alias Tuple = T;
}

enum EEE = 7;
@("hello") struct SSS { }
@(3) { @(4) @EEE @SSS int foo; }

alias TP = Tuple!(__traits(getAttributes, foo));

pragma(msg, TP); // prints tuple(3, 4, 7, (SSS))
pragma(msg, TP[2]); // prints 7

Of course the tuple types can be used to declare things: 

TP[3] a; // a is declared as an SSS

The attribute of the type name is not the same as the attribute of the variable: 

pragma(msg, __traits(getAttributes, typeof(a))); // prints tuple("hello")

Of course, the real value of UDA's is to be able to create user defined types with specific values. Having attribute values of basic types does not scale. The attribute tuples can be manipulated like any other tuple, and can be passed as the argument list to a template.

Whether the attributes are values or types is up to the user, and whether later attributes accumulate or override earlier ones is also up to how the user interprets them.

Forums | Comments | Search | Downloads | Home