D Programming Language Specification

i
 This is the specification for the D Programming Language. For more information see dlang.org.

Contents

Contents 1

1 Introduction 3

2 Lexical 5

3 Grammar 27

4 Modules 71

5 Declarations 83

6 Types 98

7 Properties 105

8 Attributes 113

9 Pragmas 127

10 Expressions 131

11 Statements 167

12 Arrays 199

13 Associative Arrays 217

14 Structs and Unions 227

15 Classes 239

1
2 CONTENTS

16 Interfaces 263

17 Enums 271

18 Type Qualifiers 277

19 Functions 285

20 Operator Overloading 329

21 Templates 347

22 Template Mixins 375

23 Contract Programming 383

24 Conditional Compilation 389

25 Traits 401

26 Error Handling 421

27 Unit Tests 425

28 Garbage Collection 429

29 Floating Point 437

30 D x86 Inline Assembler 441

31 Embedded Documentation 455

32 Interfacing to C 475

33 Interfacing to C++ 483

34 Interfacing to Objective-C 497

35 Portability Guide 503

36 Named Character Entities 505

37 Memory Safety 513

CONTENTS 3

38 Application Binary Interface 515

39 Vector Extensions 535

Chapter 1

Introduction

The D programming language is a general purpose systems programming language. To that end,
a D program is a collection of modules that can be compiled separately to native code that is
combined with libraries and compiled C code by a linker to create a native executable.

Phases of Compilation
The process of compiling is divided into multiple phases. Each phase has no dependence on subse-
quent phases. For example, the scanner is not perturbed by the semantic analyzer. This separation
of the passes makes language tools like syntax directed editors relatively easy to produce. It also is
possible to compress D source by storing it in ‘tokenized’ form.

1. source character set

The source file is checked to see what character set it is, and the appropriate scanner is loaded.
ASCII and UTF formats are accepted.
2. script line
If the first line starts with "#!", then that line is ignored.
3. lexical analysis
The source file is divided up into a sequence of tokens. Special tokens are replaced with other
tokens. SpecialTokenSequences are processed and removed.
4. syntax analysis
The sequence of tokens is parsed to form syntax trees.
5. semantic analysis
The syntax trees are traversed to declare variables, load symbol tables, assign types, and in
general determine the meaning of the program.
6. optimization
Optimization is an optional pass that tries to rewrite the program in a semantically equivalent,
but faster executing, version.

5
6 CHAPTER 1. INTRODUCTION

7. code generation
Instructions are selected from the target architecture to implement the semantics of the pro-
gram. The typical result will be an object file, suitable for input to a linker.
Chapter 2

Lexical

The lexical analysis is independent of the syntax parsing and the semantic analysis. The lexical
analyzer splits the source text up into tokens. The lexical grammar describes what those tokens
are. The grammar is designed to be suitable for high speed scanning, it has a minimum of special
case rules, there is only one phase of translation, and to make it easy to write a correct scanner for.
The tokens are readily recognizable by those familiar with C and C++.

Source Text
D source text can be in one of the following formats:

• ASCII

• UTF-8

• UTF-16BE

• UTF-16LE

• UTF-32BE

• UTF-32LE

UTF-8 is a superset of traditional 7-bit ASCII. One of the following UTF BOMs (Byte Order
Marks) can be present at the beginning of the source text:

7
8 CHAPTER 2. LEXICAL

UTF Byte Order Marks

Format BOM
UTF-8 EF BB BF
UTF-16BE FE FF
UTF-16LE FF FE
UTF-32BE 00 00 FE FF
UTF-32LE FF FE 00 00
ASCII no BOM

If the source file does not start with a BOM, then the first character must be less than or equal
to U+0000007F.
There are no digraphs or trigraphs in D.
The source text is decoded from its source representation into Unicode Character s. The Charac-
ter s are further divided into: WhiteSpace, EndOfLine, Comments, SpecialTokenSequences, Tokens,
all followed by EndOfFile.
The source text is split into tokens using the maximal munch technique, i.e., the lexical analyzer
tries to make the longest token it can. For example >> is a right shift token, not two greater than
tokens. There are two exceptions to this rule:

• A .. embedded inside what looks like two floating point literals, as in 1..2, is interpreted as
if the .. was separated by a space from the first integer.
• A 1.a is interpreted as the three tokens 1, ., and a, while 1. a is interpreted as the two
tokens 1. and a

Character Set
Character:
any Unicode character

End of File
EndOfFile:
physical end of the file
\u0000
\u001A

The source text is terminated by whichever comes first.

 9

End of Line
EndOfLine:
\u000D
\u000A
\u000D \u000A
\u2028
\u2029
EndOfFile

There is no backslash line splicing, nor are there any limits on the length of a line.

White Space
WhiteSpace:
Space
Space WhiteSpace

Space:
\u0020
\u0009
\u000B
\u000C

Comments
Comment:
BlockComment
LineComment
NestingBlockComment

BlockComment:
/* Characters */

LineComment:
// Characters EndOfLine

NestingBlockComment:
/+ NestingBlockCommentCharacters +/
10 CHAPTER 2. LEXICAL

NestingBlockCommentCharacters:
NestingBlockCommentCharacter
NestingBlockCommentCharacter NestingBlockCommentCharacters

NestingBlockCommentCharacter:
Character
NestingBlockComment

Characters:
Character
Character Characters

D has three kinds of comments:

1. Block comments can span multiple lines, but do not nest.

2. Line comments terminate at the end of the line.
3. Nesting block comments can span multiple lines and can nest.

The contents of strings and comments are not tokenized. Consequently, comment openings
occurring within a string do not begin a comment, and string delimiters within a comment do not
affect the recognition of comment closings and nested "/+" comment openings. With the exception
of "/+" occurring within a "/+" comment, comment openings within a comment are ignored.
a = /+ // +/ 1; // parses as if ’a = 1;’
a = /+ "+/"␣+/␣1"; // parses as if ’a = " +/ 1";’
a = /+ /* +/ */ 3; // parses as if ’a = */ 3;’
Comments cannot be used as token concatenators, for example, abc/**/def is two tokens, abc
and def, not one abcdef token.

Tokens
Token:

Identifier FloatLiteral . &=

StringLiteral Keyword .. &&
CharacterLiteral / ... |
IntegerLiteral /= & =|
 11

|| >= ) %
- >>= [ %=
-= >>>= ] ^
-- >> { ^=
+ >>> } ^^
+= ! ? ^^=
++ != , ~
< !<> ; ~=
<= !<>= : @
<< !< $ =>
<<= !<= = #
<> !> ==
<>= !>= *
> ( *=

Identifiers

Identifier:
IdentifierStart
IdentifierStart IdentifierChars

IdentifierChars:
IdentifierChar
IdentifierChar IdentifierChars

IdentifierStart:
_
Letter
UniversalAlpha

IdentifierChar:
IdentifierStart
0
NonZeroDigit
12 CHAPTER 2. LEXICAL

Identifiers start with a letter, _, or universal alpha, and are followed by any number of letters,
_, digits, or universal alphas. Universal alphas are as defined in ISO/IEC 9899:1999(E) Appendix
D. (This is the C99 Standard.) Identifiers can be arbitrarily long, and are case sensitive. Identifiers
starting with __ (two underscores) are reserved.

String Literals
StringLiteral:
WysiwygString
AlternateWysiwygString
DoubleQuotedString

HexString
DelimitedString
TokenString

WysiwygString:
r" WysiwygCharacters " StringPostfix opt

AlternateWysiwygString:
‘ WysiwygCharacters ‘ StringPostfix opt

WysiwygCharacters:
WysiwygCharacter
WysiwygCharacter WysiwygCharacters

WysiwygCharacter:
Character
EndOfLine

DoubleQuotedString:
" DoubleQuotedCharacters " StringPostfix opt

DoubleQuotedCharacters:
DoubleQuotedCharacter
DoubleQuotedCharacter DoubleQuotedCharacters

DoubleQuotedCharacter:
Character
EscapeSequence
 13

EndOfLine

EscapeSequence:
\’
\"
\?
\\
\0
\a
\b
\f
\n
\r
\t
\v
\x HexDigit HexDigit
\ OctalDigit
\ OctalDigit OctalDigit
\ OctalDigit OctalDigit OctalDigit
\u HexDigit HexDigit HexDigit HexDigit
\U HexDigit HexDigit HexDigit HexDigit HexDigit HexDigit HexDigit HexDigit
\ NamedCharacterEntity

HexString:
x" HexStringChars " StringPostfix opt

HexStringChars:
HexStringChar
HexStringChar HexStringChars

HexStringChar:
HexDigit
WhiteSpace
EndOfLine

StringPostfix:
c
w
d
14 CHAPTER 2. LEXICAL

DelimitedString:
q" Delimiter WysiwygCharacters MatchingDelimiter "

TokenString:
q{ Token s }

A string literal is either a double quoted string, a wysiwyg quoted string, an escape sequence, a
delimited string, a token string, or a hex string.
In all string literal forms, an EndOfLine is regarded as a single \n character.

Wysiwyg Strings
Wysiwyg "what you see is what you get" quoted strings are enclosed by r" and ". All characters
between the r" and " are part of the string. There are no escape sequences inside r" ":
r"hello"
r"c:\root\foo.exe"
r"ab\n" // string is 4 characters,
// ’a’, ’b’, ’\’, ’n’
An alternate form of wysiwyg strings are enclosed by backquotes, the ‘ character. The ‘ character
is not available on some keyboards and the font rendering of it is sometimes indistinguishable from
the regular ’ character. Since, however, the ‘ is rarely used, it is useful to delineate strings with "
in them.
‘hello‘
‘c:\root\foo.exe‘
‘ab\n‘ // string is 4 characters,
// ’a’, ’b’, ’\’, ’n’

Double Quoted Strings

Double quoted strings are enclosed by "". Escape sequences can be embedded into them with the
typical \ notation.
"hello"
"c:\\root\\foo.exe"
"ab\n" // string is 3 characters,
// ’a’, ’b’, and a linefeed
"ab
 15

" // string is 3 characters,

// ’a’, ’b’, and a linefeed

Hex Strings
Hex strings allow string literals to be created using hex data. The hex data need not form valid
UTF characters.
x"0A" // same as "\x0A"
x"00␣FBCD␣32FD␣0A" // same as
// "\x00\xFB\xCD\x32\xFD\x0A"
Whitespace and newlines are ignored, so the hex data can be easily formatted. The number of
hex characters must be a multiple of 2.
Adjacent strings are concatenated with the operator, or by simple juxtaposition:
"hello␣" ~ "world" ~ "\n" // forms the string
// ’h’,’e’,’l’,’l’,’o’,’ ’,
// ’w’,’o’,’r’,’l’,’d’,linefeed
The following are all equivalent:
"ab" "c"
r"ab" r"c"
r"a" "bc"
"a" ~ "b" ~ "c"
The optional StringPostfix character gives a specific type to the string, rather than it being
inferred from the context. This is useful when the type cannot be unambiguously inferred, such as
when overloading based on string type. The types corresponding to the postfix characters are:

String Literal Postfix Characters

Postfix Type Aka
c immutable(char)[] string
w immutable(wchar)[] wstring
d immutable(dchar)[] dstring

"hello"c // string
"hello"w // wstring
"hello"d // dstring
16 CHAPTER 2. LEXICAL

The string literals are assembled as UTF-8 char arrays, and the postfix is applied to convert to
wchar or dchar as necessary as a final step.
String literals are read only. Writes to string literals cannot always be detected, but cause
undefined behavior.

Delimited Strings
Delimited strings use various forms of delimiters. The delimiter, whether a character or identifer,
must immediately follow the " without any intervening whitespace. The terminating delimiter must
immediately precede the closing " without any intervening whitespace. A nesting delimiter nests,
and is one of the following characters:

Nesting Delimiters
Delimiter Matching Delimiter
[ ]
( )
< >
{ }

q"(foo(xxx))" // "foo(xxx)"
q"[foo{]" // "foo{"
If the delimiter is an identifier, the identifier must be immediately followed by a newline, and
the matching delimiter is the same identifier starting at the beginning of the line:
writeln(q"EOS
This
is␣a␣multi-line
heredoc␣string
EOS"
);
The newline following the opening identifier is not part of the string, but the last newline before
the closing identifier is part of the string. The closing identifier must be placed on its own line at
the leftmost column.
Otherwise, the matching delimiter is the same as the delimiter character:
q"/foo]/" // "foo]"
// q"/abc/def/" // error
 17

Token Strings
Token strings open with the characters q{ and close with the token }. In between must be valid D
tokens. The { and } tokens nest. The string is formed of all the characters between the opening
and closing of the token string, including comments.
q{foo} // "foo"
q{/*}*/ } // "/*}*/ "
q{ foo(q{hello}); } // " foo(q{hello}); "
q{ __TIME__ } // " __TIME__ "
// i.e. it is not replaced with the time
// q{ __EOF__ } // error
// __EOF__ is not a token, it’s end of file

Escape Sequences
The following table explains the meaning of the escape sequences listed in EscapeSequence:

Escape Sequences
Sequence Meaning
\’ Literal single-quote: ’
\" Literal double-quote: "
\? Literal question mark: ?
\\ Literal backslash: \
\0 Binary zero (NUL, U+0000).
\a BEL (alarm) character (U+0007).
\b Backspace (U+0008).
\f Form feed (FF) (U+000C).
\n End-of-line (U+000A).
\r Carriage return (U+000D).
\t Horizontal tab (U+0009).
\v Vertical tab (U+000B).
\xnn Byte value in hexadecimal, where nn is specified as two hexadecimal digits.For example: \xFF r
\n\nn\nnn Byte value in octal.For example: \775 represents the character with the value 509.
\unnnn Unicode character U+nnnn, where nnnn are four hexadecimal digits.For example, \u042F repre
\Unnnnnnnn Unicode character U+nnnnnnnn, where nnnnnnnn are 8 hexadecimal digits.For example, \U000
\name Named character entity from the HTML5 specification. See NamedCharacterEntity for more de

Character Literals
CharacterLiteral:
18 CHAPTER 2. LEXICAL

’ SingleQuotedCharacter ’

SingleQuotedCharacter:
Character
EscapeSequence

Character literals are a single character or escape sequence enclosed by single quotes, ’␣’.

Integer Literals
IntegerLiteral:
Integer
Integer IntegerSuffix

Integer:
DecimalInteger
BinaryInteger
HexadecimalInteger

IntegerSuffix:
L
u
U
Lu
LU
uL
UL

DecimalInteger:
0
NonZeroDigit
NonZeroDigit DecimalDigitsUS

BinaryInteger:
BinPrefix BinaryDigitsUS

BinPrefix:
0b
0B
 19

HexadecimalInteger:
HexPrefix HexDigitsNoSingleUS

NonZeroDigit:
1
2
3
4
5
6
7
8
9

DecimalDigits:
DecimalDigit
DecimalDigit DecimalDigits

DecimalDigitsUS:
DecimalDigitUS
DecimalDigitUS DecimalDigitsUS

DecimalDigitsNoSingleUS:
DecimalDigit
DecimalDigit DecimalDigitsUS
DecimalDigitsUS DecimalDigit

DecimalDigitsNoStartingUS:
DecimalDigit
DecimalDigit DecimalDigitsUS

DecimalDigit:
0
NonZeroDigit

DecimalDigitUS:
DecimalDigit
_
20 CHAPTER 2. LEXICAL

BinaryDigitsUS:
BinaryDigitUS
BinaryDigitUS BinaryDigitsUS

BinaryDigit:
0
1

BinaryDigitUS:
BinaryDigit
_

OctalDigits:
OctalDigit
OctalDigit OctalDigits

OctalDigitsUS:
OctalDigitUS
OctalDigitUS OctalDigitsUS

OctalDigit:
0
1
2
3
4
5
6
7

OctalDigitUS:
OctalDigit
_

HexDigits:
HexDigit
HexDigit HexDigits

HexDigitsUS:
HexDigitUS
 21

HexDigitUS HexDigitsUS

HexDigitsNoSingleUS:
HexDigit
HexDigit HexDigitsUS
HexDigitsUS HexDigit

HexDigitsNoStartingUS:
HexDigit
HexDigit HexDigitsUS

HexDigit:
DecimalDigit
HexLetter

HexLetter:
a
b
c
d
e
f
A
B
C
D
E
F
_

Integers can be specified in decimal, binary, octal, or hexadecimal.

Decimal integers are a sequence of decimal digits.
Binary integers are a sequence of binary digits preceded by a ‘0b’.
C-style octal integer notation was deemed too easy to mix up with decimal notation. The above
is only fully supported in string literals. D still supports octal integer literals interpreted at compile
time through the std.conv.octal template, as in octal!167.
Hexadecimal integers are a sequence of hexadecimal digits preceded by a ‘0x’.
Integers can have embedded ‘_’ characters, which are ignored. The embedded ‘_’ are useful for
formatting long literals, such as using them as a thousands separator:
22 CHAPTER 2. LEXICAL

123_456 // 123456
1_2_3_4_5_6_ // 123456
Integers can be immediately followed by one ‘L’ or one of ‘u’ or ‘U’ or both. Note that there is
no ‘l’ suffix.
The type of the integer is resolved as follows:

Decimal Literal Types

Literal Type
Usual decimal notation
0 .. 2_147_483_647 int
2_147_483_648 .. 9_223_372_036_854_775_807 long
Explicit suffixes
0L .. 9_223_372_036_854_775_807L long
0U .. 4_294_967_296U uint
4_294_967_296U .. 18_446_744_073_709_551_615U ulong
0UL .. 18_446_744_073_709_551_615UL ulong
Hexadecimal notation
0x0 .. 0x7FFF_FFFF int
0x8000_0000 .. 0xFFFF_FFFF uint
0x1_0000_0000 .. 0x7FFF_FFFF_FFFF_FFFF long
0x8000_0000_0000_0000 .. 0xFFFF_FFFF_FFFF_FFFF ulong
Hexadecimal notation with explicit suffixes
0x0L .. 0x7FFF_FFFF_FFFF_FFFFL long
0x8000_0000_0000_0000L .. 0xFFFF_FFFF_FFFF_FFFFL ulong
0x0U .. 0xFFFF_FFFFU uint
0x1_0000_0000U .. 0xFFFF_FFFF_FFFF_FFFFU ulong
0x0UL .. 0xFFFF_FFFF_FFFF_FFFFUL ulong

Floating Point Literals

FloatLiteral:
Float
Float Suffix
Integer ImaginarySuffix
Integer FloatSuffix ImaginarySuffix
Integer RealSuffix ImaginarySuffix

Float:
 23

DecimalFloat
HexFloat

DecimalFloat:
LeadingDecimal .
LeadingDecimal . DecimalDigits
DecimalDigits . DecimalDigitsNoStartingUS DecimalExponent
. DecimalInteger
. DecimalInteger DecimalExponent
LeadingDecimal DecimalExponent

DecimalExponent
DecimalExponentStart DecimalDigitsNoSingleUS

DecimalExponentStart
e
E
e+
E+
e-
E-

HexFloat:
HexPrefix HexDigitsNoSingleUS . HexDigitsNoStartingUS HexExponent
HexPrefix . HexDigitsNoStartingUS HexExponent
HexPrefix HexDigitsNoSingleUS HexExponent

HexPrefix:
0x
0X

HexExponent:
HexExponentStart DecimalDigitsNoSingleUS

HexExponentStart:
p
P
p+
P+
p-
24 CHAPTER 2. LEXICAL

P-

Suffix:
FloatSuffix
RealSuffix
ImaginarySuffix
FloatSuffix ImaginarySuffix
RealSuffix ImaginarySuffix

FloatSuffix:
f
F

RealSuffix:
L

ImaginarySuffix:
i

LeadingDecimal:
DecimalInteger
0 DecimalDigitsNoSingleUS

Floats can be in decimal or hexadecimal format.

Hexadecimal floats are preceded with a 0x and the exponent is a p or P followed by a decimal
number serving as the exponent of 2.
Floating literals can have embedded ‘_’ characters, which are ignored. The embedded ‘_’ are
useful for formatting long literals to make them more readable, such as using them as a thousands
separator:
123_456.567_8 // 123456.5678
1_2_3_4_5_6_.5_6_7_8 // 123456.5678
1_2_3_4_5_6_.5e-6_ // 123456.5e-6
Floating literals with no suffix are of type double. Floats can be followed by one f, F, or L
suffix. The f or F suffix means it is a float, and L means it is a real.
If a floating literal is followed by i, then it is an ireal (imaginary) type.
Examples:
0x1.FFFFFFFFFFFFFp1023 // double.max
 25

0x1p-52 // double.epsilon
1.175494351e-38F // float.min
6.3i // idouble 6.3
6.3fi // ifloat 6.3
6.3Li // ireal 6.3
It is an error if the literal exceeds the range of the type. It is not an error if the literal is rounded
to fit into the significant digits of the type.
Complex literals are not tokens, but are assembled from real and imaginary expressions during
semantic analysis:
4.5 + 6.2i // complex number (phased out)

Keywords
Keywords are reserved identifiers.
See Also: Globally Defined Symbols.

Keyword:

abstract char extern in

alias class inout
align const false int
asm continue final interface
assert creal finally invariant
auto float ireal
dchar for is
body debug foreach
bool default foreach_reverse lazy
break delegate function long
byte delete (deprecated)
deprecated goto macro (unused)
case do mixin
cast double idouble module
catch if
cdouble else ifloat new
cent enum immutable nothrow
cfloat export import null
26 CHAPTER 2. LEXICAL

shared
out short ubyte __FILE__
override static ucent __MODULE__
struct uint __LINE__
package super ulong __FUNCTION__
pragma switch union __PRETTY_FUNCTION__
private synchronized unittest
protected ushort __gshared
public template __traits
pure this version __vector
throw void __parameters
real true volatile (deprecated)
ref try
return typedef (deprecated) wchar
typeid while
scope typeof with

Globally Defined Symbols

These are defined in object_.d, which is automatically imported by the default implementation.

Symbols:

string (alias to immutable(char)[])

dstring (alias <!--
to immutable(dchar)[])
This
size_t
is important; people want to know these things u
wstring (alias to immutable(wchar)[]) ptrdiff_t

Special Tokens
These tokens are replaced with other tokens according to the following table:
 27

Special Tokens
Special Token Replaced with
__DATE__ string literal of the date of compilation "mmm dd yyyy"
__EOF__ sets the scanner to the end of the file
__TIME__ string literal of the time of compilation "hh:mm:ss"
__TIMESTAMP__ string literal of the date and time of compilation "www mmm dd hh:mm:ss
yyyy"
__VENDOR__ Compiler vendor string, such as "Digital Mars D"
__VERSION__ Compiler version as an integer, such as 2001

Special Token Sequences

SpecialTokenSequence:
# line IntegerLiteral EndOfLine
# line IntegerLiteral Filespec EndOfLine

Filespec:
" Characters "

Special token sequences are processed by the lexical analyzer, may appear between any other
tokens, and do not affect the syntax parsing.
There is currently only one special token sequence, #line.
This sets the source line number to IntegerLiteral, and optionally the source file name to Filespec,
beginning with the next line of source text. The source file and line number is used for printing error
messages and for mapping generated code back to the source for the symbolic debugging output.
For example:
int #line 6 "foo\bar"
x; // this is now line 6 of file foo\bar
Note that the backslash character is not treated specially inside Filespec strings.
Chapter 3

Grammar

Lexical Syntax
Refer to the page for lexical syntax.

Type
Type:
TypeCtors opt BasicType BasicType2 opt

TypeCtors:
TypeCtor
TypeCtor TypeCtors

TypeCtor:
const
immutable
inout
shared

BasicType:
BasicTypeX
. IdentifierList
IdentifierList
Typeof
Typeof . IdentifierList
TypeCtor ( Type )
TypeVector

29
30 CHAPTER 3. GRAMMAR

BasicTypeX:
bool
byte
ubyte
short
ushort
int
uint
long
ulong
char
wchar
dchar
float
double
real
ifloat
idouble
ireal
cfloat
cdouble
creal
void

BasicType2:
BasicType2X BasicType2 opt

BasicType2X:
*
[ ]
[ AssignExpression ]
[ AssignExpression .. AssignExpression ]
[ Type ]
delegate Parameters MemberFunctionAttributes opt
function Parameters FunctionAttributes opt

IdentifierList:
Identifier
Identifier . IdentifierList
 31

TemplateInstance
TemplateInstance . IdentifierList
Identifier [ AssignExpression ]. IdentifierList

Typeof:
typeof ( Expression )
typeof ( return )

TypeVector:
__vector ( Type )

Expression
Expression:
CommaExpression

CommaExpression:
AssignExpression
AssignExpression , CommaExpression

AssignExpression:
ConditionalExpression
ConditionalExpression = AssignExpression
ConditionalExpression += AssignExpression
ConditionalExpression -= AssignExpression
ConditionalExpression *= AssignExpression
ConditionalExpression /= AssignExpression
ConditionalExpression %= AssignExpression
ConditionalExpression &= AssignExpression
ConditionalExpression =| AssignExpression
ConditionalExpression ^= AssignExpression
ConditionalExpression ~= AssignExpression
ConditionalExpression <<= AssignExpression
ConditionalExpression >>= AssignExpression
ConditionalExpression >>>= AssignExpression
ConditionalExpression ^^= AssignExpression

ConditionalExpression:
32 CHAPTER 3. GRAMMAR

OrOrExpression
OrOrExpression ? Expression : ConditionalExpression

OrOrExpression:
AndAndExpression
OrOrExpression || AndAndExpression

AndAndExpression:
OrExpression
AndAndExpression && OrExpression
CmpExpression
AndAndExpression && CmpExpression

OrExpression:
XorExpression
OrExpression | XorExpression

XorExpression:
AndExpression
XorExpression ^ AndExpression

AndExpression:
ShiftExpression
AndExpression & ShiftExpression

CmpExpression:
ShiftExpression
EqualExpression
IdentityExpression
RelExpression
InExpression

EqualExpression:
ShiftExpression == ShiftExpression
 33

ShiftExpression != ShiftExpression

IdentityExpression:
ShiftExpression is ShiftExpression
ShiftExpression !is ShiftExpression

RelExpression:
ShiftExpression < ShiftExpression
ShiftExpression <= ShiftExpression
ShiftExpression > ShiftExpression
ShiftExpression >= ShiftExpression
ShiftExpression !<>= ShiftExpression
ShiftExpression !<> ShiftExpression
ShiftExpression <> ShiftExpression
ShiftExpression <>= ShiftExpression
ShiftExpression !> ShiftExpression
ShiftExpression !>= ShiftExpression
ShiftExpression !< ShiftExpression
ShiftExpression !<= ShiftExpression

InExpression:
ShiftExpression in ShiftExpression
ShiftExpression !in ShiftExpression

ShiftExpression:
AddExpression
ShiftExpression << AddExpression
ShiftExpression >> AddExpression
ShiftExpression >>> AddExpression

AddExpression:
MulExpression
AddExpression + MulExpression
AddExpression - MulExpression
CatExpression
34 CHAPTER 3. GRAMMAR

CatExpression:
AddExpression ~ MulExpression

MulExpression:
UnaryExpression
MulExpression * UnaryExpression
MulExpression / UnaryExpression
MulExpression % UnaryExpression

UnaryExpression:
& UnaryExpression
++ UnaryExpression
-- UnaryExpression
* UnaryExpression
- UnaryExpression
+ UnaryExpression
! UnaryExpression
ComplementExpression
( Type ) . Identifier
( Type ) . TemplateInstance
DeleteExpression
CastExpression
PowExpression

ComplementExpression:
~ UnaryExpression

NewExpression:
new AllocatorArguments opt Type
NewExpressionWithArgs

NewExpressionWithArgs:
new AllocatorArguments opt Type [ AssignExpression ]
new AllocatorArguments opt Type ( ArgumentList opt )
NewAnonClassExpression
 35

AllocatorArguments:
( ArgumentList opt )

ArgumentList:
AssignExpression
AssignExpression ,
AssignExpression , ArgumentList

NewAnonClassExpression:
new AllocatorArguments opt class ClassArguments opt SuperClass opt Interfaces opt AggregateBody

ClassArguments:
( ArgumentList opt )

DeleteExpression:
delete UnaryExpression

CastExpression:
cast ( Type ) UnaryExpression
cast ( TypeCtors opt ) UnaryExpression

PowExpression:
PostfixExpression
PostfixExpression ^^ UnaryExpression

PostfixExpression:
PrimaryExpression
PostfixExpression . Identifier
PostfixExpression . TemplateInstance
PostfixExpression . NewExpression
PostfixExpression ++
PostfixExpression --
PostfixExpression ( ArgumentList opt )
TypeCtors opt BasicType ( ArgumentList opt )
IndexExpression
SliceExpression
36 CHAPTER 3. GRAMMAR

IndexExpression:
PostfixExpression [ ArgumentList ]

SliceExpression:
PostfixExpression [ ]
PostfixExpression [ AssignExpression .. AssignExpression ]

PrimaryExpression:
Identifier
. Identifier
TemplateInstance
. TemplateInstance
this
super
null
true
false
$
IntegerLiteral
FloatLiteral
CharacterLiteral
StringLiterals
ArrayLiteral
AssocArrayLiteral
FunctionLiteral
AssertExpression
MixinExpression
ImportExpression
NewExpressionWithArgs
BasicTypeX . Identifier
Typeof
TypeidExpression
IsExpression
( Expression )
TraitsExpression
SpecialKeyword
 37

StringLiterals:
StringLiteral
StringLiterals StringLiteral

ArrayLiteral:
[ ArgumentList opt ]

AssocArrayLiteral:
[ KeyValuePairs ]

KeyValuePairs:
KeyValuePair
KeyValuePair , KeyValuePairs

KeyValuePair:
KeyExpression : ValueExpression

KeyExpression:
AssignExpression

ValueExpression:
AssignExpression

FunctionLiteral:
function Type opt ParameterAttributes opt FunctionLiteralBody
delegate Type opt ParameterMemberAttributes opt FunctionLiteralBody
ParameterMemberAttributes FunctionLiteralBody
FunctionLiteralBody
Lambda

ParameterAttributes:
Parameters FunctionAttributes opt

ParameterMemberAttributes:
Parameters MemberFunctionAttributes opt
38 CHAPTER 3. GRAMMAR

FunctionLiteralBody:
BlockStatement
FunctionContracts opt BodyStatement

Lambda:
function Type opt ParameterAttributes => AssignExpression
delegate Type opt ParameterMemberAttributes => AssignExpression
ParameterMemberAttributes => AssignExpression
Identifier => AssignExpression

AssertExpression:
assert ( AssignExpression )
assert ( AssignExpression , AssignExpression )

MixinExpression:
mixin ( AssignExpression )

ImportExpression:
import ( AssignExpression )

TypeidExpression:
typeid ( Type )
typeid ( Expression )

IsExpression:
is ( Type )
is ( Type : TypeSpecialization )
is ( Type == TypeSpecialization )
is ( Type : TypeSpecialization , TemplateParameterList )
is ( Type == TypeSpecialization , TemplateParameterList )
is ( Type Identifier )
is ( Type Identifier : TypeSpecialization )
is ( Type Identifier == TypeSpecialization )
is ( Type Identifier : TypeSpecialization , TemplateParameterList )
is ( Type Identifier == TypeSpecialization , TemplateParameterList )
 39

TypeSpecialization:
Type
struct
union
class
interface
enum
function
delegate
super
const
immutable
inout
shared
return
__parameters

TraitsExpression:
__traits ( TraitsKeyword , TraitsArguments )

TraitsKeyword:
isAbstractClass
isArithmetic
isAssociativeArray
isFinalClass
isPOD
isNested
isFloating
isIntegral
isScalar
isStaticArray
isUnsigned
isVirtualFunction
isVirtualMethod
isAbstractFunction
isFinalFunction
isStaticFunction
isOverrideFunction
isRef
40 CHAPTER 3. GRAMMAR

isOut
isLazy
hasMember
identifier
getAliasThis
getAttributes
getFunctionAttributes
getMember
getOverloads
getPointerBitmap
getProtection
getVirtualFunctions
getVirtualMethods
getUnitTests
parent
classInstanceSize
getVirtualIndex
allMembers
derivedMembers
isSame
compiles

TraitsArguments:
TraitsArgument
TraitsArgument , TraitsArguments

TraitsArgument:
AssignExpression
Type

SpecialKeyword:
__FILE__
__MODULE__
__LINE__
__FUNCTION__
__PRETTY_FUNCTION__
 41

Statement

Statement:
;
NonEmptyStatement
ScopeBlockStatement

NoScopeNonEmptyStatement:
NonEmptyStatement
BlockStatement

NoScopeStatement:
;
NonEmptyStatement
BlockStatement

NonEmptyOrScopeBlockStatement:
NonEmptyStatement
ScopeBlockStatement

NonEmptyStatement:
NonEmptyStatementNoCaseNoDefault
CaseStatement
CaseRangeStatement
DefaultStatement

NonEmptyStatementNoCaseNoDefault:
LabeledStatement
ExpressionStatement
DeclarationStatement
IfStatement
WhileStatement
DoStatement
ForStatement
ForeachStatement
SwitchStatement
FinalSwitchStatement
ContinueStatement
BreakStatement
ReturnStatement
42 CHAPTER 3. GRAMMAR

GotoStatement
WithStatement
SynchronizedStatement
TryStatement
ScopeGuardStatement
ThrowStatement
AsmStatement
PragmaStatement
MixinStatement
ForeachRangeStatement
ConditionalStatement
StaticAssert
TemplateMixin
ImportDeclaration

ScopeStatement:
NonEmptyStatement
BlockStatement

ScopeBlockStatement:
BlockStatement

LabeledStatement:
Identifier :
Identifier : NoScopeStatement
Identifier : Statement

BlockStatement:
{ }
{ StatementList }

StatementList:
Statement
Statement StatementList
 43

ExpressionStatement:
Expression ;

DeclarationStatement:
StorageClasses opt Declaration

IfStatement:
if ( IfCondition ) ThenStatement
if ( IfCondition ) ThenStatement else ElseStatement

IfCondition:
Expression
auto Identifier = Expression
TypeCtors Identifier = Expression
TypeCtors opt BasicType Declarator = Expression

ThenStatement:
ScopeStatement

ElseStatement:
ScopeStatement

WhileStatement:
while ( Expression ) ScopeStatement

DoStatement:
do ScopeStatement while ( Expression ) ;

ForStatement:
for ( Initialize Test opt ; Increment opt ) ScopeStatement

Initialize:
;
NoScopeNonEmptyStatement

Test:
44 CHAPTER 3. GRAMMAR

Expression

Increment:
Expression

ForeachStatement:
Foreach ( ForeachTypeList ; ForeachAggregate ) NoScopeNonEmptyStatement

Foreach:
foreach
foreach_reverse

ForeachTypeList:
ForeachType
ForeachType , ForeachTypeList

ForeachType:
ForeachTypeAttributes opt BasicType Declarator
ForeachTypeAttributes opt Identifier

ForeachTypeAttributes
ForeachTypeAttribute
ForeachTypeAttribute ForeachTypeAttributes opt

ForeachTypeAttribute:
ref
TypeCtor

ForeachAggregate:
Expression

ForeachRangeStatement:
Foreach ( ForeachType ; LwrExpression .. UprExpression ) ScopeStatement

LwrExpression:
Expression

UprExpression:
 45

Expression

SwitchStatement:
switch ( Expression ) ScopeStatement

CaseStatement:
case ArgumentList : ScopeStatementList

CaseRangeStatement:
case FirstExp : .. case LastExp : ScopeStatementList

FirstExp:
AssignExpression

LastExp:
AssignExpression

DefaultStatement:
default : ScopeStatementList

ScopeStatementList:
StatementListNoCaseNoDefault

StatementListNoCaseNoDefault:
StatementNoCaseNoDefault
StatementNoCaseNoDefault StatementListNoCaseNoDefault

StatementNoCaseNoDefault:
;
NonEmptyStatementNoCaseNoDefault
ScopeBlockStatement

FinalSwitchStatement:
final switch ( Expression ) ScopeStatement

ContinueStatement:
continue Identifier opt ;
46 CHAPTER 3. GRAMMAR

BreakStatement:
break Identifier opt ;

ReturnStatement:
return Expression opt ;

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

WithStatement:
with ( Expression ) ScopeStatement
with ( Symbol ) ScopeStatement
with ( TemplateInstance ) ScopeStatement

SynchronizedStatement:
synchronized ScopeStatement
synchronized ( Expression ) ScopeStatement

TryStatement:
try ScopeStatement Catches
try ScopeStatement Catches FinallyStatement
try ScopeStatement FinallyStatement

Catches:
LastCatch
Catch
Catch Catches

LastCatch:
catch NoScopeNonEmptyStatement

Catch:
catch ( CatchParameter ) NoScopeNonEmptyStatement
 47

CatchParameter:
BasicType Identifier

FinallyStatement:
finally NoScopeNonEmptyStatement

ThrowStatement:
throw Expression ;

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

AsmStatement:
asm FunctionAttributes opt { AsmInstructionList opt }

AsmInstructionList:
AsmInstruction ;
AsmInstruction ; AsmInstructionList

PragmaStatement:
Pragma NoScopeStatement

MixinStatement:
mixin ( AssignExpression ) ;

Iasm
AsmInstruction:
Identifier : AsmInstruction
align IntegerExpression
even
naked
48 CHAPTER 3. GRAMMAR

db Operands
ds Operands
di Operands
dl Operands
df Operands
dd Operands
de Operands
Opcode
Opcode Operands

Operands:
Operand
Operand , Operands

IntegerExpression:
IntegerLiteral
Identifier

Register:
AL AH AX EAX
BL BH BX EBX
CL CH CX ECX
DL DH DX EDX
BP EBP
SP ESP
DI EDI
SI ESI
ES CS SS DS GS FS
CR0 CR2 CR3 CR4
DR0 DR1 DR2 DR3 DR6 DR7
TR3 TR4 TR5 TR6 TR7
ST
ST(0) ST(1) ST(2) ST(3) ST(4) ST(5) ST(6) ST(7)
MM0 MM1 MM2 MM3 MM4 MM5 MM6 MM7
XMM0 XMM1 XMM2 XMM3 XMM4 XMM5 XMM6 XMM7

Register64:
 49

RAX RBX RCX RDX

BPL RBP
SPL RSP
DIL RDI
SIL RSI
R8B R8W R8D R8
R9B R9W R9D R9
R10B R10W R10D R10
R11B R11W R11D R11
R12B R12W R12D R12
R13B R13W R13D R13
R14B R14W R14D R14
R15B R15W R15D R15
XMM8 XMM9 XMM10 XMM11 XMM12 XMM13 XMM14 XMM15
YMM0 YMM1 YMM2 YMM3 YMM4 YMM5 YMM6 YMM7
YMM8 YMM9 YMM10 YMM11 YMM12 YMM13 YMM14 YMM15

Operand:
AsmExp

AsmExp:
AsmLogOrExp
AsmLogOrExp ? AsmExp : AsmExp

AsmLogOrExp:
AsmLogAndExp
AsmLogOrExp || AsmLogAndExp

AsmLogAndExp:
AsmOrExp
AsmLogAndExp && AsmOrExp

AsmOrExp:
AsmXorExp
AsmOrExp | AsmXorExp

AsmXorExp:
AsmAndExp
AsmXorExp ^ AsmAndExp
50 CHAPTER 3. GRAMMAR

AsmAndExp:
AsmEqualExp
AsmAndExp & AsmEqualExp

AsmEqualExp:
AsmRelExp
AsmEqualExp == AsmRelExp
AsmEqualExp != AsmRelExp

AsmRelExp:
AsmShiftExp
AsmRelExp < AsmShiftExp
AsmRelExp <= AsmShiftExp
AsmRelExp > AsmShiftExp
AsmRelExp >= AsmShiftExp

AsmShiftExp:
AsmAddExp
AsmShiftExp << AsmAddExp
AsmShiftExp >> AsmAddExp
AsmShiftExp >>> AsmAddExp

AsmAddExp:
AsmMulExp
AsmAddExp + AsmMulExp
AsmAddExp - AsmMulExp

AsmMulExp:
AsmBrExp
AsmMulExp * AsmBrExp
AsmMulExp / AsmBrExp
AsmMulExp % AsmBrExp

AsmBrExp:
AsmUnaExp
AsmBrExp [ AsmExp ]

AsmUnaExp:
AsmTypePrefix AsmExp
 51

offsetof AsmExp
seg AsmExp
+ AsmUnaExp
- AsmUnaExp
! AsmUnaExp
~ AsmUnaExp
AsmPrimaryExp

AsmPrimaryExp:
IntegerLiteral
FloatLiteral
__LOCAL_SIZE
$
Register
Register : AsmExp
Register64
Register64 : AsmExp
DotIdentifier
this

DotIdentifier:
Identifier
Identifier . DotIdentifier

AsmTypePrefix:
near ptr
far ptr
byte ptr
short ptr
int ptr
word ptr
dword ptr
qword ptr
float ptr
double ptr
real ptr
52 CHAPTER 3. GRAMMAR

Declaration
Declaration:
FuncDeclaration
VarDeclarations
AliasDeclaration
AggregateDeclaration
EnumDeclaration
ImportDeclaration

AliasDeclaration:
alias StorageClasses opt BasicType Declarator ;
alias StorageClasses opt BasicType FuncDeclarator ;
alias AliasDeclarationX ;

AliasDeclarationX:
Identifier TemplateParameters opt = StorageClasses opt Type
AliasDeclarationX , Identifier TemplateParameters opt = StorageClasses opt Type

AutoDeclaration:
StorageClasses AutoDeclarationX ;

AutoDeclarationX:
Identifier TemplateParameters opt = Initializer
AutoDeclarationX , Identifier TemplateParameters opt = Initializer

VarDeclarations:
StorageClasses opt BasicType Declarators ;
AutoDeclaration

Declarators:
DeclaratorInitializer
DeclaratorInitializer , DeclaratorIdentifierList

DeclaratorInitializer:
VarDeclarator
VarDeclarator TemplateParameters opt = Initializer
AltDeclarator
 53

AltDeclarator = Initializer

DeclaratorIdentifierList:
DeclaratorIdentifier
DeclaratorIdentifier , DeclaratorIdentifierList

DeclaratorIdentifier:
VarDeclaratorIdentifier
AltDeclaratorIdentifier

VarDeclaratorIdentifier:
Identifier
Identifier TemplateParameters opt = Initializer

AltDeclaratorIdentifier:
BasicType2 Identifier AltDeclaratorSuffixes opt
BasicType2 Identifier AltDeclaratorSuffixes opt = Initializer
BasicType2 opt Identifier AltDeclaratorSuffixes
BasicType2 opt Identifier AltDeclaratorSuffixes = Initializer

Declarator:
VarDeclarator
AltDeclarator

VarDeclarator:
BasicType2 opt Identifier

AltDeclarator:
BasicType2 opt Identifier AltDeclaratorSuffixes
BasicType2 opt ( AltDeclaratorX )
BasicType2 opt ( AltDeclaratorX ) AltFuncDeclaratorSuffix
BasicType2 opt ( AltDeclaratorX ) AltDeclaratorSuffixes

AltDeclaratorX:
BasicType2 opt Identifier
BasicType2 opt Identifier AltFuncDeclaratorSuffix
AltDeclarator

AltDeclaratorSuffixes:
AltDeclaratorSuffix
54 CHAPTER 3. GRAMMAR

AltDeclaratorSuffix AltDeclaratorSuffixes

AltDeclaratorSuffix:
[ ]
[ AssignExpression ]
[ Type ]

AltFuncDeclaratorSuffix:
Parameters MemberFunctionAttributes opt

StorageClasses:
StorageClass
StorageClass StorageClasses

StorageClass:
LinkageAttribute
AlignAttribute
deprecated
enum
static
extern
abstract
final
override
synchronized
auto
scope
const
immutable
inout
shared
__gshared
Property
nothrow
pure
ref

Initializer:
 55

VoidInitializer
NonVoidInitializer

VoidInitializer:
void

NonVoidInitializer:
ExpInitializer :
ArrayInitializer
StructInitializer

ExpInitializer:
AssignExpression

ArrayInitializer:
[ ArrayMemberInitializations opt ]

ArrayMemberInitializations:
ArrayMemberInitialization
ArrayMemberInitialization ,
ArrayMemberInitialization , ArrayMemberInitializations

ArrayMemberInitialization:
NonVoidInitializer
AssignExpression : NonVoidInitializer

StructInitializer:
{ StructMemberInitializers opt }

StructMemberInitializers:
StructMemberInitializer
StructMemberInitializer ,
StructMemberInitializer , StructMemberInitializers

StructMemberInitializer:
NonVoidInitializer
Identifier : NonVoidInitializer
56 CHAPTER 3. GRAMMAR

Function
FuncDeclaration:
StorageClasses opt BasicType FuncDeclarator FunctionBody
AutoFuncDeclaration

AutoFuncDeclaration:
StorageClasses Identifier FuncDeclaratorSuffix FunctionBody

FuncDeclarator:
BasicType2 opt Identifier FuncDeclaratorSuffix

FuncDeclaratorSuffix:
Parameters MemberFunctionAttributes opt
TemplateParameters Parameters MemberFunctionAttributes opt Constraint opt

Parameters:
( ParameterList opt )

ParameterList:
Parameter
Parameter , ParameterList
...

Parameter:
InOut opt BasicType Declarator
InOut opt BasicType Declarator ...
InOut opt BasicType Declarator = AssignExpression
InOut opt Type
InOut opt Type ...

InOut:
InOutX
InOut InOutX

InOutX:
auto
TypeCtor
final
 57

in
lazy
out
ref
scope

FunctionAttributes:
FunctionAttribute
FunctionAttribute FunctionAttributes

FunctionAttribute:
nothrow
pure
Property

MemberFunctionAttributes:
MemberFunctionAttribute
MemberFunctionAttribute MemberFunctionAttributes

MemberFunctionAttribute:
const
immutable
inout
shared
FunctionAttribute

FunctionBody:
BlockStatement
FunctionContracts opt BodyStatement
FunctionContracts

FunctionContracts:
InStatement OutStatement opt
OutStatement InStatement opt

InStatement:
in BlockStatement

OutStatement:
58 CHAPTER 3. GRAMMAR

out BlockStatement
out ( Identifier ) BlockStatement

BodyStatement:
body BlockStatement

Constructor:
this Parameters MemberFunctionAttributes opt ;
this Parameters MemberFunctionAttributes opt FunctionBody
ConstructorTemplate

ConstructorTemplate:
this TemplateParameters Parameters MemberFunctionAttributes opt Constraint opt ;
this TemplateParameters Parameters MemberFunctionAttributes opt Constraint opt FunctionBody

Destructor:
~ this ( ) MemberFunctionAttributes opt ;
~ this ( ) MemberFunctionAttributes opt FunctionBody

Postblit:
this ( this ) MemberFunctionAttributes opt ;
this ( this ) MemberFunctionAttributes opt FunctionBody

Allocator:
new Parameters ;
new Parameters FunctionBody

Deallocator:
delete Parameters ;
delete Parameters FunctionBody

Invariant:
invariant ( ) BlockStatement
invariant BlockStatement

UnitTest:
unittest BlockStatement
 59

StaticConstructor:
static this ( ) ;
static this ( ) FunctionBody

StaticDestructor:
static ~ this ( ) MemberFunctionAttributes opt ;
static ~ this ( ) MemberFunctionAttributes opt FunctionBody

SharedStaticConstructor:
shared static this ( ) ;
shared static this ( ) FunctionBody

SharedStaticDestructor:
shared static ~ this ( ) MemberFunctionAttributes opt ;
shared static ~ this ( ) MemberFunctionAttributes opt FunctionBody

Aggregate
AggregateDeclaration:
ClassDeclaration
InterfaceDeclaration
StructDeclaration
UnionDeclaration

ClassDeclaration:
class Identifier ;
class Identifier BaseClassList opt AggregateBody
ClassTemplateDeclaration

ClassTemplateDeclaration:
class Identifier TemplateParameters Constraint opt BaseClassList opt AggregateBody
class Identifier TemplateParameters BaseClassList Constraint AggregateBody

InterfaceDeclaration:
interface Identifier ;
interface Identifier BaseInterfaceList opt AggregateBody
InterfaceTemplateDeclaration

InterfaceTemplateDeclaration:
60 CHAPTER 3. GRAMMAR

interface Identifier TemplateParameters Constraint opt BaseInterfaceList opt AggregateBody

interface Identifier TemplateParameters BaseInterfaceList Constraint AggregateBody

StructDeclaration:
struct Identifier ;
struct Identifier AggregateBody
StructTemplateDeclaration
AnonStructDeclaration

StructTemplateDeclaration:
struct Identifier TemplateParameters Constraint opt AggregateBody

AnonStructDeclaration:
struct AggregateBody

UnionDeclaration:
union Identifier ;
union Identifier AggregateBody
UnionTemplateDeclaration
AnonUnionDeclaration

UnionTemplateDeclaration:
union Identifier TemplateParameters Constraint opt AggregateBody

AnonUnionDeclaration:
union AggregateBody

AggregateBody:
{ DeclDefs opt }

BaseClassList:
: SuperClass
: SuperClass , Interfaces
: Interfaces

BaseInterfaceList:
: Interfaces

SuperClass:
 61

BasicType

Interfaces:
Interface
Interface , Interfaces

Interface:
BasicType

AliasThis:
alias Identifier this ;

Enum
EnumDeclaration:
enum Identifier EnumBody
enum Identifier : EnumBaseType EnumBody
AnonymousEnumDeclaration

EnumBaseType:
Type

EnumBody:
{ EnumMembers }
;

EnumMembers:
EnumMember
EnumMember ,
EnumMember , EnumMembers

EnumMember:
Identifier
Identifier = AssignExpression

AnonymousEnumDeclaration:
enum : EnumBaseType { EnumMembers }
enum { EnumMembers }
62 CHAPTER 3. GRAMMAR

enum { AnonymousEnumMembers }

AnonymousEnumMembers:
AnonymousEnumMember
AnonymousEnumMember ,
AnonymousEnumMember , AnonymousEnumMembers

AnonymousEnumMember:
EnumMember
Type Identifier = AssignExpression

Template
TemplateDeclaration:
template Identifier TemplateParameters Constraint opt { DeclDefs opt }

TemplateParameters:
( TemplateParameterList opt )

TemplateParameterList:
TemplateParameter
TemplateParameter ,
TemplateParameter , TemplateParameterList

TemplateParameter:
TemplateTypeParameter
TemplateValueParameter
TemplateAliasParameter
TemplateTupleParameter
TemplateThisParameter

Constraint:
if ( Expression )

TemplateInstance:
Identifier TemplateArguments

TemplateArguments:
 63

! ( TemplateArgumentList opt )
! TemplateSingleArgument

TemplateArgumentList:
TemplateArgument
TemplateArgument ,
TemplateArgument , TemplateArgumentList

TemplateArgument:
Type
AssignExpression
Symbol

Symbol:
SymbolTail
. SymbolTail

SymbolTail:
Identifier
Identifier . SymbolTail
TemplateInstance
TemplateInstance . SymbolTail

TemplateSingleArgument:
Identifier
BasicTypeX
CharacterLiteral
StringLiteral
IntegerLiteral
FloatLiteral
true
false
null
this
SpecialKeyword

TemplateTypeParameter:
Identifier
Identifier TemplateTypeParameterSpecialization
64 CHAPTER 3. GRAMMAR

Identifier TemplateTypeParameterDefault
Identifier TemplateTypeParameterSpecialization TemplateTypeParameterDefault

TemplateTypeParameterSpecialization:
: Type

TemplateTypeParameterDefault:
= Type

TemplateThisParameter:
this TemplateTypeParameter

TemplateValueParameter:
BasicType Declarator
BasicType Declarator TemplateValueParameterSpecialization
BasicType Declarator TemplateValueParameterDefault
BasicType Declarator TemplateValueParameterSpecialization TemplateValueParameterDefault

TemplateValueParameterSpecialization:
: ConditionalExpression

TemplateValueParameterDefault:
= AssignExpression
= SpecialKeyword

TemplateAliasParameter:
alias Identifier TemplateAliasParameterSpecialization opt TemplateAliasParameterDefault opt
alias BasicType Declarator TemplateAliasParameterSpecialization opt TemplateAliasParameterDefau

TemplateAliasParameterSpecialization:
: Type
: ConditionalExpression

TemplateAliasParameterDefault:
= Type
= ConditionalExpression
 65

TemplateTupleParameter:
Identifier ...

TemplateMixinDeclaration:
mixin template Identifier TemplateParameters Constraint opt { DeclDefs opt }

TemplateMixin:
mixin MixinTemplateName TemplateArguments opt Identifier opt ;

MixinTemplateName:
. QualifiedIdentifierList
QualifiedIdentifierList
Typeof . QualifiedIdentifierList

QualifiedIdentifierList:
Identifier
Identifier . QualifiedIdentifierList
TemplateInstance . QualifiedIdentifierList

Attribute
AttributeSpecifier:
Attribute :
Attribute DeclarationBlock

Attribute:
LinkageAttribute
AlignAttribute
DeprecatedAttribute
ProtectionAttribute
Pragma
static
extern
abstract
final
override
synchronized
auto
66 CHAPTER 3. GRAMMAR

scope
const
immutable
inout
shared
__gshared
Property
nothrow
pure
ref

DeclarationBlock:
DeclDef
{ DeclDefs opt }

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

LinkageType:
C
C++
D
Windows
Pascal
System
Objective-C

AlignAttribute:
align
align ( IntegerLiteral )

DeprecatedAttribute:
deprecated
deprecated ( StringLiteral )

ProtectionAttribute:
 67

private
package
package ( IdentifierList )
protected
public
export

Property:
@ PropertyIdentifier
UserDefinedAttribute

PropertyIdentifier:
property
safe
trusted
system
disable
nogc

UserDefinedAttribute:
@ ( ArgumentList )
@ Identifier
@ Identifier ( ArgumentList opt )
@ TemplateInstance
@ TemplateInstance ( ArgumentList opt )

Pragma:
pragma ( Identifier )
pragma ( Identifier , ArgumentList )

Conditional
ConditionalDeclaration:
Condition DeclarationBlock
Condition DeclarationBlock else DeclarationBlock
Condition : DeclDefs opt
Condition DeclarationBlock else : DeclDefs opt
68 CHAPTER 3. GRAMMAR

ConditionalStatement:
Condition NoScopeNonEmptyStatement
Condition NoScopeNonEmptyStatement else NoScopeNonEmptyStatement

Condition:
VersionCondition
DebugCondition
StaticIfCondition

VersionCondition:
version ( IntegerLiteral )
version ( Identifier )
version ( unittest )
version ( assert )

DebugCondition:
debug
debug ( IntegerLiteral )
debug ( Identifier )

StaticIfCondition:
static if ( AssignExpression )

VersionSpecification:
version = Identifier ;
version = IntegerLiteral ;

DebugSpecification:
debug = Identifier ;
debug = IntegerLiteral ;

StaticAssert:
static assert ( AssignExpression );
static assert ( AssignExpression , AssignExpression );
 69

Module
Module:
ModuleDeclaration DeclDefs
DeclDefs

DeclDefs:
DeclDef
DeclDef DeclDefs

DeclDef:
AttributeSpecifier
Declaration
Constructor
Destructor
Postblit
Allocator
Deallocator
Invariant
UnitTest
AliasThis
StaticConstructor
StaticDestructor
SharedStaticConstructor
SharedStaticDestructor
ConditionalDeclaration
DebugSpecification
VersionSpecification
StaticAssert
TemplateDeclaration
TemplateMixinDeclaration
TemplateMixin
MixinDeclaration
;

ModuleDeclaration:
module ModuleFullyQualifiedName ;

ModuleFullyQualifiedName:
70 CHAPTER 3. GRAMMAR

ModuleName
Packages . ModuleName

ModuleName:
Identifier

Packages:
PackageName
Packages . PackageName

PackageName:
Identifier

ImportDeclaration:
import ImportList ;
static import ImportList ;

ImportList:
Import
ImportBindings
Import , ImportList

Import:
ModuleFullyQualifiedName
ModuleAliasIdentifier = ModuleFullyQualifiedName

ImportBindings:
Import : ImportBindList

ImportBindList:
ImportBind
ImportBind , ImportBindList

ImportBind:
Identifier
Identifier = Identifier

ModuleAliasIdentifier:
Identifier
 71

MixinDeclaration:
mixin ( AssignExpression ) ;
Chapter 4

Modules

Module:
ModuleDeclaration DeclDefs
DeclDefs

DeclDefs:
DeclDef
DeclDef DeclDefs

DeclDef:
AttributeSpecifier
Declaration
Constructor
Destructor
Postblit
Allocator
Deallocator
Invariant
UnitTest
AliasThis
StaticConstructor
StaticDestructor
SharedStaticConstructor
SharedStaticDestructor
ConditionalDeclaration
DebugSpecification
VersionSpecification

73
74 CHAPTER 4. MODULES

StaticAssert
TemplateDeclaration
TemplateMixinDeclaration
TemplateMixin
MixinDeclaration
;

Modules have a one-to-one correspondence with source files. The module name is, by default,
the file name with the path and extension stripped off, and can be set explicitly with the module
declaration.
Modules automatically provide a namespace scope for their contents. Modules superficially
resemble classes, but differ in that:

• There’s only one instance of each module, and it is statically allocated.

• There is no virtual table.
• Modules do not inherit, they have no super modules, etc.
• Only one module per file.
• Module symbols can be imported.
• Modules are always compiled at global scope, and are unaffected by surrounding attributes
or other modifiers.

Modules can be grouped together in hierarchies called packages.

Modules offer several guarantees:

• The order in which modules are imported does not affect the semantics.
• The semantics of a module are not affected by what imports it.
• If a module C imports modules A and B, any modifications to B will not silently change code
in C that is dependent on A.

Module Declaration
The ModuleDeclaration sets the name of the module and what package it belongs to. If absent,
the module name is taken to be the same name (stripped of path and extension) of the source file
name.

ModuleDeclaration:
ModuleAttributes opt module ModuleFullyQualifiedName ;

ModuleAttributes:
 75

ModuleAttribute
ModuleAttribute ModuleAttributes

ModuleAttribute:
DeprecatedAttribute
UserDefinedAttribute

ModuleFullyQualifiedName:
ModuleName
Packages . ModuleName

ModuleName:
Identifier

Packages:
PackageName
Packages . PackageName

PackageName:
Identifier

The Identifiers preceding the rightmost are the Packages that the module is in. The packages
correspond to directory names in the source file path. Package names cannot be keywords, hence
the corresponding directory names cannot be keywords, either.
If present, the ModuleDeclaration appears syntactically first in the source file, and there can be
only one per source file.
Example:
module c.stdio; // module stdio in the c package
By convention, package and module names are all lower case. This is because those names can
have a one-to-one correspondence with the operating system’s directory and file names, and many
file systems are not case sensitive. All lower case package and module names will minimize problems
moving projects between dissimilar file systems.
If the file name of a module is an invalid module name (e.g. foo-bar.d), you may use a module
declaration to set a valid module name:
module foo_bar;
ModuleDeclaration can have an optional DeprecatedAttribute. The compiler will produce a mes-
sage when the deprecated module is imported.
76 CHAPTER 4. MODULES

deprecated module foo;

module bar;
import foo; // Deprecated: module foo is deprecated
DeprecatedAttribute can have an optional string argument to provide a more expressive message.
deprecated("Please␣use␣foo2␣instead.")
module foo;

module bar;
import foo; // Deprecated: module foo is deprecated - Please use foo2 instead.

Import Declaration
Symbols from one module are made available in another module by using the ImportDeclaration:

ImportDeclaration:
import ImportList ;
static import ImportList ;

ImportList:
Import
ImportBindings
Import , ImportList

Import:
ModuleFullyQualifiedName
ModuleAliasIdentifier = ModuleFullyQualifiedName

ImportBindings:
Import : ImportBindList

ImportBindList:
ImportBind
ImportBind , ImportBindList

ImportBind:
Identifier
Identifier = Identifier
 77

ModuleAliasIdentifier:
Identifier

There are several forms of the ImportDeclaration, from generalized to fine-grained importing.
The order in which ImportDeclarations occur has no significance.
ModuleFullyQualifiedNames in the ImportDeclaration must be fully qualified with whatever
packages they are in. They are not considered to be relative to the module that imports them.

Basic Imports
The simplest form of importing is to just list the modules being imported:
import std.stdio; // import module stdio from package std
import foo, bar; // import modules foo and bar

void main()
{
writeln("hello!"); // calls std.stdio.writeln
}
How basic imports work is that first a name is searched for in the current namespace. If it is
not found, then it is looked for in the imports. If it is found uniquely among the imports, then that
is used. If it is in more than one import, an error occurs.
module A;
void foo();
void bar();

module B;
void foo();
void bar();

module C;
import A;
void foo();
void test()
{
foo(); // C.foo() is called, it is found before imports are searched
bar(); // A.bar() is called, since imports are searched
}
78 CHAPTER 4. MODULES

module D;
import A;
import B;
void test()
{
foo(); // error, A.foo() or B.foo() ?
A.foo(); // ok, call A.foo()
B.foo(); // ok, call B.foo()
}

module E;
import A;
import B;
alias foo = B.foo;
void test()
{
foo(); // call B.foo()
A.foo(); // call A.foo()
B.foo(); // call B.foo()
}

Public Imports
By default, imports are private. This means that if module A imports module B, and module B
imports module C, then C’s names are not searched for. An import can be specifically declared
public, when it will be treated as if any imports of the module with the ImportDeclaration also
import the public imported modules.
All symbols from a publicly imported module are also aliased in the importing module. This
means that if module D imports module C, and module C publicly imports module B which has
the symbol bar, in module D you can access the symbol via bar, B.bar, and C.bar.
module A;
void foo() { }

module B;
void bar() { }

module C;
import A;
public import B;
...
 79

foo(); // call A.foo()

bar(); // calls B.bar()

module D;
import C;
...
foo(); // error, foo() is undefined
bar(); // ok, calls B.bar()
B.bar(); // ditto
C.bar(); // ok, calls C.bar() which is an alias to B.bar()

Static Imports
Basic imports work well for programs with relatively few modules and imports. If there are a lot of
imports, name collisions can start occurring between the names in the various imported modules.
One way to stop this is by using static imports. A static import requires one to use a fully qualified
name to reference the module’s names:
static import std.stdio;

void main()
{
writeln("hello!"); // error, writeln is undefined
std.stdio.writeln("hello!"); // ok, writeln is fully qualified
}

Renamed Imports
A local name for an import can be given, through which all references to the module’s symbols
must be qualified with:
import io = std.stdio;

void main()
{
io.writeln("hello!"); // ok, calls std.stdio.writeln
std.stdio.writeln("hello!"); // error, std is undefined
writeln("hello!"); // error, writeln is undefined
}
Renamed imports are handy when dealing with very long import names.
80 CHAPTER 4. MODULES

Selective Imports
Specific symbols can be exclusively imported from a module and bound into the current namespace:
import std.stdio : writeln, foo = write;

void main()
{
std.stdio.writeln("hello!"); // error, std is undefined
writeln("hello!"); // ok, writeln bound into current namespace
write("world"); // error, write is undefined
foo("world"); // ok, calls std.stdio.write()
fwritefln(stdout, "abc"); // error, fwritefln undefined
}
static cannot be used with selective imports.

Renamed and Selective Imports

When renaming and selective importing are combined:
import io = std.stdio : foo = writeln;

void main()
{
writeln("bar"); // error, writeln is undefined
std.stdio.foo("bar"); // error, foo is bound into current namespace
std.stdio.writeln("bar"); // error, std is undefined
foo("bar"); // ok, foo is bound into current namespace,
// FQN not required
io.writeln("bar"); // ok, io=std.stdio bound the name io in
// the current namespace to refer to the entire ⤦
Ç module
io.foo("bar"); // error, foo is bound into current namespace,
// foo is not a member of io
}

Scoped Imports
Import declarations may be used at any scope. For example:
void main()
{
 81

import std.stdio;
writeln("bar");
}
The imports are looked up to satisfy any unresolved symbols at that scope. Imported symbols
may hide symbols from outer scopes.
In function scopes, imported symbols only become visible after the import declaration lexically
appears in the function body. In other words, imported symbols at function scope cannot be forward
referenced.
void main()
{
void writeln(string) {}
void foo()
{
writeln("bar"); // calls main.writeln
import std.stdio;
writeln("bar"); // calls std.stdio.writeln
void writeln(string) {}
writeln("bar"); // calls main.foo.writeln
}
writeln("bar"); // calls main.writeln
std.stdio.writeln("bar"); // error, std is undefined
}

Module Scope Operator

Sometimes, it’s necessary to override the usual lexical scoping rules to access a name hidden by a
local name. This is done with the global scope operator, which is a leading ‘.’:
int x;

int foo(int x)
{
if (y)
return x; // returns foo.x, not global x
else
return .x; // returns global x
}
The leading ‘.’ means look up the name at the module scope level.
82 CHAPTER 4. MODULES

Static Construction and Destruction

Static constructors are code that gets executed to initialize a module or a class before the main()
function gets called. Static destructors are code that gets executed after the main() function returns,
and are normally used for releasing system resources.
There can be multiple static constructors and static destructors within one module. The static
constructors are run in lexical order, the static destructors are run in reverse lexical order.
Static constructors and static destructors run on thread local data, and are run whenever threads
are created or destroyed.
Shared static constructors and shared static destructors are run on global shared data, and
constructors are run once on program startup and destructors are run once on program termination.

Order of Static Construction

Shared static constructors on all modules are run before any static constructors.
The order of static initialization is implicitly determined by the import declarations in each
module. Each module is assumed to depend on any imported modules being statically constructed
first. Other than following that rule, there is no imposed order on executing the module static
constructors.
Cycles (circular dependencies) in the import declarations are allowed as long as not both of
the modules contain static constructors or static destructors. Violation of this rule will result in a
runtime exception.

Order of Static Construction within a Module

Within a module, the static construction occurs in the lexical order in which they appear.

Order of Static Destruction

It is defined to be exactly the reverse order that static construction was performed in. Static de-
structors for individual modules will only be run if the corresponding static constructor successfully
completed.
Shared static destructors are executed after static destructors.

Order of Unit tests

Unit tests are run in the lexical order in which they appear within a module.

Mixin Declaration
MixinDeclaration:
mixin ( AssignExpression ) ;
 83

The AssignExpression must evaluate at compile time to a constant string. The text contents of
the string must be compilable as a valid DeclDefs, and is compiled as such.

Package Module
A package module can be used to publicly import other modules, while enabling a simpler import
syntax. It enables converting a module into a package of modules, without breaking existing code
which uses that module. Example of a set of library modules:
libweb/client.d:
module libweb.client;

void runClient() { }
libweb/server.d:
module libweb.server;

void runServer() { }
libweb/package.d:
module libweb;

public import libweb.client;

public import libweb.server;
The package module must have the file name package.d. The module name is declared to be the
fully qualified name of the package. Package modules can be imported just like any other modules:
test.d:
module test;

// import the package module

import libweb;

void main()
{
runClient();
runServer();
}
84 CHAPTER 4. MODULES

A package module can be nested inside of a sub-package:

libweb/utils/package.d:
// must be declared as the fully qualified name of the package, not just ’utils’
module libweb.utils;

// publicly import modules from within the ’libweb.utils’ package.

public import libweb.utils.conv;
public import libweb.utils.text;
The package module can then be imported with the standard module import declaration:
test.d:
module test;

// import the package module

import libweb.utils;

void main() { }
Chapter 5

Declarations

Declaration:
FuncDeclaration
VarDeclarations
AliasDeclaration
AggregateDeclaration
EnumDeclaration
ImportDeclaration

VarDeclarations:
StorageClasses opt BasicType Declarators ;
AutoDeclaration

Declarators:
DeclaratorInitializer
DeclaratorInitializer , DeclaratorIdentifierList

DeclaratorInitializer:
VarDeclarator
VarDeclarator TemplateParameters opt = Initializer
AltDeclarator
AltDeclarator = Initializer

DeclaratorIdentifierList:
DeclaratorIdentifier
DeclaratorIdentifier , DeclaratorIdentifierList

85
86 CHAPTER 5. DECLARATIONS

DeclaratorIdentifier:
VarDeclaratorIdentifier
AltDeclaratorIdentifier

VarDeclaratorIdentifier:
Identifier
Identifier TemplateParameters opt = Initializer

AltDeclaratorIdentifier:
BasicType2 Identifier AltDeclaratorSuffixes opt
BasicType2 Identifier AltDeclaratorSuffixes opt = Initializer
BasicType2 opt Identifier AltDeclaratorSuffixes
BasicType2 opt Identifier AltDeclaratorSuffixes = Initializer

Declarator:
VarDeclarator
AltDeclarator

VarDeclarator:
BasicType2 opt Identifier

AltDeclarator:
BasicType2 opt Identifier AltDeclaratorSuffixes
BasicType2 opt ( AltDeclaratorX )
BasicType2 opt ( AltDeclaratorX ) AltFuncDeclaratorSuffix
BasicType2 opt ( AltDeclaratorX ) AltDeclaratorSuffixes

AltDeclaratorX:
BasicType2 opt Identifier
BasicType2 opt Identifier AltFuncDeclaratorSuffix
AltDeclarator

AltDeclaratorSuffixes:
AltDeclaratorSuffix
AltDeclaratorSuffix AltDeclaratorSuffixes

AltDeclaratorSuffix:
[ ]
[ AssignExpression ]
[ Type ]
 87

AltFuncDeclaratorSuffix:
Parameters MemberFunctionAttributes opt

Type:
TypeCtors opt BasicType BasicType2 opt

TypeCtors:
TypeCtor
TypeCtor TypeCtors

TypeCtor:
const
immutable
inout
shared

BasicType:
BasicTypeX
. IdentifierList
IdentifierList
Typeof
Typeof . IdentifierList
TypeCtor ( Type )
TypeVector

BasicTypeX:

bool int wchar ifloat creal

byte uint dchar idouble void
ubyte long float ireal
short ulong double cfloat
ushort char real cdouble
88 CHAPTER 5. DECLARATIONS

BasicType2:
BasicType2X BasicType2 opt

BasicType2X:
*
[ ]
[ AssignExpression ]
[ AssignExpression .. AssignExpression ]
[ Type ]
delegate Parameters MemberFunctionAttributes opt
function Parameters FunctionAttributes opt

IdentifierList:
Identifier
Identifier . IdentifierList
TemplateInstance
TemplateInstance . IdentifierList
Identifier [ AssignExpression ]. IdentifierList

StorageClasses:
StorageClass
StorageClass StorageClasses

StorageClass:

LinkageAttribute extern auto shared ref

AlignAttribute abstract scope __gshared
deprecated final const Property
enum override immutable nothrow
static synchronized inout pure

Initializer:
VoidInitializer
 89

NonVoidInitializer

NonVoidInitializer:
ExpInitializer :
ArrayInitializer
StructInitializer

ExpInitializer:
AssignExpression

ArrayInitializer:
[ ArrayMemberInitializations opt ]

ArrayMemberInitializations:
ArrayMemberInitialization
ArrayMemberInitialization ,
ArrayMemberInitialization , ArrayMemberInitializations

ArrayMemberInitialization:
NonVoidInitializer
AssignExpression : NonVoidInitializer

StructInitializer:
{ StructMemberInitializers opt }

StructMemberInitializers:
StructMemberInitializer
StructMemberInitializer ,
StructMemberInitializer , StructMemberInitializers

StructMemberInitializer:
NonVoidInitializer
Identifier : NonVoidInitializer

Declaration Syntax
Declaration syntax generally reads right to left:
int x; // x is an int
int* x; // x is a pointer to int
90 CHAPTER 5. DECLARATIONS

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
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
Pointers to functions are declared using the 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
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
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

Implicit Type Inference

AutoDeclaration:
StorageClasses AutoDeclarationX ;
 91

AutoDeclarationX:
Identifier TemplateParameters opt = Initializer
AutoDeclarationX , Identifier TemplateParameters opt = Initializer

If a declaration starts with a StorageClass and has a 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

The 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.
An ArrayLiteral is inferred to be a dynamic array type rather than a static array:
auto v = ["hello", "world"]; // type is string[], not string[2]

Alias Declarations
AliasDeclaration:
alias StorageClasses opt BasicType Declarators ;
alias StorageClasses opt BasicType FuncDeclarator ;
alias AliasDeclarationX ;

AliasDeclarationX:
Identifier TemplateParameters opt = StorageClasses opt Type
AliasDeclarationX , Identifier TemplateParameters opt = StorageClasses opt Type

AliasDeclarations 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;
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:
92 CHAPTER 5. DECLARATIONS

alias myint = int;

void foo(int x) { ... }

void foo(myint m) { ... } // error, multiply defined function foo
A symbol can be declared as an alias of another symbol. For example:
import string;

alias mylen = string.strlen;

...
int len = mylen("hello"); // actually calls string.strlen()
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
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;
}
Aliasing can be used to ‘import’ a symbol from an import into the current scope:
alias strlen = string.strlen;
Aliases can also ‘import’ a set of overloaded functions, that can be overloaded with functions in
the current scope:
 93

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
}
Note: Type aliases can sometimes look indistinguishable from alias declarations:
alias abc = foo.bar; // is it a type or a symbol?
The distinction is made in the semantic analysis pass.
Aliases cannot be used for expressions:
struct S { static int i; }
S s;

alias a = s.i; // illegal, s.i is an expression

alias b = S.i; // ok
b = 4; // sets S.i to 4
94 CHAPTER 5. DECLARATIONS

Extern Declarations
Variable declarations with the storage class 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.
An extern declaration can optionally be followed by an extern linkage attribute. If there is no
linkage attribute it defaults to 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)

typeof
Typeof:
typeof ( Expression )
typeof ( return )

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
}
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
}
 95

There are three special cases:

1. typeof(this) will generate the type of what this would be in a non-static member function,
even if not in a member function.
2. Analogously, typeof(super) will generate the type of what super would be in a non-static
member function.
3. 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

If the expression is a Property Function, typeof gives its return type.
struct S
{
@property int foo() { return 1; }
}
typeof(S.foo) n; // n is declared to be an int
Where Typeof is most useful is in writing generic template code.

Void Initializations
VoidInitializer:
void
96 CHAPTER 5. DECLARATIONS

Normally, variables are initialized either with an explicit Initializer or are set to the default
value for the type of the variable. If the Initializer is 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;
writeln(x); // will print garbage
}
Therefore, one should only use void initializers as a last resort when optimizing critical code.

Global and Static Initializers

The 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.

Type Qualifiers vs. Storage Classes

D draws a distinction between a type qualifer and a storage class.
A 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.
For example, the 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)
A storage class, on the other hand, does not create a new type, but describes only the type of
storage used by the variable or function being declared. For example, a member function can be
declared with the const storage class to indicate that it does not modify its implicit this argument:
struct S
{
int x;
int method() const
{
 97

//x++; // Error: this method is const and cannot modify this.x

return x; // OK: we can still read this.x
}
}
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. One example is 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.
}

// 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();
98 CHAPTER 5. DECLARATIONS

static assert(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().
}
Due to the fact that some keywords, such as const, can be used both as a type qualifier and a
storage class, it may sometimes result in ambiguous-looking code:
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() { return 1; }
}
To avoid such confusion, it is recommended that type qualifier syntax with parentheses always
be used for return types, and that function storage classes 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; }
}
99
100 CHAPTER 6. TYPES

Chapter 6

Types

Basic Data Types

Basic Data Types
Keyword Default Initializer (.init) Description
void - no type
bool false boolean value
byte 0 signed 8 bits
ubyte 0 unsigned 8 bits
short 0 signed 16 bits
ushort 0 unsigned 16 bits
int 0 signed 32 bits
uint 0 unsigned 32 bits
long 0L signed 64 bits
ulong 0L unsigned 64 bits
cent 0 signed 128 bits (reserved for future use)
ucent 0 unsigned 128 bits (reserved for future use)
float float.nan 32 bit floating point
double double.nan 64 bit floating point
real real.nan largest FP size implemented in hardware1
ifloat float.nan*1.0i imaginary float
idouble double.nan*1.0i imaginary double
ireal real.nan*1.0i imaginary real
cfloat float.nan+float.nan*1.0i a complex number of two float values
cdouble double.nan+double.nan*1.0i complex double
creal real.nan+real.nan*1.0i complex real
char 0xFF unsigned 8 bit (UTF-8 code unit)
wchar 0xFFFF unsigned 16 bit (UTF-16 code unit)
dchar 0x0000FFFF unsigned 32 bit (UTF-32 code unit)
1
Implementation Note: 80 bits for x86 CPUs or double size, whichever is larger
 101

Derived Data Types

• pointer
• array
• associative array
• function
• delegate

Strings are a special case of arrays.

User Defined Types

• alias
• enum
• struct
• union
• class

Base Types
The base type of an enum is the type it is based on:
enum E : T { ... } // T is the base type of E

Pointer Conversions
Casting pointers to non-pointers and vice versa is allowed in D, however, do not do this for any
pointers that point to data allocated by the garbage collector.

Implicit Conversions
Implicit conversions are used to automatically convert types as required.
A enum can be implicitly converted to its base type, but going the other way requires an explicit
conversion.
For example:
int i;

enum Foo { E }
Foo f;
i = f; // OK
f = i; // error
102 CHAPTER 6. TYPES

f = cast(Foo)i; // OK
f = 0; // error
f = Foo.E; // OK

Integer Promotions
Integer Promotions are conversions of the following types:

Integer Promotions
from to
bool int
byte int
ubyte int
short int
ushort int
char int
wchar int
dchar uint

If a enum has as a base type one of the types in the left column, it is converted to the type in
the right column.

Usual Arithmetic Conversions

The usual arithmetic conversions convert operands of binary operators to a common type. The
operands must already be of arithmetic types. The following rules are applied in order, looking at
the base type:

1. If either operand is real, the other operand is converted to real.

2. Else if either operand is double, the other operand is converted to double.
3. Else if either operand is float, the other operand is converted to float.
4. Else the integer promotions are done on each operand, followed by:

a) If both are the same type, no more conversions are done.

b) If both are signed or both are unsigned, the smaller type is converted to the larger.
c) If the signed type is larger than the unsigned type, the unsigned type is converted to the
signed type.
d) The signed type is converted to the unsigned type.
 103

If one or both of the operand types is an enum after undergoing the above conversions, the
result type is:

1. If the operands are the same type, the result will be the that type.
2. If one operand is an enum and the other is the base type of that enum, the result is the base
type.
3. If the two operands are different enums, the result is the closest base type common to both.
A base type being closer means there is a shorter sequence of conversions to base type to get
there from the original type.

Integer values cannot be implicitly converted to another type that cannot represent the integer
bit pattern after integral promotion. For example:
ubyte u1 = cast(byte)-1; // error, -1 cannot be represented in a ubyte
ushort u2 = cast(short)-1; // error, -1 cannot be represented in a ushort
uint u3 = cast(int)-1; // ok, -1 can be represented in a uint
ulong u4 = cast(long)-1; // ok, -1 can be represented in a ulong
Floating point types cannot be implicitly converted to integral types.
Complex floating point types cannot be implicitly converted to non-complex floating point types.
Imaginary floating point types cannot be implicitly converted to float, double, or real types.
Float, double, or real types cannot be implicitly converted to imaginary floating point types.

bool
The bool type is a 1 byte size type that can only hold the value true or false. The only operators
that can accept operands of type bool are: & | ^ &= |= ^= ! && || ?:. A bool value can be
implicitly converted to any integral type, with false becoming 0 and true becoming 1. The numeric
literals 0 and 1 can be implicitly converted to the bool values false and true, respectively. Casting
an expression to bool means testing for 0 or !=0 for arithmetic types, and null or !=null for pointers
or references.

Delegates
There are no pointers-to-members in D, but a more useful concept called delegates are supported.
Delegates are an aggregate of two pieces of data: an object reference and a pointer to a non-static
member function, or a pointer to a closure and a pointer to a nested function. The object reference
forms the this pointer when the function is called.
Delegates are declared similarly to function pointers, except that the keyword delegate takes
the place of (*), and the identifier occurs afterwards:
int function(int) fp; // fp is pointer to a function
int delegate(int) dg; // dg is a delegate to a function
104 CHAPTER 6. TYPES

The C style syntax for declaring pointers to functions is

deprecated:
int (*fp)(int); // fp is pointer to a function

A delegate is initialized analogously to function pointers:

int func(int);
fp = &func; // fp points to func

class OB
{
int member(int);
}
OB o;
dg = &o.member; // dg is a delegate to object o and
// member function member

Delegates cannot be initialized with static member functions or non-member functions.

Delegates are called analogously to function pointers:
fp(3); // call func(3)
dg(3); // call o.member(3)

The equivalent of member function pointers can be constructed using anonymous lambda func-
tions:
class C
{
int a;
int foo(int i) { return i + a; }
}

// mfp is the member function pointer

auto mfp = function(C self, int i) { return self.foo(i); };
auto c = new C(); // create an instance of C
mfp(c, 1); // and call c.foo(1)

size_t
size_t is an alias to one of the unsigned integral basic types, and represents a type that is large
enough to represent an offset into all addressible memory.
 105

ptrdiff_t
ptrdiff_t is an alias to the signed basic type the same size as size_t.
Chapter 7

Properties

Every type and expression has properties that can be queried:

Property Examples
Expression Value
int.sizeof yields 4
float.nan yields the floating point nan (Not A Number) value
(float).nan yields the floating point nan value
(3).sizeof yields 4 (because 3 is an int)
int.init default initializer for int’s
int.mangleof yields the string "i"
int.stringof yields the string "int"
(1+2).stringof yields the string "1 + 2"

Properties for All Types

Property Description
.init initializer
.sizeof size in bytes (equivalent to C’s sizeof(type))
.alignof alignment size
.mangleof string representing the ‘mangled’ representation of the type
.stringof string representing the source representation of the type

107
108 CHAPTER 7. PROPERTIES

Properties for Integral Types

Property Description
.init initializer (0)
.max maximum value
.min minimum value

Properties for Floating Point Types

Property Description
.init initializer (NaN)
.infinity infinity value
.nan NaN value
.dig number of decimal digits of precision
.epsilon smallest increment to the value 1
.mant_dig number of bits in mantissa
.max_10_exp maximum int value such that 10^max_10_exp is representable
.max_exp maximum int value such that 2^max_exp-1 is representable
.min_10_exp minimum int value such that 10^min_10_exp is representable
as a normalized value
.min_exp minimum int value such that 2^min_exp-1 is representable as
a normalized value
.max largest representable value that’s not infinity
.min_normal smallest representable normalized value that’s not 0
.re real part
.im imaginary part

Properties for Class Types

Property Description
.classinfo Information about the dynamic type of the class

.init Property
.init produces a constant expression that is the default initializer. If applied to a type, it is the
default initializer for that type. If applied to a variable or field, it is the default initializer for that
variable or field’s type. For example:
int a;
int b = 1;
typedef int t = 2;
t c;
 109

t d = cast(t)3;

int.init // is 0
a.init // is 0
b.init // is 0
t.init // is 2
c.init // is 2
d.init // is 2

struct Foo
{
int a;
int b = 7;
}

Foo.init.a // is 0
Foo.init.b // is 7
Note: .init produces a default initialized object, not default constructed. That means using
.init is sometimes incorrect.

1. If T is a nested struct, the context pointer in T.init is null.

void main()
{
int a;
struct S
{
void foo() { a = 1; } // access a variable in enclosing scope
}
S s1; // OK. S() correctly initialize its frame pointer.
S s2 = S(); // OK. same as s1
S s3 = S.init; // Bad. the frame pointer in s3 is null
s3.foo(); // Access violation
}
2. If T is a struct which has @disable this();, T.init might return a logically incorrect object.
struct S
{
int a;
@disable this();
110 CHAPTER 7. PROPERTIES

this(int n) { a = n; }
invariant { assert(a > 0); }
void check() {}
}
void main()
{
//S s1; // Error: variable s1 initializer required for type S
//S s2 = S(); // Error: constructor S.this is not callable
// because it is annotated with @disable
S s3 = S.init; // Bad. s3.a == 0, and it violates the invariant of S.
s3.check(); // Assertion failure.
}

.stringof Property
.stringof produces a constant string that is the source representation of its prefix. If applied to
a type, it is the string for that type. If applied to an expression, it is the source representation of
that expression. Semantic analysis is not done for that expression. For example:
module test;
import std.stdio;

struct Foo { }

enum Enum { RED }

typedef int myint;

void main()
{
writeln((1+2).stringof); // "1 + 2"
writeln(Foo.stringof); // "Foo"
writeln(test.Foo.stringof); // "Foo"
writeln(int.stringof); // "int"
writeln((int*[5][]).stringof); // "int*[5u][]"
writeln(Enum.RED.stringof); // "cast(enum)0"
writeln(test.myint.stringof); // "myint"
writeln((5).stringof); // "5"
}
 111

Note: Using .stringof for code generation is not recommended, as the internal representation
of a type or expression can change between different compiler versions.
Instead you should prefer to use the identifier trait, or one of the Phobos helper functions such
as fullyQualifiedName.

.sizeof Property
e.sizeof gives the size in bytes of the expression e.
When getting the size of a member, it is not necessary for there to be a this object:

struct S
{
int a;
static int foo()
{
return a.sizeof; // returns 4
}
}

void test()
{
int x = S.a.sizeof; // sets x to 4
}

.sizeof applied to a class object returns the size of the class reference, not the class instantia-
tion.

.alignof Property
.alignof gives the aligned size of an expression or type. For example, an aligned size of 1 means
that it is aligned on a byte boundary, 4 means it is aligned on a 32 bit boundary.

.classinfo Property
.classinfo provides information about the dynamic type of a class object.
It returns a reference to type object.TypeInfo_Class.
.classinfo applied to an interface gives the information for the interface, not the class it might
be an instance of.
112 CHAPTER 7. PROPERTIES

User Defined Properties

Properties are functions that can be syntactically treated as if they were fields or variables. Prop-
erties can be read from or written to. A property is read by calling a method or function with no
arguments; a property is written by calling a method or function with its argument being the value
it is set to.
A simple property would be:
struct Foo
{
@property int data() { return m_data; } // read property

@property int data(int value) { return m_data = value; } // write property

private:
int m_data;
}
Properties are marked with the @property attribute. Properties may only have zero or one
parameter, and may not be variadic. Property functions may not be overloaded with non-property
functions.
To use it:
int test()
{
Foo f;

f.data = 3; // same as f.data(3);

return f.data + 3; // same as return f.data() + 3;
}
The absence of a read method means that the property is write-only. The absence of a write
method means that the property is read-only. Multiple write methods can exist; the correct one is
selected using the usual function overloading rules.
In all the other respects, these methods are like any other methods. They can be static, have
different linkages, have their address taken, etc.
Note: A property can be the left-hand side of an op=, ++, or – operator if it returns a ref.
The built in properties .sizeof, .alignof, and .mangleof may not be declared as fields or
methods in structs, unions, classes or enums.
If a .property is applied to a user-defined property, the .property is applied to the result of the
function call.
void main()
 113

{
@property int[] delegate() bar1 = { return [1, 2]; };
auto x1 = bar1.ptr; // points to array data

struct Foo { int* ptr; }

@property Foo delegate() bar2 = { return Foo(); };
auto x2 = bar2.ptr; // gets value of Foo.ptr
}
Chapter 8

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

115
116 CHAPTER 8. ATTRIBUTES

ref

Property:
@ PropertyIdentifier
UserDefinedAttribute

PropertyIdentifier:
property
safe
trusted
system
disable
nogc

DeclarationBlock:
DeclDef
{ DeclDefs opt }

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 )
 117

LinkageType:
C
C++
D
Windows
Pascal
System
Objective-C

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++. Objective-C offers
limited compatibility with Objective-C, see the Interfacing to Objective-C documentation for more
information. 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.
118 CHAPTER 8. ATTRIBUTES

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.
 119

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
120 CHAPTER 8. ATTRIBUTES

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
 121

package ( IdentifierList )
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.
Package may have an optional parameter - dot-separated identifier list which is resolved as the
qualified package name. If this optional parameter is present, the symbol is considered to be owned
by that package instead of the default innermost one. This only applies to access checks and does
not affect the module/package this symbol belongs to.
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
122 CHAPTER 8. ATTRIBUTES

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.
 123

__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.
124 CHAPTER 8. ATTRIBUTES

@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.
 125

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
126 CHAPTER 8. ATTRIBUTES

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.’
 127

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 ( ArgumentList opt )
@ TemplateInstance
@ TemplateInstance ( ArgumentList opt )

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:
128 CHAPTER 8. ATTRIBUTES

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.
Chapter 9

Pragmas

Pragma:
pragma ( Identifier )
pragma ( Identifier , ArgumentList )

Pragmas are a way to pass special information to the compiler and to add vendor specific
extensions to D. Pragmas can be used by themselves terminated with a ‘;’, they can influence a
statement, a block of statements, a declaration, or a block of declarations.
Pragmas can appear as either declarations, Pragma DeclarationBlock, or as statements, Prag-
maStatement.
pragma(ident); // just by itself

pragma(ident) declaration; // influence one declaration

pragma(ident): // influence subsequent declarations

declaration;
declaration;

pragma(ident) // influence block of declarations

{
declaration;
declaration;
}

pragma(ident) statement; // influence one statement

129
130 CHAPTER 9. PRAGMAS

pragma(ident) // influence block of statements

{
statement;
statement;
}
The kind of pragma it is determined by the Identifier. ExpressionList is a comma-separated
list of AssignExpressions. The AssignExpressions must be parsable as expressions, but what they
mean semantically is up to the individual pragma semantics.

Predefined Pragmas
All implementations must support these, even if by just ignoring them:

• pragma inline
• pragma lib
• pragma mangle
• pragma msg
• pragma startaddress

inline Affects whether functions are inlined or not. If at the declaration level, it affects the
functions declared in the block it controls. If inside a function, it affects the function it is
enclosed by. If there are multiple pragma inlines in a function, the lexically last one takes
effect.
It takes three forms:

1. pragma(inline)
Sets the behavior to match the default behavior set by the compiler switch -inline.
2. pragma(inline, false)
Functions are never inlined.
3. pragma(inline, true)
If a function cannot be inlined with the -inline switch, an error message is issued. This is
expected to be improved in the future to causing functions to always be inlined regardless
of compiler switch settings. Whether a compiler can inline a particular function or not
is implementation defined.
 131

pragma(inline):
int foo(int x) // foo() is never inlined
{
pragma(inline, true);
++x;
pragma(inline, false); // supercedes the others
return x + 3;
}

lib Inserts a directive in the object file to link in the library specified by the AssignExpression.
The AssignExpressions must be a string literal:
pragma(lib, "foo.lib");

mangle Overrides the default mangling for a symbol. It’s only effective when the symbol is a
function declaration or a variable declaration. For example this allows linking to a symbol
which is a D keyword, which would normally be disallowed as a symbol name:
pragma(mangle, "body")
extern(C) void body_func();

msg Constructs a message from the arguments and prints to the standard error stream while
compiling:
pragma(msg, "compiling...", 1, 1.0);

startaddress Puts a directive into the object file saying that the function specified in the first
argument will be the start address for the program:
void foo() { ... }
pragma(startaddress, foo);

This is not normally used for application level programming, but is for specialized systems
work. For applications code, the start address is taken care of by the runtime library.

Vendor Specific Pragmas

Vendor specific pragma Identifier s can be defined if they are prefixed by the vendor’s trademarked
name, in a similar manner to version identifiers:
pragma(DigitalMars_funky_extension) { ... }
Compilers must diagnose an error for unrecognized Pragmas, even if they are vendor specific
ones. This implies that vendor specific pragmas should be wrapped in version statements:
132 CHAPTER 9. PRAGMAS

version (DigitalMars)
{
pragma(DigitalMars_funky_extension)
{ ... }
}
Chapter 10

Expressions

C and C++ programmers will find the D expressions very familiar, with a few interesting additions.
Expressions are used to compute values with a resulting type. These values can then be assigned,
tested, or ignored. Expressions can also have side effects.

Order Of Evaluation
Binary expressions and function arguments are evaluated in strictly left-to-right order. This is
similar to Java but different to C and C++, where the evaluation order is unspecified. Thus, the
following code is valid and well defined.
import std.conv;
int i = 0;
(i = 2) = ++i * i++ + i;
assert(i == 13); // left to right evaluation of side effects
assert(text(++i, ++i) == "1415"); // left to right evaluation of arguments
But even though the order of evaluation is well defined, writing code that depends on it is rarely
recommended. Note that dmd currently does not comply with left to right evaluation of
function arguments and AssignExpression.

Expressions
Expression:
CommaExpression

CommaExpression:
AssignExpression
AssignExpression , CommaExpression

133
134 CHAPTER 10. EXPRESSIONS

The left operand of the , is evaluated, then the right operand is evaluated. The type of the
expression is the type of the right operand, and the result is the result of the right operand.

Assign Expressions
AssignExpression:
ConditionalExpression
ConditionalExpression = AssignExpression
ConditionalExpression += AssignExpression
ConditionalExpression -= AssignExpression
ConditionalExpression *= AssignExpression
ConditionalExpression /= AssignExpression
ConditionalExpression %= AssignExpression
ConditionalExpression &= AssignExpression
ConditionalExpression =| AssignExpression
ConditionalExpression ^= AssignExpression
ConditionalExpression ~= AssignExpression
ConditionalExpression <<= AssignExpression
ConditionalExpression >>= AssignExpression
ConditionalExpression >>>= AssignExpression
ConditionalExpression ^^= AssignExpression

The right operand is implicitly converted to the type of the left operand, and assigned to it.
The result type is the type of the left operand, and the result value is the value of the left operand
after the assignment.
The left operand must be an lvalue.

Assignment Operator Expressions

Assignment operator expressions, such as:
a op= b
are semantically equivalent to:
a = cast(typeof(a))(a op b)
except that:

• operand a is only evaluated once

 135

• overloading op uses a different function than overloading op= does

• the left operand of >>>= does not undergo integral promotions before shifting

Conditional Expressions
ConditionalExpression:
OrOrExpression
OrOrExpression ? Expression : ConditionalExpression

The first expression is converted to bool, and is evaluated.

If it is true, then the second expression is evaluated, and its result is the result of the conditional
expression.
If it is false, then the third expression is evaluated, and its result is the result of the conditional
expression.
If either the second or third expressions are of type void, then the resulting type is void.
Otherwise, the second and third expressions are implicitly converted to a common type which
becomes the result type of the conditional expression.

OrOr Expressions
OrOrExpression:
AndAndExpression
OrOrExpression || AndAndExpression

The result type of an OrOrExpression is bool, unless the right operand has type void, when
the result is type void.
The OrOrExpression evaluates its left operand.
If the left operand, converted to type bool, evaluates to true, then the right operand is not
evaluated. If the result type of the OrOrExpression is bool then the result of the expression is
true.
If the left operand is false, then the right operand is evaluated. If the result type of the
OrOrExpression is bool then the result of the expression is the right operand converted to type
bool.

AndAnd Expressions
AndAndExpression:
OrExpression
AndAndExpression && OrExpression
136 CHAPTER 10. EXPRESSIONS

The result type of an AndAndExpression is bool, unless the right operand has type void, when
the result is type void.
The AndAndExpression evaluates its left operand.
If the left operand, converted to type bool, evaluates to false, then the right operand is not
evaluated. If the result type of the AndAndExpression is bool then the result of the expression is
false.
If the left operand is true, then the right operand is evaluated. If the result type of the
AndAndExpression is bool then the result of the expression is the right operand converted to type
bool.

Bitwise Expressions
Bit wise expressions perform a bitwise operation on their operands. Their operands must be integral
types. First, the default integral promotions are done. Then, the bitwise operation is done.

Or Expressions
OrExpression:
XorExpression
OrExpression | XorExpression

The operands are OR’d together.

Xor Expressions
XorExpression:
AndExpression
XorExpression ^ AndExpression

The operands are XOR’d together.

And Expressions
AndExpression:
CmpExpression
AndExpression & CmpExpression

The operands are AND’d together.

 137

Compare Expressions
CmpExpression:
ShiftExpression
EqualExpression
IdentityExpression
RelExpression
InExpression

Equality Expressions
EqualExpression:
ShiftExpression == ShiftExpression
ShiftExpression != ShiftExpression

Equality expressions compare the two operands for equality (==) or inequality (!=). The type
of the result is bool. The operands go through the usual conversions to bring them to a common
type before comparison.
If they are integral values or pointers, equality is defined as the bit pattern of the type matches
exactly.
Equality for floating point types is more complicated. -0 and +0 compare as equal. If either or
both operands are NAN, then both the == returns false and != returns true. Otherwise, the bit
patterns are compared for equality.
For complex numbers, equality is defined as equivalent to:
x.re == y.re && x.im == y.im
and inequality is defined as equivalent to:
x.re != y.re || x.im != y.im
Equality for struct objects means the logical product of all equality results of the corresponding
object fields. If all struct fields use bitwise equality, the whole struct equality could be optimized
to one memory comparison operation (the existence of alignment holes in the objects is accounted
for, usually by setting them all to 0 upon initialization).
For class and struct objects, the expression (a == b) is rewritten as a.opEquals(b), and (a ⤦
Ç != b) is rewritten as !a.opEquals(b).
For class objects, the == and != operators compare the contents of the objects. Therefore,
comparing against null is invalid, as null has no contents. Use the is and !is operators instead.
class C;
C c;
138 CHAPTER 10. EXPRESSIONS

if (c == null) // error
...
if (c is null) // ok
...
For static and dynamic arrays, equality is defined as the lengths of the arrays matching, and all
the elements are equal.

Identity Expressions
IdentityExpression:
ShiftExpression is ShiftExpression
ShiftExpression !is ShiftExpression

The is compares for identity. To compare for not identity, use e1 !is e2. The type of the
result is bool. The operands go through the usual conversions to bring them to a common type
before comparison.
For class objects, identity is defined as the object references are for the same object. Null class
objects can be compared with is.
For struct objects, identity is defined as the bits in the struct being identical.
For static and dynamic arrays, identity is defined as referring to the same array elements and
the same number of elements.
For other operand types, identity is defined as being the same as equality.
The identity operator is cannot be overloaded.

Relational Expressions
RelExpression:
ShiftExpression < ShiftExpression
ShiftExpression <= ShiftExpression
ShiftExpression > ShiftExpression
ShiftExpression >= ShiftExpression
ShiftExpression !<>= ShiftExpression
ShiftExpression !<> ShiftExpression
ShiftExpression <> ShiftExpression
ShiftExpression <>= ShiftExpression
ShiftExpression !> ShiftExpression
ShiftExpression !>= ShiftExpression
ShiftExpression !< ShiftExpression
ShiftExpression !<= ShiftExpression
 139

First, the integral promotions are done on the operands. The result type of a relational expres-
sion is bool.
For class objects, the result of Object.opCmp() forms the left operand, and 0 forms the right
operand. The result of the relational expression (o1 op o2) is:

(o1.opCmp(o2) op 0)

It is an error to compare objects if one is null.

For static and dynamic arrays, the result of the relational op is the result of the operator applied
to the first non-equal element of the array. If two arrays compare equal, but are of different lengths,
the shorter array compares as "less" than the longer array.

Integer comparisons

Integer comparisons happen when both operands are integral types.

Integer comparison operators

Operator Relation
< less
> greater
<= less or equal
>= greater or equal
== equal
!= not equal

It is an error to have one operand be signed and the other unsigned for a <, <=, > or >= expression.
Use casts to make both operands signed or both operands unsigned.

Floating point comparisons

If one or both operands are floating point, then a floating point comparison is performed.
Useful floating point operations must take into account NAN values. In particular, a relational
operator can have NAN operands. The result of a relational operation on float values is less, greater,
equal, or unordered (unordered means either or both of the operands is a NAN). That means there
are 14 possible comparison conditions to test for:
140 CHAPTER 10. EXPRESSIONS

Floating point comparison operators

Operator Greater Less Equal Unordered Exception Relation
== F F T F no equal
!= T T F T no unordered, less, or greater
> T F F F yes greater
>= T F T F yes greater or equal
< F T F F yes less
<= F T T F yes less or equal
!<>= F F F T no unordered
<> T T F F yes less or greater
<>= T T T F yes less, equal, or greater
!<= T F F T no unordered or greater
!< T F T T no unordered, greater, or equal
!>= F T F T no unordered or less
!> F T T T no unordered, less, or equal
!<> F F T T no unordered or equal

Notes:

1. For floating point comparison operators, (a !op b) is not the same as !(a op b).
2. "Unordered" means one or both of the operands is a NAN.
3. "Exception" means the Invalid Exception is raised if one of the operands is a NAN. It does
not mean an exception is thrown. The Invalid Exception can be checked using the functions
in core.stdc.fenv.

Class comparisons
For class objects, the relational operators compare the contents of the objects. Therefore, comparing
against null is invalid, as null has no contents.
class C;
C c;
if (c < null) // error
...

In Expressions
InExpression:
ShiftExpression in ShiftExpression
ShiftExpression !in ShiftExpression
 141

An associative array can be tested to see if an element is in the array:

int foo[char[]];
...
if ("hello" in foo)
...
The in expression has the same precedence as the relational expressions <, <=, etc. The return
value of the InExpression is null if the element is not in the array; if it is in the array it is a pointer
to the element.
The !in expression is the logical negation of the in operation.

Shift Expressions
ShiftExpression:
AddExpression
ShiftExpression << AddExpression
ShiftExpression >> AddExpression
ShiftExpression >>> AddExpression

The operands must be integral types, and undergo the usual integral promotions. The result
type is the type of the left operand after the promotions. The result value is the result of shifting
the bits by the right operand’s value.
<< is a left shift. >> is a signed right shift. >>> is an unsigned right shift.
It’s illegal to shift by the same or more bits than the size of the quantity being shifted:
int c;
auto x = c << 33; // error

Add Expressions
AddExpression:
MulExpression
AddExpression + MulExpression
AddExpression - MulExpression
CatExpression
142 CHAPTER 10. EXPRESSIONS

If the operands are of integral types, they undergo integral promotions, and then are brought
to a common type using the usual arithmetic conversions.
If either operand is a floating point type, the other is implicitly converted to floating point and
they are brought to a common type via the usual arithmetic conversions.
If the operator is + or -, and the first operand is a pointer, and the second is an integral type,
the resulting type is the type of the first operand, and the resulting value is the pointer plus (or
minus) the second operand multiplied by the size of the type pointed to by the first operand.
If the second operand is a pointer, and the first is an integral type, and the operator is +, the
operands are reversed and the pointer arithmetic just described is applied.
If both operands are pointers, and the operator is +, then it is illegal. For -, the pointers are
subtracted and the result is divided by the size of the type pointed to by the operands. It is an
error if the pointers point to different types.
If both operands are of integral types and an overflow or underflow occurs in the computation,
wrapping will happen. That is, uint.max + 1 == uint.min and uint.min - 1 == uint.max.
Add expressions for floating point operands are not associative.

Cat Expressions
CatExpression:
AddExpression ~ MulExpression

A CatExpression concatenates arrays, producing a dynmaic array with the result. The arrays
must be arrays of the same element type. If one operand is an array and the other is of that
array’s element type, that element is converted to an array of length 1 of that element, and then
the concatenation is performed.

Mul Expressions
MulExpression:
UnaryExpression
MulExpression * UnaryExpression
MulExpression / UnaryExpression
MulExpression % UnaryExpression

The operands must be arithmetic types. They undergo integral promotions, and then are
brought to a common type using the usual arithmetic conversions.
For integral operands, the *, /, and % correspond to multiply, divide, and modulus operations.
For multiply, overflows are ignored and simply chopped to fit into the integral type.
 143

For integral operands of the / and % operators, the quotient rounds towards zero and the
remainder has the same sign as the dividend. If the divisor is zero, an Exception is thrown.
For floating point operands, the * and / operations correspond to the IEEE 754 floating point
equivalents. the IEEE 754 remainder. For example, 15.0 for IEEE 754, remainder(15.0,10.0) ==
-5.0.
Mul expressions for floating point operands are not associative.

Unary Expressions
UnaryExpression:
& UnaryExpression
++ UnaryExpression
-- UnaryExpression
* UnaryExpression
- UnaryExpression
+ UnaryExpression
! UnaryExpression
ComplementExpression
( Type ) . Identifier
( Type ) . TemplateInstance
DeleteExpression
CastExpression
PowExpression

Complement Expressions
ComplementExpression:
~ UnaryExpression

ComplementExpressions work on integral types (except bool). All the bits in the value are
complemented.
Note: unlike in C and C++, the usual integral promotions are not performed prior to the
complement operation.

New Expressions
NewExpression:
new AllocatorArguments opt Type
NewExpressionWithArgs
144 CHAPTER 10. EXPRESSIONS

NewExpressionWithArgs:
new AllocatorArguments opt Type [ AssignExpression ]
new AllocatorArguments opt Type ( ArgumentList opt )
NewAnonClassExpression

AllocatorArguments:
( ArgumentList opt )

ArgumentList:
AssignExpression
AssignExpression ,
AssignExpression , ArgumentList

NewExpressions are used to allocate memory on the garbage collected heap (default) or using a
class or struct specific allocator.
To allocate multidimensional arrays, the declaration reads in the same order as the prefix array
declaration order.
char[][] foo; // dynamic array of strings
...
foo = new char[][30]; // allocate array of 30 strings
The above allocation can also be written as:
foo = new char[][](30); // allocate array of 30 strings
To allocate the nested arrays, multiple arguments can be used:
int[][][] bar;
...
bar = new int[][][](5, 20, 30);
Which is equivalent to:
bar = new int[][][5];
foreach (ref a; bar)
{
a = new int[][20];
foreach (ref b; a)
{
b = new int[30];
}
}
 145

If there is a new ( ArgumentList ), then those arguments are passed to the class or struct
specific allocator function after the size argument.
If a NewExpression is used as an initializer for a function local variable with scope storage class,
and the ArgumentList to new is empty, then the instance is allocated on the stack rather than the
heap or using the class specific allocator.

Delete Expressions
DeleteExpression:
delete UnaryExpression

If the UnaryExpression is a class object reference, and there is a destructor for that class, the
destructor is called for that object instance.
Next, if the UnaryExpression is a class object reference, or a pointer to a struct instance, and
the class or struct has overloaded operator delete, then that operator delete is called for that class
object instance or struct instance.
Otherwise, the garbage collector is called to immediately free the memory allocated for the class
instance or struct instance. If the garbage collector was not used to allocate the memory for the
instance, undefined behavior will result.
If the UnaryExpression is a pointer or a dynamic array, the garbage collector is called to imme-
diately release the memory. If the garbage collector was not used to allocate the memory for the
instance, undefined behavior will result.
The pointer, dynamic array, or reference is set to null after the delete is performed. Any
attempt to reference the data after the deletion via another reference to it will result in undefined
behavior.
If UnaryExpression is a variable allocated on the stack, the class destructor (if any) is called for
that instance. Neither the garbage collector nor any class deallocator is called.

Cast Expressions
CastExpression:
cast ( Type ) UnaryExpression
cast ( TypeCtors opt ) UnaryExpression

A CastExpression converts the UnaryExpression to Type.

cast(foo) -p; // cast (-p) to type foo
(foo) - p; // subtract p from foo
146 CHAPTER 10. EXPRESSIONS

Any casting of a class reference to a derived class reference is done with a runtime check to make
sure it really is a downcast. null is the result if it isn’t.
Note: This is equivalent to the behavior of the dynamic_cast operator in C++.
class A { ... }
class B : A { ... }

void test(A a, B b)
{
B bx = a; // error, need cast
B bx = cast(B) a; // bx is null if a is not a B
A ax = b; // no cast needed
A ax = cast(A) b; // no runtime check needed for upcast
}
In order to determine if an object o is an instance of a class B use a cast:
if (cast(B) o)
{
// o is an instance of B
}
else
{
// o is not an instance of B
}
Casting a pointer type to and from a class type is done as a type paint (i.e. a reinterpret cast).
Casting a dynamic array to another dynamic array is done only if the array lengths multiplied
by the element sizes match. The cast is done as a type paint, with the array length adjusted to
match any change in element size. If there’s not a match, a runtime error is generated.
import std.stdio;

int main()
{
byte[] a = [1,2,3];
auto b = cast(int[])a; // runtime array cast misalignment

int[] c = [1, 2, 3];

auto d = cast(byte[])c; // ok
// prints:
// [1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0]
writeln(d);
 147

return 0;
}
Casting a floating point literal from one type to another changes its type, but internally it is
retained at full precision for the purposes of constant folding.
void test()
{
real a = 3.40483L;
real b;
b = 3.40483; // literal is not truncated to double precision
assert(a == b);
assert(a == 3.40483);
assert(a == 3.40483L);
assert(a == 3.40483F);
double d = 3.40483; // truncate literal when assigned to variable
assert(d != a); // so it is no longer the same
const double x = 3.40483; // assignment to const is not
assert(x == a); // truncated if the initializer is visible
}
Casting a value v to a struct S, when value is not a struct of the same type, is equivalent to:
S(v)
Casting to a CastQual replaces the qualifiers to the type of the UnaryExpression.
shared int x;
assert(is(typeof(cast(const)x) == const int));
Casting with no Type or CastQual removes any top level const, immutable, shared or inout
type modifiers from the type of the UnaryExpression.
shared int x;
assert(is(typeof(cast()x) == int));
Casting an expression to void type is allowed to mark that the result is unused. On Expres-
sionStatement, it could be used properly to avoid "has no effect" error.
void foo(lazy void exp) {}
void main()
{
foo(10); // NG - has no effect in expression ’10’
foo(cast(void)10); // OK
}
148 CHAPTER 10. EXPRESSIONS

Pow Expressions
PowExpression:
PostfixExpression
PostfixExpression ^^ UnaryExpression

PowExpression raises its left operand to the power of its right operand.

Postfix Expressions
PostfixExpression:
PrimaryExpression
PostfixExpression . Identifier
PostfixExpression . TemplateInstance
PostfixExpression . NewExpression
PostfixExpression ++
PostfixExpression --
PostfixExpression ( ArgumentList opt )
TypeCtors opt BasicType ( ArgumentList opt )
IndexExpression
SliceExpression

Index Expressions
IndexExpression:
PostfixExpression [ ArgumentList ]

PostfixExpression is evaluated.
If PostfixExpression is an expression of type static array or dynamic array, the symbol $ is set
to be the the number of elements in the array.
If PostfixExpression is an ExpressionTuple, the symbol $ is set to be the the number of elements
in the tuple.
A new declaration scope is created for the evaluation of the ArgumentList and $ appears in that
scope only.
If PostfixExpression is an ExpressionTuple, then the ArgumentList must consist of only one
argument, and that must be statically evaluatable to an integral constant. That integral constant n
then selects the nth expression in the ExpressionTuple, which is the result of the IndexExpression.
It is an error if n is out of bounds of the ExpressionTuple.
 149

Slice Expressions
SliceExpression:
PostfixExpression [ ]
PostfixExpression [ AssignExpression .. AssignExpression ]

PostfixExpression is evaluated. if PostfixExpression is an expression of type static array or

dynamic array, the special variable $ is declared and set to be the length of the array. A new
declaration scope is created for the evaluation of the AssignExpression..AssignExpression and $
appears in that scope only.
The first AssignExpression is taken to be the inclusive lower bound of the slice, and the second
AssignExpression is the exclusive upper bound. The result of the expression is a slice of the
PostfixExpression array.
If the [ ] form is used, the slice is of the entire array.
The type of the slice is a dynamic array of the element type of the PostfixExpression.
A SliceExpression is not a modifiable lvalue.
If the slice bounds can be known at compile time, the slice expression is implicitly convertible
to an lvalue of static array. For example:
arr[a .. b] // typed T[]
If both a and b are integers (may be constant-folded), the slice expression can be convered to a
static array type T[b - a].
void foo(int[2] a)
{
assert(a == [2, 3]);
}
void bar(ref int[2] a)
{
assert(a == [2, 3]);
a[0] = 4;
a[1] = 5;
assert(a == [4, 5]);
}
void baz(int[3] a) {}

void main()
{
int[] arr = [1, 2, 3];
150 CHAPTER 10. EXPRESSIONS

foo(arr[1 .. 3]);
assert(arr == [1, 2, 3]);

bar(arr[1 .. 3]);
assert(arr == [1, 4, 5]);

//baz(arr[1 .. 3]); // cannot match length

}
Following forms of slice expression can be convertible to a static array type:

eAn expression that contains no side effects.

a, bIntegers (that may be constant-folded).

Form The length calculated at compile time

arr[] The compile time length of arr if it’s known.
arr[a .. b] b - a
arr[\textit{e}-a .. \textit{e}] a
arr[\textit{e} .. \textit{e}+b] b
arr[\textit{e}-a .. \textit{e}+b] a + b
arr[\textit{e}+a .. \textit{e}+b] b - a if a <= b
arr[\textit{e}-a .. \textit{e}-b] a - b if a >= b
If PostfixExpression is an ExpressionTuple, then the result of the slice is a new ExpressionTuple
formed from the upper and lower bounds, which must statically evaluate to integral constants. It
is an error if those bounds are out of range.

Primary Expressions
PrimaryExpression:
Identifier
. Identifier
TemplateInstance
. TemplateInstance
this
super
null
true
false
$
IntegerLiteral
 151

FloatLiteral
CharacterLiteral
StringLiterals
ArrayLiteral
AssocArrayLiteral
FunctionLiteral
AssertExpression
MixinExpression
ImportExpression
NewExpressionWithArgs
BasicTypeX . Identifier
BasicTypeX ( ArgumentList opt )
TypeCtor ( Type ) . Identifier
TypeCtor ( Type ) ( ArgumentList opt )
Typeof
TypeidExpression
IsExpression
( Expression )
TraitsExpression
SpecialKeyword

.Identifier
Identifier is looked up at module scope, rather than the current lexically nested scope.

this
Within a non-static member function, this resolves to a reference to the object for which the
function was called. If the object is an instance of a struct, this will be a pointer to that instance.
If a member function is called with an explicit reference to typeof(this), a non-virtual call is
made:
class A
{
char get() { return ’A’; }

char foo() { return typeof(this).get(); }

char bar() { return this.get(); }
}
152 CHAPTER 10. EXPRESSIONS

class B : A
{
override char get() { return ’B’; }
}

void main()
{
B b = new B();

assert(b.foo() == ’A’);
assert(b.bar() == ’B’);
}
Assignment to this is not allowed.

super
super is identical to this, except that it is cast to this’s base class. It is an error if there is no
base class. It is an error to use super within a struct member function. (Only class Object has no
base class.) If a member function is called with an explicit reference to super, a non-virtual call is
made.
Assignment to super is not allowed.

null
null represents the null value for pointers, pointers to functions, delegates, dynamic arrays, asso-
ciative arrays, and class objects. If it has not already been cast to a type, it is given the singular
type typeof(null) and it is an exact conversion to convert it to the null value for pointers, pointers
to functions, delegates, etc. After it is cast to a type, such conversions are implicit, but no longer
exact.

true, false
These are of type bool and when cast to another integral type become the values 1 and 0, respec-
tively.

Character Literals
Character literals are single characters and resolve to one of type char, wchar, or dchar. If the
literal is a \u escape sequence, it resolves to type wchar. If the literal is a \U escape sequence, it
resolves to type dchar. Otherwise, it resolves to the type with the smallest size it will fit into.
 153

String Literals
StringLiterals:
StringLiteral
StringLiterals StringLiteral

String literals can implicitly convert to any of the following types, they have equal weight:
immutable(char)*
immutable(wchar)*
immutable(dchar)*
immutable(char)[]
immutable(wchar)[]
immutable(dchar)[]
By default, a string literal is typed as a dynamic array, but the element count is known at
compile time. So all string literals can be implicitly convered to static array types.
void foo(char[2] a)
{
assert(a == "bc");
}
void bar(ref const char[2] a)
{
assert(a == "bc");
}
void baz(const char[3] a) {}

void main()
{
string str = "abc";
foo(str[1 .. 3]);
bar(str[1 .. 3]);
//baz(str[1 .. 3]); // cannot match length
}
String literals have a 0 appended to them, which makes them easy to pass to C or C++ functions
expecting a const char* string. The 0 is not included in the .length property of the string literal.

Array Literals
ArrayLiteral:
[ ArgumentList opt ]
154 CHAPTER 10. EXPRESSIONS

Array literals are a comma-separated list of AssignExpressions between square brackets [ and ].
The AssignExpressions form the elements of a dynamic array, the length of the array is the number
of elements. The common type of the all elements is taken to be the type of the array element, and
all elements are implicitly converted to that type.
auto a1 = [1,2,3]; // type is int[], with elements 1, 2 and 3
auto a2 = [1u,2,3]; // type is uint[], with elements 1u, 2u, and 3u
By default, an array literal is typed as a dynamic array, but the element count is known at
compile time. So all array literals can be implicitly convered to static array types.
void foo(long[2] a)
{
assert(a == [2, 3]);
}
void bar(ref long[2] a)
{
assert(a == [2, 3]);
a[0] = 4;
a[1] = 5;
assert(a == [4, 5]);
}
void baz(const char[3] a) {}

void main()
{
long[] arr = [1, 2, 3];

foo(arr[1 .. 3]);
assert(arr == [1, 2, 3]);

bar(arr[1 .. 3]);
assert(arr == [1, 4, 5]);

//baz(arr[1 .. 3]); // cannot match length

}
If any of the arguments in the ArgumentList are an ExpressionTuple, then the elements of the
ExpressionTuple are inserted as arguments in place of the tuple.
Array literals are allocated on the memory managed heap. Thus, they can be returned safely
from functions:
 155

int[] foo()
{
return [1, 2, 3];
}
When array literals are cast to another array type, each element of the array is cast to the new
element type. When arrays that are not literals are cast, the array is reinterpreted as the new type,
and the length is recomputed:
import std.stdio;

void main()
{
// cast array literal
const short[] ct = cast(short[]) [cast(byte)1, 1];
// this is equivalent with:
// const short[] ct = [cast(short)1, cast(short)1];
writeln(ct); // writes [1, 1]

// cast other array expression

// --> normal behavior of CastExpression
byte[] arr = [cast(byte)1, cast(byte)1];
short[] rt = cast(short[]) arr;
writeln(rt); // writes [257]
}
In other words, casting literal expression will change the literal type.

Associative Array Literals

AssocArrayLiteral:
[ KeyValuePairs ]

KeyValuePairs:
KeyValuePair
KeyValuePair , KeyValuePairs

KeyValuePair:
KeyExpression : ValueExpression

KeyExpression:
AssignExpression
156 CHAPTER 10. EXPRESSIONS

ValueExpression:
AssignExpression

Associative array literals are a comma-separated list of key:value pairs between square brackets
[ and ]. The list cannot be empty. The common type of the all keys is taken to be the key type
of the associative array, and all keys are implicitly converted to that type. The common type of
the all values is taken to be the value type of the associative array, and all values are implicitly
converted to that type. An AssocArrayLiteral cannot be used to statically initialize anything.
[21u:"he", 38:"ho", 2:"hi"]; // type is string[uint],
// with keys 21u, 38u and 2u
// and values "he", "ho", and "hi"
If any of the keys or values in the KeyValuePairs are an ExpressionTuple, then the elements of
the ExpressionTuple are inserted as arguments in place of the tuple.

Function Literals
FunctionLiteral:
function Type opt ParameterAttributes opt FunctionLiteralBody
delegate Type opt ParameterMemberAttributes opt FunctionLiteralBody
ParameterMemberAttributes FunctionLiteralBody
FunctionLiteralBody
Lambda

ParameterAttributes:
Parameters FunctionAttributes opt

ParameterMemberAttributes:
Parameters MemberFunctionAttributes opt

FunctionLiteralBody:
BlockStatement
FunctionContracts opt BodyStatement

FunctionLiteral s enable embedding anonymous functions and anonymous delegates directly into
expressions. Type is the return type of the function or delegate, if omitted it is inferred from
any ReturnStatements in the FunctionLiteralBody. ( ArgumentList ) forms the arguments to the
function. If omitted it defaults to the empty argument list ( ). The type of a function literal is
 157

pointer to function or pointer to delegate. If the keywords function or delegate are omitted, it is
inferred from whether FunctionLiteralBody is actually accessing to the outer context.
For example:
int function(char c) fp; // declare pointer to a function

void test()
{
static int foo(char c) { return 6; }

fp = &foo;
}
is exactly equivalent to:
int function(char c) fp;

void test()
{
fp = function int(char c) { return 6;} ;
}
And:
int abc(int delegate(int i));

void test()
{
int b = 3;
int foo(int c) { return 6 + b; }

abc(&foo);
}
is exactly equivalent to:
int abc(int delegate(int i));

void test()
{
int b = 3;

abc( delegate int(int c) { return 6 + b; } );

}
158 CHAPTER 10. EXPRESSIONS

and the following where the return type int and function/delegate are inferred:
int abc(int delegate(int i));
int def(int function(int s));

void test()
{
int b = 3;

abc( (int c) { return 6 + b; } ); // inferred to delegate

def( (int c) { return c * 2; } ); // inferred to function
//def( (int c) { return c * b; } ); // error!
// Because the FunctionLiteralBody accesses b, then the function literal type
// is inferred to delegate. But def cannot receive delegate.
}
If the type of a function literal can be uniquely determined from its context, the parameter type
inference is possible.
void foo(int function(int) fp);

void test()
{
int function(int) fp = (n) { return n * 2; };
// The type of parameter n is inferred to int.

foo((n) { return n * 2; });

// The type of parameter n is inferred to int.
}
Anonymous delegates can behave like arbitrary statement literals. For example, here an arbi-
trary statement is executed by a loop:
double test()
{
double d = 7.6;
float f = 2.3;

void loop(int k, int j, void delegate() statement)

{
for (int i = k; i < j; i++)
{
statement();
 159

}
}

loop(5, 100, { d += 1; });

loop(3, 10, { f += 3; });

return d + f;
}
When comparing with nested functions, the function form is analogous to static or non-nested
functions, and the delegate form is analogous to non-static nested functions. In other words, a
delegate literal can access stack variables in its enclosing function, a function literal cannot.

Lambdas
Lambda:
function Type opt ParameterAttributes => AssignExpression
delegate Type opt ParameterMemberAttributes => AssignExpression
ParameterMemberAttributes => AssignExpression
Identifier => AssignExpression

Lambdas are a shorthand syntax for FunctionLiteral s.

1. Just one Identifier is rewritten to Parameters:

( Identifier )
2. The following part => AssignExpression is rewritten to FunctionLiteralBody:
{ return AssignExpression ; }

Example usage:
import std.stdio;

void main()
{
auto i = 3;
auto twice = function (int x) => x * 2;
auto square = delegate (int x) => x * x;

auto n = 5;
auto mul_n = (int x) => x * n;
160 CHAPTER 10. EXPRESSIONS

writeln(twice(i)); // prints 6
writeln(square(i)); // prints 9
writeln(mul_n(i)); // prints 15
}

Uniform construction syntax for built-in scalar types

The implicit conversions of built-in scalar types can be explicitly represented by using function call
syntax. For example:
auto a = short(1); // implicitly convert an integer literal ’1’ to short
auto b = double(a); // implicitly convert a short variable ’a’ to double
auto c = byte(128); // error, 128 cannot be represented in a byte
If the argument is omitted, it means default construction of the scalar type:
auto a = ushort(); // same as: ushort.init
auto b = wchar(); // same as: wchar.init
auto c = creal(); // same as: creal.init

Assert Expressions
AssertExpression:
assert ( AssignExpression )
assert ( AssignExpression , AssignExpression )

The assert expression is used to declare conditions that the programmer asserts must hold at
that point in the program if the program logic has been correctly implemented. It can be used both
as a debugging tool and as a way of communicating to the compiler facts about the code that it
may employ to produce more efficient code.
Programs for which AssignExpression is false are invalid. Subsequent to such a false result, the
program is in an invalid, non-recoverable state.
As a debugging tool, the compiler may insert checks to verify that the condition indeed holds
by evaluating AssignExpression at runtime. If it evaluates to a non-null class reference, the class
invariant is run. Otherwise, if it evaluates to a non-null pointer to a struct, the struct invariant
is run. Otherwise, if the result is false, an AssertError is thrown. If the result is true, then no
exception is thrown. In this way, if a bug in the code causes the assertion to fail, execution is
aborted, prompting the programmer to fix the problem.
It is implementation defined whether the AssignExpression is evaluated at run time or not.
Programs that rely on side effects of AssignExpression are invalid.
 161

The result type of an assert expression is void. Asserts are a fundamental part of the Contract
Programming support in D.
The expression assert(0) is a special case; it signifies that it is unreachable code. Either
AssertError is thrown at runtime if it is reachable, or the execution is halted (on the x86 processor,
a HLT instruction can be used to halt execution). The optimization and code generation phases of
compilation may assume that it is unreachable code.
The second AssignExpression, if present, must be implicitly convertible to type const(char)[].
It is evaluated if the result is false, and the string result is appended to the AssertError’s message.
void main()
{
assert(0, "an" ~ "␣error␣message");
}
When compiled and run, it will produce the message:
Error: AssertError Failure test.d(3) an error message

Mixin Expressions
MixinExpression:
mixin ( AssignExpression )

The AssignExpression must evaluate at compile time to a constant string. The text contents of
the string must be compilable as a valid Expression, and is compiled as such.
int foo(int x)
{
return mixin("x␣+␣1") * 7; // same as ((x + 1) * 7)
}

Import Expressions
ImportExpression:
import ( AssignExpression )

The AssignExpression must evaluate at compile time to a constant string. The text contents of
the string are interpreted as a file name. The file is read, and the exact contents of the file become
a string literal.
Implementations may restrict the file name in order to avoid directory traversal security vulner-
abilities. A possible restriction might be to disallow any path components in the file name.
162 CHAPTER 10. EXPRESSIONS

Note that by default an import expression will not compile unless you pass one or more paths
via the -J switch. This tells the compiler where it should look for the files to import. This is a
security feature.
void foo()
{
// Prints contents of file foo.txt
writeln(import("foo.txt"));
}

Typeid Expressions
TypeidExpression:
typeid ( Type )
typeid ( Expression )

If Type, returns an instance of class TypeInfo corresponding to Type.

If Expression, returns an instance of class TypeInfo corresponding to the type of the Expression.
If the type is a class, it returns the TypeInfo of the dynamic type (i.e. the most derived type). The
Expression is always executed.
class A { }
class B : A { }

void main()
{
writeln(typeid(int)); // int
uint i;
writeln(typeid(i++)); // uint
writeln(i); // 1
A a = new B();
writeln(typeid(a)); // B
writeln(typeid(typeof(a))); // A
}

IsExpression
IsExpression:
is ( Type )
is ( Type : TypeSpecialization )
 163

is ( Type == TypeSpecialization )
is ( Type : TypeSpecialization , TemplateParameterList )
is ( Type == TypeSpecialization , TemplateParameterList )
is ( Type Identifier )
is ( Type Identifier : TypeSpecialization )
is ( Type Identifier == TypeSpecialization )
is ( Type Identifier : TypeSpecialization , TemplateParameterList )
is ( Type Identifier == TypeSpecialization , TemplateParameterList )

TypeSpecialization:
Type
struct
union
class
interface
enum
function
delegate
super
const
immutable
inout
shared
return
__parameters

IsExpressions are evaluated at compile time and are used for checking for valid types, comparing
types for equivalence, determining if one type can be implicitly converted to another, and deducing
the subtypes of a type. The result of an IsExpression is an int of type 0 if the condition is not
satisified, 1 if it is.
Type is the type being tested. It must be syntactically correct, but it need not be semantically
correct. If it is not semantically correct, the condition is not satisfied.
Identifier is declared to be an alias of the resulting type if the condition is satisfied. The
Identifier forms can only be used if the IsExpression appears in a StaticIfCondition.
TypeSpecialization is the type that Type is being compared against.
The forms of the IsExpression are:
164 CHAPTER 10. EXPRESSIONS

1. is ( Type ) The condition is satisfied if Type is semantically correct (it must be syntactically
correct regardless).
alias int func(int); // func is a alias to a function type
void foo()
{
if (is(func[])) // not satisfied because arrays of
// functions are not allowed
writeln("satisfied");
else
writeln("not␣satisfied");

if (is([][])) // error, [][] is not a syntactically valid type

...
}
2. is ( Type : TypeSpecialization ) The condition is satisfied if Type is semantically correct and
it is the same as or can be implicitly converted to TypeSpecialization. TypeSpecialization is
only allowed to be a Type.
alias bar = short;
void foo(bar x)
{
if (is(bar : int)) // satisfied because short can be
// implicitly converted to int
writeln("satisfied");
else
writeln("not␣satisfied");
}
3. is ( Type == TypeSpecialization )
The condition is satisfied if Type is semantically correct and is the same type as TypeSpecial-
ization.
If TypeSpecialization is one of
struct union class interface enum function delegate const immutable shared
then the condition is satisfied if Type is one of those.
alias bar = short;

void test(bar x)
{
if (is(bar == int)) // not satisfied because short is not
// the same type as int
 165

writeln("satisfied");
else
writeln("not␣satisfied");
}
4. is ( Type Identifier ) The condition is satisfied if Type is semantically correct. If so, Identifier
is declared to be an alias of Type.
alias bar = short;
void foo(bar x)
{
static if (is(bar T))
alias S = T;
else
alias S = long;

writeln(typeid(S)); // prints "short"

if (is(bar T)) // error, Identifier T form can
// only be in StaticIfConditions
...
}
5. is ( Type Identifier : TypeSpecialization )
The condition is satisfied if Type is the same as TypeSpecialization, or if Type is a class and
TypeSpecialization is a base class or base interface of it. The Identifier is declared to be
either an alias of the TypeSpecialization or, if TypeSpecialization is dependent on Identifier,
the deduced type.
alias bar = int;
alias abc = long*;
void foo(bar x, abc a)
{
static if (is(bar T : int))
alias S = T;
else
alias S = long;

writeln(typeid(S)); // prints "int"

static if (is(abc U : U*))

{
U u;
166 CHAPTER 10. EXPRESSIONS

writeln(typeid(typeof(u))); // prints "long"

}
}
The way the type of Identifier is determined is analogous to the way template parameter
types are determined by TemplateTypeParameterSpecialization.
6. is ( Type Identifier == TypeSpecialization )
The condition is satisfied if Type is semantically correct and is the same as TypeSpecialization.
The Identifier is declared to be either an alias of the TypeSpecialization or, if TypeSpecialization
is dependent on Identifier, the deduced type.
If TypeSpecialization is one of struct union class interface enum function delegate const
immutable shared
then the condition is satisfied if Type is one of those. Furthermore, Identifier is set to be an
alias of the type:

keyword alias type for Identifier

struct Type
union Type
class Type
interface Type
super TypeTuple of base classes and interfaces
enum the base type of the enum
function TypeTuple of the function parameter types. For C- and D-style variadic func-
tions, only the non-variadic parameters are included. For typesafe variadic
functions, the ... is ignored.
delegate the function type of the delegate
return the return type of the function, delegate, or function pointer
__parameters the parameter tuple of a function, delegate, or function pointer. This in-
cludes the parameter types, names, and default values.
const Type
immutable Type
shared Type

alias bar = short;

enum E : byte { Emember }
void foo(bar x)
{
static if (is(bar T == int)) // not satisfied, short is not int
alias S = T;
 167

alias U = T; // error, T is not defined

static if (is(E V == enum)) // satisified, E is an enum

V v; // v is declared to be a byte
}
7. is ( Type : TypeSpecialization , TemplateParameterList ) is ( Type == TypeSpecialization ,
TemplateParameterList ) is ( Type Identifier : TypeSpecialization , TemplateParameterList
) is ( Type Identifier == TypeSpecialization , TemplateParameterList )
More complex types can be pattern matched; the TemplateParameterList declares symbols
based on the parts of the pattern that are matched, analogously to the way implied template
parameters are matched.
import std.stdio, std.typecons;

void main()
{
alias Tup = Tuple!(int, string);
alias AA = long[char[]];

static if (is(Tup : TX!TL, alias TX, TL...))

{
writeln(is(TX!(int, long) == Tuple!(int, long))); // true
writeln(typeid(TL[0])); // int
writeln(typeid(TL[1])); // immutable(char)[]
}

static if (is(AA T : T[U], U : const char[]))

{
writeln(typeid(T)); // long
writeln(typeid(U)); // const char[]
}

static if (is(AA A : A[B], B : int))

{
assert(0); // should not match, as B is not an int
}

static if (is(int[10] W : W[V], int V))

{
writeln(typeid(W)); // int
168 CHAPTER 10. EXPRESSIONS

writeln(V); // 10
}

static if (is(int[10] X : X[Y], int Y : 5))

{
assert(0); // should not match, Y should be 10
}
}

Associativity and Commutativity

An implementation may rearrange the evaluation of expressions according to arithmetic associativity
and commutativity rules as long as, within that thread of execution, no observable difference is
possible.
This rule precludes any associative or commutative reordering of floating point expressions.
Chapter 11

Statements

C and C++ programmers will find the D statements very familiar, with a few interesting additions.

Statement:
;
NonEmptyStatement
ScopeBlockStatement

NoScopeNonEmptyStatement:
NonEmptyStatement
BlockStatement

NoScopeStatement:
;
NonEmptyStatement
BlockStatement

NonEmptyOrScopeBlockStatement:
NonEmptyStatement
ScopeBlockStatement

NonEmptyStatement:
NonEmptyStatementNoCaseNoDefault
CaseStatement
CaseRangeStatement
DefaultStatement

NonEmptyStatementNoCaseNoDefault:

169
170 CHAPTER 11. STATEMENTS

LabeledStatement
ExpressionStatement
DeclarationStatement
IfStatement
WhileStatement
DoStatement
ForStatement
ForeachStatement
SwitchStatement
FinalSwitchStatement
ContinueStatement
BreakStatement
ReturnStatement
GotoStatement
WithStatement
SynchronizedStatement
TryStatement
ScopeGuardStatement
ThrowStatement
AsmStatement
PragmaStatement
MixinStatement
ForeachRangeStatement
ConditionalStatement
StaticAssert
TemplateMixin
ImportDeclaration

Any ambiguities in the grammar between Statements and Declarations are resolved by the
declarations taking precedence. If a Statement is desired instead, wrapping it in parentheses will
disambiguate it in favor of being a Statement.

Scope Statements
ScopeStatement:
NonEmptyStatement
BlockStatement

A new scope for local symbols is introduced for the NonEmptyStatement or BlockStatement.
 171

Even though a new scope is introduced, local symbol declarations cannot shadow (hide) other
local symbol declarations in the same function.
void func1(int x)
{
int x; // illegal, x shadows parameter x

int y;

{ int y; } // illegal, y shadows enclosing scope’s y

void delegate() dg;

dg = { int y; }; // ok, this y is not in the same function

struct S
{
int y; // ok, this y is a member, not a local
}

{ int z; }
{ int z; } // ok, this z is not shadowing the other z

{ int t; }
{ t++; } // illegal, t is undefined
}
The idea is to avoid bugs in complex functions caused by scoped declarations inadvertently
hiding previous ones. Local names should all be unique within a function.

Scope Block Statements

ScopeBlockStatement:
BlockStatement

A scope block statement introduces a new scope for the BlockStatement.

Labeled Statements
Statements can be labeled. A label is an identifier that precedes a statement.

LabeledStatement:
172 CHAPTER 11. STATEMENTS

Identifier :
Identifier : NoScopeStatement
Identifier : Statement

Any statement can be labeled, including empty statements, and so can serve as the target of a
goto statement. Labeled statements can also serve as the target of a break or continue statement.
A label can appear without a following statement at the end of a block.
Labels are in a name space independent of declarations, variables, types, etc. Even so, labels
cannot have the same name as local declarations. The label name space is the body of the function
they appear in. Label name spaces do not nest, i.e. a label inside a block statement is accessible
from outside that block.

Block Statement
BlockStatement:
{ }
{ StatementList }

StatementList:
Statement
Statement StatementList

A block statement is a sequence of statements enclosed by . The statements are executed in

lexical order.

Expression Statement
ExpressionStatement:
Expression ;

The expression is evaluated.

Expressions that have no effect, like (x + x), are illegal in expression statements. If such an
expression is needed, casting it to void will make it legal.
int x;
x++; // ok
x; // illegal
1+1; // illegal
cast(void)(x + x); // ok
 173

Declaration Statement
Declaration statements declare variables and types.

DeclarationStatement:
StorageClasses opt Declaration

Some declaration statements:

int a; // declare a as type int and initialize it to 0
struct S { } // declare struct s
alias myint = int;

If Statement
If statements provide simple conditional execution of statements.

IfStatement:
if ( IfCondition ) ThenStatement
if ( IfCondition ) ThenStatement else ElseStatement

IfCondition:
Expression
auto Identifier = Expression
TypeCtors Identifier = Expression
TypeCtors opt BasicType Declarator = Expression

ThenStatement:
ScopeStatement

ElseStatement:
ScopeStatement

Expression is evaluated and must have a type that can be converted to a boolean. If it’s true
the ThenStatement is transferred to, else the ElseStatement is transferred to.
The ’dangling else’ parsing problem is solved by associating the else with the nearest if statement.
If an auto Identifier is provided, it is declared and initialized to the value and type of the
Expression. Its scope extends from when it is initialized to the end of the ThenStatement.
If a Declarator is provided, it is declared and initialized to the value of the Expression. Its scope
extends from when it is initialized to the end of the ThenStatement.
174 CHAPTER 11. STATEMENTS

import std.regexp;
...
if (auto m = std.regexp.search("abcdef", "b(c)d"))
{
writefln("[%s]", m.pre); // prints [a]
writefln("[%s]", m.post); // prints [ef]
writefln("[%s]", m.match(0)); // prints [bcd]
writefln("[%s]", m.match(1)); // prints [c]
writefln("[%s]", m.match(2)); // prints []
}
else
{
writeln(m.post); // error, m undefined
}
writeln(m.pre); // error, m undefined

While Statement
WhileStatement:
while ( Expression ) ScopeStatement

While statements implement simple loops.

Expression is evaluated and must have a type that can be converted to a boolean. If it’s true
the ScopeStatement is executed. After the ScopeStatement is executed, the Expression is evalu-
ated again, and if true the ScopeStatement is executed again. This continues until the Expression
evaluates to false.
int i = 0;
while (i < 10)
{
foo(i);
i++;
}
A BreakStatement will exit the loop. A ContinueStatement will transfer directly to evaluating
Expression again.

Do Statement
DoStatement:
 175

do ScopeStatement while ( Expression ) ;

Do while statements implement simple loops.

ScopeStatement is executed. Then Expression is evaluated and must have a type that can be
converted to a boolean. If it’s true the loop is iterated again. This continues until the Expression
evaluates to false.
int i = 0;
do
{
foo(i);
} while (++i < 10);
A BreakStatement will exit the loop. A ContinueStatement will transfer directly to evaluating
Expression again.

For Statement
For statements implement loops with initialization, test, and increment clauses.

ForStatement:
for ( Initialize Test opt ; Increment opt ) ScopeStatement

Initialize:
;
NoScopeNonEmptyStatement

Test:
Expression

Increment:
Expression

Initialize is executed. Test is evaluated and must have a type that can be converted to a boolean.
If it’s true the statement is executed. After the statement is executed, the Increment is executed.
Then Test is evaluated again, and if true the statement is executed again. This continues until the
Test evaluates to false.
A BreakStatement will exit the loop. A ContinueStatement will transfer directly to the Incre-
ment.
176 CHAPTER 11. STATEMENTS

A ForStatement creates a new scope. If Initialize declares a variable, that variable’s scope
extends through the end of the for statement. For example:
for (int i = 0; i < 10; i++)
foo(i);
is equivalent to:
{
int i;
for (i = 0; i < 10; i++)
foo(i);
}
Function bodies cannot be empty:
for (int i = 0; i < 10; i++)
; // illegal
Use instead:
for (int i = 0; i < 10; i++)
{
}
The Initialize may be omitted. Test may also be omitted, and if so, it is treated as if it evaluated
to true.

Foreach Statement
A foreach statement loops over the contents of an aggregate.

ForeachStatement:
Foreach ( ForeachTypeList ; ForeachAggregate ) NoScopeNonEmptyStatement

Foreach:
foreach
foreach_reverse

ForeachTypeList:
ForeachType
ForeachType , ForeachTypeList

ForeachType:
ForeachTypeAttributes opt BasicType Declarator
 177

ForeachTypeAttributes opt Identifier

ForeachTypeAttributes
ForeachTypeAttribute
ForeachTypeAttribute ForeachTypeAttributes opt

ForeachTypeAttribute:
ref
TypeCtor

ForeachAggregate:
Expression

ForeachAggregate is evaluated. It must evaluate to an expression of type static array, dynamic

array, associative array, struct, class, delegate, or tuple. The NoScopeNonEmptyStatement is exe-
cuted, once for each element of the aggregate. At the start of each iteration, the variables declared
by the ForeachTypeList are set to be a copy of the elements of the aggregate. If the variable is ref,
it is a reference to the contents of that aggregate.
The aggregate must be loop invariant, meaning that elements to the aggregate cannot be added
or removed from it in the NoScopeNonEmptyStatement.

Foreach over Arrays

If the aggregate is a static or dynamic array, there can be one or two variables declared. If one,
then the variable is said to be the value set to the elements of the array, one by one. The type of
the variable must match the type of the array contents, except for the special cases outlined below.
If there are two variables declared, the first is said to be the index and the second is said to be the
value. The index must be of int, uint or size_t type, it cannot be ref, and it is set to be the index
of the array element.
char[] a;
...
foreach (int i, char c; a)
{
writefln("a[%d]␣=␣’%c’", i, c);
}
For foreach, the elements for the array are iterated over starting at index 0 and continuing
to the maximum of the array. For foreach_reverse, the array elements are visited in the reverse
order.
178 CHAPTER 11. STATEMENTS

Foreach over Arrays of Characters

If the aggregate expression is a static or dynamic array of chars, wchars, or dchars, then the Type
of the value can be any of char, wchar, or dchar. In this manner any UTF array can be decoded
into any UTF type:
char[] a = "\xE2\x89\xA0".dup; // \u2260 encoded as 3 UTF-8 bytes

foreach (dchar c; a)
{
writefln("a[]␣=␣%x", c); // prints ’a[] = 2260’
}

dchar[] b = "\u2260"d.dup;

foreach (char c; b)
{
writef("%x,␣", c); // prints ’e2, 89, a0, ’
}
Aggregates can be string literals, which can be accessed as char, wchar, or dchar arrays:
void test()
{
foreach (char c; "ab")
{
writefln("’%s’", c);
}
foreach (wchar w; "xy")
{
writefln("’%s’", w);
}
}
which would print:
’a’ ’b’ ’x’ ’y’

Foreach over Associative Arrays

If the aggregate expression is an associative array, there can be one or two variables declared. If
one, then the variable is said to be the value set to the elements of the array, one by one. The type
of the variable must match the type of the array contents. If there are two variables declared, the
first is said to be the index and the second is said to be the value. The index must be of the same
 179

type as the indexing type of the associative array. It cannot be ref, and it is set to be the index of
the array element. The order in which the elements of the array are iterated over is unspecified for
foreach. foreach_reverse for associative arrays is illegal.
double[string] a; // index type is string, value type is double
...
foreach (string s, double d; a)
{
writefln("a[’%s’]␣=␣%g", s, d);
}

Foreach over Structs and Classes with opApply

If the aggregate expression is a struct or class object, the foreach is defined by the special
opApply member function, and the foreach_reverse behavior is defined by the special
opApplyReverse member function. These functions have the type:
int opApply(int delegate(ref Type [, ...]) dg);

int opApplyReverse(int delegate(ref Type [, ...]) dg);

where Type matches the Type used in the ForeachType declaration of Identifier. Multi-
ple ForeachTypes correspond with multiple Type’s in the delegate type passed to opApply or
opApplyReverse. There can be multiple opApply and opApplyReverse functions, one is selected
by matching the type of dg to the ForeachTypes of the ForeachStatement. The body of the apply
function iterates over the elements it aggregates, passing them each to the dg function. If the dg
returns 0, then apply goes on to the next element. If the dg returns a nonzero value, apply must
cease iterating and return that value. Otherwise, after done iterating across all the elements, apply
will return 0.
For example, consider a class that is a container for two elements:
class Foo
{
uint[2] array;

int opApply(int delegate(ref uint) dg)

{
int result = 0;

for (int i = 0; i < array.length; i++)

{
result = dg(array[i]);
180 CHAPTER 11. STATEMENTS

if (result)
break;
}
return result;
}
}
An example using this might be:
void test()
{
Foo a = new Foo();

a.array[0] = 73;
a.array[1] = 82;

foreach (uint u; a)
{
writefln("%d", u);
}
}
which would print:
73 82
opApply can also be a templated function, which will infer the types of parameters based on the
ForeachStatement.
For example:
struct S
{
import std.traits : ParameterTypeTuple; // introspection template

int opApply(Dg)(scope Dg dg)

if (ParameterTypeTuple!Dg.length == 2) // foreach function takes 2 ⤦
Ç parameters
{
return 0;
}

int opApply(Dg)(scope Dg dg)

if (ParameterTypeTuple!Dg.length == 3) // foreach function takes 3 ⤦
Ç parameters
 181

{
return 0;
}
}

void main()
{
foreach (int a, int b; S()) { } // calls first opApply function
foreach (int a, int b, float c; S()) { } // calls second opApply function
}

Foreach over Structs and Classes with Ranges

If the aggregate expression is a struct or class object, but the opApply for foreach, or
opApplyReverse foreach_reverse do not exist, then iteration over struct and class objects can be
done with range primitives. For foreach, this means the following properties and methods must
be defined:

Foreach Range Properties

Property Purpose
.empty returns true if no more elements
.front return the leftmost element of the range

Foreach Range Methods

Method Purpose
.popFront() move the left edge of the range right by one

Meaning:
foreach (e; range) { ... }
translates to:
for (auto __r = range; !__r.empty; __r.popFront())
{
auto e = __r.front;
...
}
Similarly, for foreach_reverse, the following properties and methods must be defined:
182 CHAPTER 11. STATEMENTS

Foreach_reverse Range Properties

Property Purpose
.empty returns true if no more elements
.back return the rightmost element of the range

Foreach_reverse Range Methods

Method Purpose
.popBack() move the right edge of the range left by one

Meaning:
foreach_reverse (e; range) { ... }
translates to:
for (auto __r = range; !__r.empty; __r.popBack())
{
auto e = __r.back;
...
}

Foreach over Delegates

If ForeachAggregate is a delegate, the type signature of the delegate is of the same as for opApply.
This enables many different named looping strategies to coexist in the same class or struct.
For example:
void main()
{
// Custom loop implementation, that iterates over powers of 2 with
// alternating sign. The loop body is passed in dg.
int myLoop(int delegate(ref int) dg)
{
for (int z = 1; z < 128; z *= -2)
{
auto ret = dg(z);

// If the loop body contains a break, ret will be non-zero.

if (ret != 0)
return ret;
}
 183

return 0;
}

// This example loop simply collects the loop index values into an array.
int[] result;
foreach (ref x; &myLoop)
{
result ~= x;
}
assert(result == [1, -2, 4, -8, 16, -32, 64, -128]);
}
Note: When ForeachAggregate is a delegate, the compiler does not try to implement reverse
traversal of the results returned by the delegate when foreach_reverse is used. This may result in
code that is confusing to read. Therefore, using foreach_reverse with a delegate is now deprecated,
and will be rejected in the future.

Foreach over Tuples

If the aggregate expression is a tuple, there can be one or two variables declared. If one, then the
variable is said to be the value set to the elements of the tuple, one by one. If the type of the
variable is given, it must match the type of the tuple contents. If it is not given, the type of the
variable is set to the type of the tuple element, which may change from iteration to iteration. If
there are two variables declared, the first is said to be the index and the second is said to be the
value. The index must be of int or uint type, it cannot be ref, and it is set to be the index of the
tuple element.
If the tuple is a list of types, then the foreach statement is executed once for each type, and the
value is aliased to that type.
import std.stdio;
import std.typetuple; // for TypeTuple

void main()
{
alias TL = TypeTuple!(int, long, double);

foreach (T; TL)

{
writeln(typeid(T));
}
}
184 CHAPTER 11. STATEMENTS

Prints:
int long double

Foreach Ref Parameters

ref can be used to update the original elements:
void test()
{
static uint[2] a = [7, 8];

foreach (ref uint u; a)

{
u++;
}
foreach (uint u; a)
{
writefln("%d", u);
}
}

which would print:

8 9 ref can not be applied to the index values.
If not specified, the Types in the ForeachType can be inferred from the type of the ForeachAg-
gregate.

Foreach Restrictions
The aggregate itself must not be resized, reallocated, free’d, reassigned or destructed while the
foreach is iterating over the elements.
int[] a;
int[] b;
foreach (int i; a)
{
a = null; // error
a.length += 10; // error
a = b; // error
}
a = null; // ok
 185

Foreach Range Statement

A foreach range statement loops over the specified range.

ForeachRangeStatement:
Foreach ( ForeachType ; LwrExpression .. UprExpression ) ScopeStatement

LwrExpression:
Expression

UprExpression:
Expression

ForeachType declares a variable with either an explicit type, or a type inferred from LwrEx-
pression 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 executed zero times. If Foreach is foreach, then the variable is set to Lwr-
Expression, 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
186 CHAPTER 11. STATEMENTS

Break and Continue out of Foreach

A BreakStatement in the body of the foreach will exit the foreach, a ContinueStatement will imme-
diately start the next iteration.

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

SwitchStatement:
switch ( Expression ) ScopeStatement

CaseStatement:
case ArgumentList : ScopeStatementList

CaseRangeStatement:
case FirstExp : .. case LastExp : ScopeStatementList

FirstExp:
AssignExpression

LastExp:
AssignExpression

DefaultStatement:
default : ScopeStatementList

ScopeStatementList:
StatementListNoCaseNoDefault

StatementListNoCaseNoDefault:
StatementNoCaseNoDefault
StatementNoCaseNoDefault StatementListNoCaseNoDefault

StatementNoCaseNoDefault:
;
NonEmptyStatementNoCaseNoDefault
ScopeBlockStatement
 187

Expression is evaluated. The result type T must be of integral type or char[], wchar[] or
dchar[]. The result is compared against each of the case expressions. If there is a match, the
corresponding case statement is transferred to.
The case expressions, ArgumentList, are a comma separated list of expressions.
A CaseRangeStatement is a shorthand for listing a series of case statements from FirstExp to
LastExp.
If none of the case expressions match, and there is a default statement, the default statement is
transferred to.
A switch statement must have a default statement.
The case expressions must all evaluate to a constant value or array, or a runtime initialized const
or immutable variable of integral type.
They must be implicitly convertible to the type of the switch Expression.
Case expressions must all evaluate to distinct values. Const or immutable variables must all
have different names. If they share a value, the first case statement with that value gets control.
There must be exactly one default statement.
The ScopeStatementList introduces a new scope.
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:
}
break;
}
A ScopeStatementList must either be empty, or be ended with a ContinueStatement, Break-
Statement, ReturnStatement, GotoStatement, ThrowStatement or assert(0) expression unless this is
the last case. This is to set apart with C’s error-prone implicit fall-through behavior. goto case;
could be used for explicit fall-through:
int number;
string message;
switch (number)
{
default: // valid: ends with ’throw’
throw new Exception("unknown␣number");

case 3: // valid: ends with ’break’ (break out of the ’switch’ only)
188 CHAPTER 11. STATEMENTS

message ~= "three␣";
break;

case 4: // valid: ends with ’continue’ (continue the enclosing loop)

message ~= "four␣";
continue;

case 5: // valid: ends with ’goto’ (explicit fall-through to next case.)

message ~= "five␣";
goto case;

case 6: // ERROR: implicit fall-through

message ~= "six␣";

case 1: // valid: the body is empty

case 2: // valid: this is the last case in the switch statement.
message = "one␣or␣two";
}
A break statement will exit the switch BlockStatement.
Strings can be used in switch expressions. For example:
char[] 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.
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.

Final Switch Statement

FinalSwitchStatement:
final switch ( Expression ) ScopeStatement
 189

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

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

Continue Statement
ContinueStatement:
continue Identifier opt ;

A continue aborts the current iteration of its enclosing loop statement, and starts the next
iteration.
continue executes the next iteration of its innermost enclosing while, for, foreach, or do loop.
The increment clause is executed.
If continue is followed by Identifier, the Identifier must be the label of an enclosing while, for, or
do loop, and the next iteration of that loop is executed. It is an error if there is no such statement.
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.
for (i = 0; i < 10; i++)
{
if (foo(i))
continue;
bar();
}

Break Statement
BreakStatement:
break Identifier opt ;

A break exits the enclosing statement.

break exits the innermost enclosing while, for, foreach, do, or switch statement, resuming exe-
cution at the statement following it.
190 CHAPTER 11. STATEMENTS

If break is followed by Identifier, the Identifier must be the label of an enclosing while, for, do
or switch statement, and that statement is exited. It is an error if there is no such statement.
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.
for (i = 0; i < 10; i++)
{
if (foo(i))
break;
}

Return Statement
ReturnStatement:
return Expression opt ;

A return exits the current function and supplies its return value.
Expression is required if the function specifies a return type that is not void. The Expression is
implicitly converted to the function return type.
At least one return statement, throw statement, or assert(0) expression is required if the function
specifies a return type that is not void, unless the function contains inline assembler code.
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 (see Contract Programming), that postcondition is executed
after the Expression is evaluated and before the function actually returns.
int foo(int x)
{
return x + 3;
}

Goto Statement
GotoStatement:
goto Identifier ;
 191

goto default ;
goto case ;
goto case Expression ;

A 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 Expression;, transfers to the CaseStatement of the innermost
enclosing SwitchStatement with a matching Expression.
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 ) ScopeStatement
192 CHAPTER 11. STATEMENTS

with ( Symbol ) ScopeStatement

with ( TemplateInstance ) ScopeStatement

where Expression evaluates to a class reference or struct instance. Within the with body the
referenced object is searched first for identifier symbols. The WithStatement
with (expression)
{
...
ident;
}
is semantically equivalent to:
{
Object tmp;
tmp = expression;
...
tmp.ident;
}
Note that Expression only gets evaluated once. 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 inadvertant breakage of with statements when new members are added
to the object declaration.
struct S
{
 193

float x;
}

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

Synchronized Statement
The synchronized statement wraps a statement with a mutex to synchronize access among multiple
threads.

SynchronizedStatement:
synchronized ScopeStatement
synchronized ( Expression ) ScopeStatement

Synchronized allows only one thread at a time to execute ScopeStatement by using a mutex.
What mutex is used is determined by the Expression. If there is no Expression, then a global
mutex is created, one per such synchronized statement. Different synchronized statements will have
different global mutexes.
If there is an Expression, it must evaluate to either an Object or an instance of an Interface,
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.
The synchronization gets released even if ScopeStatement terminates with an exception, goto,
or return.
Example:
synchronized { ... }
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.
194 CHAPTER 11. STATEMENTS

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

TryStatement:
try ScopeStatement Catches
try ScopeStatement Catches FinallyStatement
try ScopeStatement FinallyStatement

Catches:
LastCatch
Catch
Catch Catches

LastCatch:
catch NoScopeNonEmptyStatement

Catch:
catch ( CatchParameter ) NoScopeNonEmptyStatement

CatchParameter:
BasicType Identifier

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.
LastCatch catches all exceptions.
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
 195

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 Error 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)
{
writeln("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.

Throw Statement
Throw an exception.
196 CHAPTER 11. STATEMENTS

ThrowStatement:
throw Expression ;

Expression is evaluated and must be a Throwable reference. The Throwable reference is thrown
as an exception.
throw new Exception("message");

Scope Guard Statement

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

The ScopeGuardStatement executes NonEmptyOrScopeBlockStatement at the close of the cur-

rent scope, rather than at the point where the ScopeGuardStatement appears. scope(exit) executes
NonEmptyOrScopeBlockStatement when the scope exits normally or when it exits due to exception
unwinding. scope(failure) executes NonEmptyOrScopeBlockStatement when the scope exits due
to exception unwinding. scope(success) executes NonEmptyOrScopeBlockStatement 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");
 197

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.

Asm Statement
Inline assembler is supported with the asm statement:

AsmStatement:
asm FunctionAttributes opt { AsmInstructionList opt }
198 CHAPTER 11. STATEMENTS

AsmInstructionList:
AsmInstruction ;
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 implementation defined. 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
{
 199

...
}
}
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
PragmaStatement:
Pragma NoScopeStatement

Mixin Statement
MixinStatement:
mixin ( AssignExpression ) ;

The AssignExpression must evaluate at compile time to a constant 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 j;
mixin("
␣␣␣␣␣␣␣␣int␣x␣=␣3;
␣␣␣␣␣␣␣␣for␣(int␣i␣=␣0;␣i␣<␣3;␣i++)
␣␣␣␣␣␣␣␣␣␣␣␣writeln(x␣+␣i,␣++j);
␣␣␣␣␣␣␣␣"); // ok

const char[] s = "int␣y;";

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

char[] t = "y␣=␣3;";
200 CHAPTER 11. STATEMENTS

mixin(t); // error, t is not evaluatable at compile time

mixin("y␣=") 4; // error, string must be complete statement

mixin("y␣=" ~ "4;"); // ok
}
Chapter 12

Arrays

There are four kinds of arrays:

Kinds of Arrays
Syntax Description
type* Pointers to data
type[integer ] Static arrays
type[] Dynamic arrays
type[type] Associative arrays

Pointers

int* p;
These are simple pointers to data, analogous to C pointers. Pointers are provided for interfacing
with C and for specialized systems work. There is no length associated with it, and so there is no
way for the compiler or runtime to do bounds checking, etc., on it. Most conventional uses for
pointers can be replaced with dynamic arrays, out and ref parameters, and reference types.
Static Arrays

int[3] s;
These are analogous to C arrays. Static arrays are distinguished by having a length fixed at
compile time.
The total size of a static array cannot exceed 16Mb. A dynamic array should be used instead
for such large arrays.
A static array with a dimension of 0 is allowed, but no space is allocated for it. It’s useful as
the last member of a variable length struct, or as the degenerate case of a template expansion.

201
202 CHAPTER 12. ARRAYS

Static arrays are value types. Unlike in C and D version 1, static arrays are passed to functions
by value. Static arrays can also be returned by functions.
Dynamic Arrays

int[] a;
Dynamic arrays consist of a length and a pointer to the array data. Multiple dynamic arrays
can share all or parts of the array data.
12.1 Array Declarations
Declarations appear before the identifier being declared and read right to left, so:
int[] a; // dynamic array of ints
int[4][3] b; // array of 3 arrays of 4 ints each
int[][5] c; // array of 5 dynamic arrays of ints.
int*[]*[3] d; // array of 3 pointers to dynamic arrays of pointers to ints
int[]* e; // pointer to dynamic array of ints

12.2 Array Usage

There are two broad kinds of operations to do on an array - affecting the handle to the array,
and affecting the contents of the array. C only has operators to affect the handle. In D, both are
accessible.
The handle to an array is specified by naming the array, as in p, s or a:
int* p;
int[3] s;
int[] a;

int* q;
int[3] t;
int[] b;

p = q; // p points to the same thing q does.

p = s.ptr; // p points to the first element of the array s.
p = a.ptr; // p points to the first element of the array a.

s = ...; // error, since s is a compiled in static

// reference to an array.

a = p; // error, since the length of the array pointed

12.3. SLICING 203

// to by p is unknown
a = s; // a is initialized to point to the s array
a = b; // a points to the same array as b does

12.3 Slicing
Slicing an array means to specify a subarray of it. An array slice does not copy the data, it is only
another reference to it. For example:
int[10] a; // declare array of 10 ints
int[] b;

b = a[1..3]; // a[1..3] is a 2 element array consisting of

// a[1] and a[2]
foo(b[1]); // equivalent to foo(0)
a[2] = 3;
foo(b[1]); // equivalent to foo(3)
The [] is shorthand for a slice of the entire array. For example, the assignments to b:
int[10] a;
int[] b;

b = a;
b = a[];
b = a[0 .. a.length];
are all semantically equivalent.
Slicing is not only handy for referring to parts of other arrays, but for converting pointers into
bounds-checked arrays:
int* p;
int[] b = p[0..8];

12.4 Array Copying

When the slice operator appears as the left-hand side of an assignment expression, it means that the
contents of the array are the target of the assignment rather than a reference to the array. Array
copying happens when the left-hand side is a slice, and the right-hand side is an array of or pointer
to the same type.
204 CHAPTER 12. ARRAYS

int[3] s;
int[3] t;

s[] = t; // the 3 elements of t[3] are copied into s[3]

s[] = t[]; // the 3 elements of t[3] are copied into s[3]
s[1..2] = t[0..1]; // same as s[1] = t[0]
s[0..2] = t[1..3]; // same as s[0] = t[1], s[1] = t[2]
s[0..4] = t[0..4]; // error, only 3 elements in s
s[0..2] = t; // error, operands have different lengths

Overlapping Copying
Overlapping copies are an error:

s[0..2] = s[1..3]; // error, overlapping copy

s[1..3] = s[0..2]; // error, overlapping copy

Disallowing overlapping makes it possible for more aggressive parallel code optimizations than
possible with the serial semantics of C.
If overlapping is required, use std.algorithm.mutation.copy:

import std.algorithm;
int[] s = [1, 2, 3, 4];

copy(s[1..3], s[0..2]);
assert(s == [2, 3, 3, 4]);

12.5 Array Setting

If a slice operator appears as the left-hand side of an assignment expression, and the type of the
right-hand side is the same as the element type of the left-hand side, then the array contents of the
left-hand side are set to the right-hand side.

int[3] s;
int* p;

s[] = 3; // same as s[0] = 3, s[1] = 3, s[2] = 3

p[0..2] = 3; // same as p[0] = 3, p[1] = 3
12.6. ARRAY CONCATENATION 205

12.6 Array Concatenation

The binary operator is the cat operator. It is used to concatenate arrays:
int[] a;
int[] b;
int[] c;

a = b ~ c; // Create an array from the concatenation

// of the b and c arrays
Many languages overload the + operator to mean concatenation. This confusingly leads to,
does:
"10" + 3 + 4
produce the number 17, the string "1034" or the string "107" as the result? It isn’t obvious, and
the language designers wind up carefully writing rules to disambiguate it - rules that get incorrectly
implemented, overlooked, forgotten, and ignored. It’s much better to have + mean addition, and a
separate operator to be array concatenation.
Similarly, the = operator means append, as in:
a ~= b; // a becomes the concatenation of a and b
Concatenation always creates a copy of its operands, even if one of the operands is a 0 length
array, so:
a = b; // a refers to b
a = b ~ c[0..0]; // a refers to a copy of b
Appending does not always create a copy, see setting dynamic array length for details.

12.7 Array Operations

Many array operations, also known as vector operations, can be expressed at a high level rather
than as a loop. For example, the loop:
T[] a, b;
...
for (size_t i = 0; i < a.length; i++)
a[i] = b[i] + 4;
assigns to the elements of a the elements of b with 4 added to each. This can also be expressed
in vector notation as:
206 CHAPTER 12. ARRAYS

T[] a, b;
...
a[] = b[] + 4;

A vector operation is indicated by the slice operator appearing as the left-hand side of an =,
+=, -=, *=, /=, operator. The right-hand side can be an expression consisting either of an array
slice of the same length and type as the left-hand side or an expression of the element type of the
left-hand side, in any combination. The operators supported for vector operations are the binary
operators +, -, *, /, - and .
The slice on the left and any slices on the right must not overlap. The vector assignment
operators are evaluated right to left, and the other binary operators are evaluated left to right. All
operands are evaluated exactly once, even if the array slice has zero elements in it.
The order in which the array elements are computed is implementation defined, and may even
occur in parallel. An application must not depend on this order.
Implementation note: many of the more common vector operations are expected to take advan-
tage of any vector math instructions available on the target computer.

12.8 Pointer Arithmetic

int[3] abc; // static array of 3 ints

int[] def = [ 1, 2, 3 ]; // dynamic array of 3 ints

void dibb(int* array)

{
array[2]; // means same thing as *(array + 2)
*(array + 2); // get 3rd element
}

void diss(int[] array)

{
array[2]; // ok
*(array + 2); // error, array is not a pointer
}

void ditt(int[3] array)

{
array[2]; // ok
*(array + 2); // error, array is not a pointer
}
12.9. RECTANGULAR ARRAYS 207

12.9 Rectangular Arrays

Experienced FORTRAN numerics programmers know that multidimensional "rectangular" arrays
for things like matrix operations are much faster than trying to access them via pointers to pointers
resulting from "array of pointers to array" semantics. For example, the D syntax:
double[][] matrix;

declares matrix as an array of pointers to arrays. (Dynamic arrays are implemented as pointers to
the array data.) Since the arrays can have varying sizes (being dynamically sized), this is sometimes
called "jagged" arrays. Even worse for optimizing the code, the array rows can sometimes point to
each other! Fortunately, D static arrays, while using the same syntax, are implemented as a fixed
rectangular layout:
double[3][3] matrix;

declares a rectangular matrix with 3 rows and 3 columns, all contiguously in memory. In other
languages, this would be called a multidimensional array and be declared as:
double matrix[3,3];

12.10 Array Length

Within the [ ] of a static or a dynamic array, the symbol $ represents the length of the array.
int[4] foo;
int[] bar = foo;
int* p = &foo[0];

// These expressions are equivalent:

bar[]
bar[0 .. 4]
bar[0 .. $]
bar[0 .. bar.length]

p[0 .. $] // ’\$’ is not defined, since p is not an array

bar[0]+$ // ’\$’ is not defined, out of scope of [ ]

bar[$-1] // retrieves last element of the array

208 CHAPTER 12. ARRAYS

12.11 Array Properties

Static array properties are:

Static Array Properties

Property Description
.init Returns an array literal with each element of the literal being the .init property
of the array element type.
.sizeof Returns the array length multiplied by the number of bytes per array element.
.length Returns the number of elements in the array. This is a fixed quantity for static
arrays. It is of type size_t.
.ptr Returns a pointer to the first element of the array.
.dup Create a dynamic array of the same size and copy the contents of the array into
it.
.idup Create a dynamic array of the same size and copy the contents of the array into
it. The copy is typed as being immutable.
.reverse Reverses in place the order of the elements in the array. Returns the array.
.sort Sorts in place the order of the elements in the array. Returns the array.

Dynamic array properties are:

Dynamic Array Properties

Property Description
.init Returns null.
.sizeof Returns the size of the dynamic array reference, which is 8 in 32-bit builds and
16 on 64-bit builds.
.length Get/set number of elements in the array. It is of type size_t.
.ptr Returns a pointer to the first element of the array.
.dup Create a dynamic array of the same size and copy the contents of the array into
it.
.idup Create a dynamic array of the same size and copy the contents of the array into
it. The copy is typed as being immutable. D 2.0 only
.reverse Reverses in place the order of the elements in the array. Returns the array.
.sort Sorts in place the order of the elements in the array. Returns the array.

For the .sort property to work on arrays of class objects, the class definition must define the
function: int opCmp(Object). This is used to determine the ordering of the class objects. Note
that the parameter is of type Object, not the type of the class.
For the .sort property to work on arrays of structs or unions, the struct or union definition
must define the function:
12.11. ARRAY PROPERTIES 209

int opCmp(ref const S) const.

The type S is the type of the struct or union. This function will determine the sort ordering.
Examples:
int* p;
int[3] s;
int[] a;

p.length; // error, length not known for pointer

s.length; // compile time constant 3
a.length; // runtime value

p.dup; // error, length not known

s.dup; // creates an array of 3 elements, copies
// elements s into it
a.dup; // creates an array of a.length elements, copies
// elements of a into it

Setting Dynamic Array Length

The .length property of a dynamic array can be set as the left-hand side of an = operator:
array.length = 7;
This causes the array to be reallocated in place, and the existing contents copied over to the
new array. If the new array length is shorter, the array is not reallocated, and no data is copied. It
is equivalent to slicing the array:
array = array[0..7];
If the new array length is longer, the remainder is filled out with the default initializer.
To maximize efficiency, the runtime always tries to resize the array in place to avoid extra
copying.
It will always do a copy if the new size is larger and the array was not allocated via the new
operator or resizing in place would overwrite valid data in the array.
For example:
char[] a = new char[20];
char[] b = a[0..10];
char[] c = a[10..20];
char[] d = a;

b.length = 15; // always reallocates because extending in place would

210 CHAPTER 12. ARRAYS

// overwrite other data in a.

b[11] = ’x’; // a[11] and c[1] are not affected

d.length = 1;
d.length = 20; // also reallocates, because doing this will overwrite a and
// c

c.length = 12; // may reallocate in place if space allows, because nothing

// was allocated after c.
c[5] = ’y’; // may affect contents of a, but not b or d because those
// were reallocated.

a.length = 25; // This always reallocates because if c extended in place,

// then extending a would overwrite c. If c didn’t
// reallocate in place, it means there was not enough space,
// which will still be true for a.
a[15] = ’z’; // does not affect c, because either a or c has reallocated.
To guarantee copying behavior, use the .dup property to ensure a unique array that can be
resized. Also, one may use the phobos .capacity property to determine how many elements can
be appended to the array without reallocating.
These issues also apply to appending arrays with the = operator. Concatenation using the
operator is not affected since it always reallocates.
Resizing a dynamic array is a relatively expensive operation. So, while the following method of
filling an array:
int[] array;
while (1)
{
c = getinput();
if (!c)
break;
++array.length;
array[array.length - 1] = c;
}
will work, it will be inefficient. A more practical approach would be to minimize the number of
resizes:
int[] array;
array.length = 100; // guess
for (i = 0; ; i++)
12.12. ARRAY BOUNDS CHECKING 211

{
c = getinput();
if (!c)
break;
if (i == array.length)
array.length *= 2;
array[i] = c;
}
array.length = i;
Picking a good initial guess is an art, but you usually can pick a value covering 99For example,
when gathering user input from the console - it’s unlikely to be longer than 80.
Also, you may wish to utilize the phobos reserve function to pre-allocate array data to use
with the append operator.

Functions as Array Properties

If the first parameter to a function is an array, the function can be called as if it were a property of
the array:
int[] array;
void foo(int[] a, int x);

foo(array, 3);
array.foo(3); // means the same thing

12.12 Array Bounds Checking

It is an error to index an array with an index that is less than 0 or greater than or equal to the array
length. If an index is out of bounds, a RangeError exception is raised if detected at runtime, and
an error if detected at compile time. A program may not rely on array bounds checking happening,
for example, the following program is incorrect:
try
{
for (i = 0; ; i++)
{
array[i] = 5;
}
}
catch (RangeError)
212 CHAPTER 12. ARRAYS

{
// terminate loop
}
The loop is correctly written:
for (i = 0; i < array.length; i++)
{
array[i] = 5;
}
Implementation Note: Compilers should attempt to detect array bounds errors at compile
time, for example:
int[3] foo;
int x = foo[3]; // error, out of bounds
Insertion of array bounds checking code at runtime should be turned on and off with a compile
time switch.

12.13 Array Initialization

Default Initialization
• Pointers are initialized to null.
• Static array contents are initialized to the default initializer for the array element type.
• Dynamic arrays are initialized to having 0 elements.
• Associative arrays are initialized to having 0 elements.

Void Initialization
Void initialization happens when the Initializer for an array is void. What it means is that no
initialization is done, i.e. the contents of the array will be undefined. This is most useful as an
efficiency optimization. Void initializations are an advanced technique and should only be used
when profiling indicates that it matters.

Static Initialization of Statically Allocated Arrays

Static initalizations are supplied by a list of array element values enclosed in [ ]. The values can be
optionally preceded by an index and a :. If an index is not supplied, it is set to the previous index
plus 1, or 0 if it is the first value.
int[3] a = [ 1:2, 3 ]; // a[0] = 0, a[1] = 2, a[2] = 3
12.14. SPECIAL ARRAY TYPES 213

This is most handy when the array indices are given by enums:
enum Color { red, blue, green };

int value[Color.max + 1] =
[ Color.blue :6,
Color.green:2,
Color.red :5 ];
These arrays are statically allocated when they appear in global scope. Otherwise, they need to
be marked with const or static storage classes to make them statically allocated arrays.

12.14 Special Array Types

Strings
A string is an array of characters. String literals are just an easy way to write character arrays.
String literals are immutable (read only).
char[] str1 = "abc"; // error, "abc" is not mutable
char[] str2 = "abc".dup; // ok, make mutable copy
immutable(char)[] str3 = "abc"; // ok
immutable(char)[] str4 = str1; // error, str4 is not mutable
immutable(char)[] str5 = str1.idup; // ok, make immutable copy
The name string is aliased to immutable(char)[], so the above declarations could be equiva-
lently written as:
char[] str1 = "abc"; // error, "abc" is not mutable
char[] str2 = "abc".dup; // ok, make mutable copy
string str3 = "abc"; // ok
string str4 = str1; // error, str4 is not mutable
string str5 = str1.idup; // ok, make immutable copy
char[] strings are in UTF-8 format. wchar[] strings are in UTF-16 format. dchar[] strings
are in UTF-32 format.
Strings can be copied, compared, concatenated, and appended:
str1 = str2;
if (str1 < str3) { ... }
func(str3 ~ str4);
str4 ~= str1;
with the obvious semantics. Any generated temporaries get cleaned up by the garbage collector
(or by using alloca()). Not only that, this works with any array not just a special String array.
214 CHAPTER 12. ARRAYS

A pointer to a char can be generated:

char* p = &str[3]; // pointer to 4th element
char* p = str; // pointer to 1st element
Since strings, however, are not 0 terminated in D, when transferring a pointer to a string to C,
add a terminating 0:
str ~= "\0";
or use the function std.string.toStringz.
The type of a string is determined by the semantic phase of compilation. The type is one of:
char[], wchar[], dchar[], and is determined by implicit conversion rules. If there are two equally
applicable implicit conversions, the result is an error. To disambiguate these cases, a cast or a
postfix of c, w or d can be used:
cast(immutable(wchar) [])"abc" // this is an array of wchar characters
"abc"w // so is this
String literals that do not have a postfix character and that have not been cast can be implicitly
converted between string, wstring, and dstring as necessary.
char c;
wchar w;
dchar d;

c = ’b’; // c is assigned the character ’b’

w = ’b’; // w is assigned the wchar character ’b’
//w = ’bc’; // error - only one wchar character at a time
w = "b"[0]; // w is assigned the wchar character ’b’
w = "\r"[0]; // w is assigned the carriage return wchar character
d = ’d’; // d is assigned the character ’d’

Strings and Unicode

Note that built-in comparison operators operate on a code unit basis. The end result for valid
strings is the same as that of code point for code point comparison as long as both strings are in
the same normalization form. Since normalization is a costly operation not suitable for language
primitives it’s assumed to be enforced by the user.
The standard library lends a hand for comparing strings with mixed encodings (by transparently
decoding, see std.algorithm.cmp), case-insensitive comparison and normalization.
Last but not least, a desired string sorting order differs by culture and language and is usually
nothing like code point for code point comparison. The natural order of strings is obtained by
applying the Unicode collation algorithm that should be implemented in the standard library.
12.14. SPECIAL ARRAY TYPES 215

C’s printf() and Strings

printf() is a C function and is not part of D. printf() will print C strings, which are 0 terminated.
There are two ways to use printf() with D strings. The first is to add a terminating 0, and cast
the result to a char*:
str ~= "\0";
printf("the␣string␣is␣’%s’\n", cast(char*)str);
or:
import std.string;
printf("the␣string␣is␣’%s’\n", std.string.toStringz(str));
String literals already have a 0 appended to them, so can be used directly:
printf("the␣string␣is␣’%s’\n", cast(char*)"string␣literal");
So, why does the first string literal to printf not need the cast? The first parameter is prototyped
as a const(char)*, and a string literal can be implicitly cast to a const(char)*. The rest of the
arguments to printf, however, are variadic (specified by ...), and a string literal is passed as a
(length,pointer) combination to variadic parameters.
The second way is to use the precision specifier. The length comes first, followed by the pointer:
printf("the␣string␣is␣’%.*s’\n", str.length, str.ptr);
The best way is to use std.stdio.writefln, which can handle D strings:
import std.stdio;
writefln("the␣string␣is␣’%s’", str);

Void Arrays
There is a special type of array which acts as a wildcard that can hold arrays of any kind, declared
as void[]. Void arrays are used for low-level operations where some kind of array data is being
handled, but the exact type of the array elements are unimportant. The .length of a void array
is the length of the data in bytes, rather than the number of elements in its original type. Array
indices in indexing and slicing operations are interpreted as byte indices.
Arrays of any type can be implicitly converted to a void array; the compiler inserts the appro-
priate calculations so that the .length of the resulting array’s size is in bytes rather than number
of elements. Void arrays cannot be converted back to the original type without using a cast, and it
is an error to convert to an array type whose element size does not evenly divide the length of the
void array.
void main()
{
216 CHAPTER 12. ARRAYS

int[] data1 = [1,2,3];

long[] data2;

void[] arr = data1; // OK, int[] implicit converts to void[].

assert(data1.length == 3);
assert(arr.length == 12); // length is implicitly converted to bytes.

//data1 = arr; // Illegal: void[] does not implicitly

// convert to int[].
int[] data3 = cast(int[]) arr; // OK, can convert with explicit cast.
data2 = cast(long[]) arr; // Runtime error: long.sizeof == 8, which
// does not divide arr.length, which is 12
// bytes.
}
Void arrays can also be static if their length is known at compile-time. The length is specified
in bytes:
void main()
{
byte[2] x;
int[2] y;

void[2] a = x; // OK, lengths match

void[2] b = y; // Error: int[2] is 8 bytes long, doesn’t fit in 2 bytes.
}
While it may seem that void arrays are just fancy syntax for ubyte[], there is a subtle dis-
tinction. The garbage collector generally will not scan ubyte[] arrays for pointers, ubyte[] being
presumed to contain only pure byte data, not pointers. However, it will scan void[] arrays for
pointers, since such an array may have been implicitly converted from an array of pointers or an
array of elements that contain pointers. Allocating an array that contains pointers as ubyte[] may
run the risk of the GC collecting live memory if these pointers are the only remaining references to
their targets.

12.15 Implicit Conversions

A pointer T* can be implicitly converted to one of the following:

• void*

A static array T[dim] can be implicitly converted to one of the following:

12.15. IMPLICIT CONVERSIONS 217

• T[]
• const(U)[]
• const(U[])
• void[]

A dynamic array T[] can be implicitly converted to one of the following:

• const(U)[]
• const(U[])
• void[]

Where U is a base class of T.

Chapter 13

Associative Arrays

Associative arrays have an index that is not necessarily an integer, and can be sparsely populated.
The index for an associative array is called the key, and its type is called the KeyType.
Associative arrays are declared by placing the KeyType within the [ ] of an array declaration:
int[string] aa; // Associative array of ints that are
// indexed by string keys.
// The KeyType is string.
aa["hello"] = 3; // set value associated with key "hello" to 3
int value = aa["hello"]; // lookup value from a key
assert(value == 3);
Note: The built-in associative arrays do not preserve the order of the keys inserted into the
array. In particular, in a foreach loop the order in which the elements are iterated is unspecified.

Removing Keys
Particular keys in an associative array can be removed with the remove function:
aa.remove("hello");
remove(key) does nothing if the given key does not exist and returns false. If the given key
does exist, it removes it from the AA and returns true.

Testing Membership
The InExpression yields a pointer to the value if the key is in the associative array, or null if not:
int* p;

p = ("hello" in aa);

219
220 CHAPTER 13. ASSOCIATIVE ARRAYS

if (p !is null)
{
*p = 4; // update value associated with key
assert(aa["hello"] == 4);
}
Neither the KeyTypes nor the element types of an associative array can be function types or
void.

Using Classes as the KeyType

Classes can be used as the KeyType. For this to work, the class definition must override the following
member functions of class Object:

• size_t toHash() @trusted nothrow

• bool opEquals(Object)

Note that the parameter to opEquals is of type Object, not the type of the class in which it is
defined.
For example:
class Foo
{
int a, b;

override size_t toHash() { return a + b; }

override bool opEquals(Object o)

{
Foo foo = cast(Foo) o;
return foo && a == foo.a && b == foo.b;
}
}
Care should be taken that toHash should consistently be the same value when opEquals returns
true. In other words, two objects that are considered equal should always have the same hash
value. If this is not the case, the associative array will not function properly. Also note that opCmp
is not used to check for equality by the associative array. However, since the actual opEquals or
opCmp called is not decided until runtime, the compiler cannot always detect mismatched
functions. Because of legacy issues, the compiler may reject an associative array key type that
overrides opCmp but not opEquals. This restriction may be removed in future versions of D.
 221

Using Structs or Unions as the KeyType

If the KeyType is a struct or union type, a default mechanism is used to compute the hash and
comparisons of it based on the binary data within the struct value. A custom mechanism can be
used by providing the following functions as struct members:
size_t toHash() const @safe pure nothrow;
bool opEquals(ref const typeof(this) s) @safe pure nothrow;
For example:
import std.string;

struct MyString
{
string str;

size_t toHash() const @safe pure nothrow

{
size_t hash;
foreach (char c; str)
hash = (hash * 9) + c;
return hash;
}

bool opEquals(ref const MyString s) const @safe pure nothrow

{
return std.string.cmp(this.str, s.str) == 0;
}
}
Care should be taken that toHash should consistently be the same value when opEquals returns
true. In other words, two structs that are considered equal should always have the same hash value.
If this is not the case, the associative array will not function properly.
If necessary the functions can use @trusted instead of @safe.
Also note that opCmp is not used to check for equality by the associative array. For this reason,
and for legacy reasons, an associative array key is not allowed to define a specialized opCmp,
but omit a specialized opEquals. This restriction may be removed in future versions of D.

Construction or Assignment on Setting AA Entries

When an AA indexing access appears on the left side of an assignment operator, it is specially
handled for setting an AA entry associated with the key.
222 CHAPTER 13. ASSOCIATIVE ARRAYS

string[int] aa;
string s;
s = aa[1]; // throws RangeError in runtime
aa[1] = "hello"; // handled for setting AA entry
s = aa[1]; // succeeds to lookup
assert(s == "hello");
If the assigned value type is equivalent with the AA element type:

1. If the indexing key does not yet exist in AA, a new AA entry will be allocated, and it will be
initialized with the assigned value.
2. If the indexing key already exists in the AA, the setting runs normal assignment.

struct S
{
int val;
void opAssign(S rhs) { this.val = rhs.val * 2; }
}
S[int] aa;
aa[1] = S(10); // first setting initializes the entry aa[1]
assert(aa[1].val == 10);
aa[1] = S(10); // second setting invokes normal assignment, and
// operator-overloading rewrites it to member opAssign function.
assert(aa[1].val == 20);
If the assigned value type is not equivalent with the AA element type, the expression could
invoke operator overloading with normal indexing access:
struct S
{
int val;
void opAssign(int v) { this.val = v * 2; }
}
S[int] aa;
aa[1] = 10; // is rewritten to: aa[1].opAssign(10), and
// throws RangeError before opAssign is called
However, if the AA element type is a struct which supports an implicit constructor call from
the assigned value, implicit construction is used for setting the AA entry:
struct S
{
 223

int val;
this(int v) { this.val = v; }
void opAssign(int v) { this.val = v * 2; }
}
S s = 1; // OK, rewritten to: S s = S(1);
s = 1; // OK, rewritten to: s.opAssign(1);

S[int] aa;
aa[1] = 10; // first setting is rewritten to: aa[1] = S(10);
assert(aa[1].val == 10);
aa[1] = 10; // second setting is rewritten to: aa[1].opAssign(10);
assert(aa[1].val == 20);
This is designed for efficient memory reuse with some value-semantics structs, eg.
std.bigint.BigInt.
import std.bigint;
BigInt[string] aa;
aa["a"] = 10; // construct BigInt(10) and move it in AA
aa["a"] = 20; // call aa["a"].opAssign(20)

Runtime Initialization of Immutable AAs

Immutable associative arrays are often desirable, but sometimes initialization must be done at
runtime. This can be achieved with a constructor (static constructor depending on scope), a buffer
associative array and assumeUnique:
immutable long[string] aa;

static this()
{
import std.exception : assumeUnique;
import std.conv : to;

long[string] temp; // mutable buffer

foreach(i; 0 .. 10)
{
temp[to!string(i)] = i;
}
temp.rehash; // for faster lookups
224 CHAPTER 13. ASSOCIATIVE ARRAYS

aa = assumeUnique(temp);
}

unittest
{
assert(aa["1"] == 1);
assert(aa["5"] == 5);
assert(aa["9"] == 9);
}

Properties

Properties for associative arrays are:

 225

Associative Array Properties

Property Description
.sizeof Returns the size of the reference to the associative
array; it is 4 in 32-bit builds and 8 on 64-bit builds.
.length Returns number of values in the associative array.
Unlike for dynamic arrays, it is read-only.
.dup Create a new associative array of the same size
and copy the contents of the associative array into
it.
.keys Returns dynamic array, the elements of which are
the keys in the associative array.
.values Returns dynamic array, the elements of which are
the values in the associative array.
.rehash Reorganizes the associative array in place so that
lookups are more efficient. rehash is effective
when, for example, the program is done loading
up a symbol table and now needs fast lookups in
it. Returns a reference to the reorganized array.
.byKey() Returns a forward range suitable for use as a Fore-
achAggregate to a ForeachStatement which will it-
erate over the keys of the associative array.
.byValue() Returns a forward range suitable for use as a Fore-
achAggregate to a ForeachStatement which will it-
erate over the values of the associative array.
.byKeyValue() Returns a forward range suitable for use as a Fore-
achAggregate to a ForeachStatement which will it-
erate over key-value pairs of the associative array.
The returned pairs are represented by an opaque
type with .key and .value properties for access-
ing the key and value of the pair, respectively.
.get(Key key, lazy Value defVal) Looks up key; if it exists returns corresponding
value else evaluates and returns defVal.

<hr>

Associative Array Example: word count

Let’s consider the file is ASCII encoded with LF EOL. In general case we should use dchar c for
iteration over code points and functions from std.uni.
import std.file; // D file I/O
import std.stdio;
226 CHAPTER 13. ASSOCIATIVE ARRAYS

import std.ascii;

void main (string[] args)

{
ulong totalWords, totalLines, totalChars;
ulong[string] dictionary;

writeln("␣␣␣lines␣␣␣words␣␣␣bytes␣file");
foreach (arg; args[1 .. $]) // for each argument except the first one
{
ulong wordCount, lineCount, charCount;

foreach(line; File(arg).byLine())
{
bool inWord;
size_t wordStart;

void tryFinishWord(size_t wordEnd)

{
if (inWord)
{
auto word = line[wordStart .. wordEnd];
++dictionary[word.idup]; // increment count for word
inWord = false;
}
}

foreach (i, char c; line)

{
if (std.ascii.isDigit(c))
{
// c is a digit (0..9)
}
else if (std.ascii.isAlpha(c))
{
// c is an ASCII letter (A..Z, a..z)
if (!inWord)
{
wordStart = i;
inWord = true;
 227

++wordCount;
}
}
else
tryFinishWord(i);
++charCount;
}
tryFinishWord(line.length);
++lineCount;
}

writefln("%8s%8s%8s␣%s", lineCount, wordCount, charCount, arg);

totalWords += wordCount;
totalLines += lineCount;
totalChars += charCount;
}

if (args.length > 2)
{
writefln("-------------------------------------\n%8s%8s%8s␣total",
totalLines, totalWords, totalChars);
}

writeln("-------------------------------------");
foreach (word; dictionary.keys.sort)
{
writefln("%3s␣%s", dictionary[word], word);
}
}
Chapter 14

Structs and Unions

Whereas classes are reference types, structs are value types. Any C struct can be exactly represented
as a D struct, except non-static function-nested D structs which access the context of their enclosing
scope. Structs and unions are meant as simple aggregations of data, or as a way to paint a data
structure over hardware or an external type. External types can be defined by the operating system
API, or by a file format. Object oriented features are provided with the class data type.

A struct is defined to not have an identity; that is, the implementation is free to make bit copies
of the struct as convenient.

229
230 CHAPTER 14. STRUCTS AND UNIONS

Struct, Class Comparison Table

Feature struct class C struct C++ struct C++ class
value type ✓ ✓ ✓ ✓
reference type ✓
data members ✓ ✓ ✓ ✓ ✓
hidden members ✓ ✓ ✓ ✓
static members ✓ ✓ ✓ ✓
default member initializers ✓ ✓
bit fields ✓ ✓ ✓
non-virtual member functions ✓ ✓ ✓ ✓
virtual member functions ✓ ✓ ✓
constructors ✓ ✓ ✓ ✓
postblit/copy constructors ✓ ✓ ✓
destructors ✓ ✓ ✓ ✓
SharedStaticConstructor s ✓ ✓
SharedStaticDestructor s ✓ ✓
RAII ✓ ✓ ✓ ✓
identity assign overload ✓ ✓ ✓
literals ✓
operator overloading ✓ ✓ ✓ ✓
inheritance ✓ ✓ ✓
invariants ✓ ✓
unit tests ✓ ✓
synchronizable ✓
parameterizable ✓ ✓ ✓ ✓
alignment control ✓ ✓
member protection ✓ ✓ ✓ ✓
default public ✓ ✓ ✓ ✓
tag name space ✓ ✓ ✓
anonymous ✓ ✓ ✓ ✓
static constructor ✓ ✓
static destructor ✓ ✓
const/immutable/shared ✓ ✓
inner nesting ✓ ✓

AggregateDeclaration:
ClassDeclaration
InterfaceDeclaration
StructDeclaration
 231

UnionDeclaration

StructDeclaration:
struct Identifier ;
struct Identifier AggregateBody
StructTemplateDeclaration
AnonStructDeclaration

AnonStructDeclaration:
struct AggregateBody

UnionDeclaration:
union Identifier ;
union Identifier AggregateBody
UnionTemplateDeclaration
AnonUnionDeclaration

AnonUnionDeclaration:
union AggregateBody

AggregateBody:
{ DeclDefs opt }

They work like they do in C, with the following exceptions:

• no bit fields
• alignment can be explicitly specified
• no separate tag name space - tag names go into the current scope
• declarations like:

struct ABC x;

are not allowed, replace with:

ABC x;

• anonymous structs/unions are allowed as members of other structs/unions

• Default initializers for members can be supplied.
• Member functions and static members are allowed.
232 CHAPTER 14. STRUCTS AND UNIONS

Opaque Structs and Unions

Opaque struct and union declarations do not have a AggregateBody:
struct S;
union U;
The members are completely hidden to the user, and so the only operations on those types are
ones that do not require any knowledge of the contents of those types. For example:
struct S;
S.sizeof; // error, size is not known
S s; // error, cannot initialize unknown contents
S* p; // ok, knowledge of members is not necessary
They can be used to implement the PIMPL idiom.

Static Initialization of Structs

Static struct members are by default initialized to whatever the default initializer for the member is,
and if none supplied, to the default initializer for the member’s type. If a static initializer is supplied,
the members are initialized by the member name, colon, expression syntax. The members may be
initialized in any order. Initializers for statics must be evaluatable at compile time. Members not
specified in the initializer list are default initialized.
struct S { int a; int b; int c; int d = 7;}
static S x = { a:1, b:2}; // c is set to 0, d to 7
static S z = { c:4, b:5, a:2 , d:5}; // z.a = 2, z.b = 5, z.c = 4, z.d = 5
C-style initialization, based on the order of the members in the struct declaration, is also sup-
ported:
static S q = { 1, 2 }; // q.a = 1, q.b = 2, q.c = 0, q.d = 7
Struct literals can also be used to initialize statics, but they must be evaluable at compile time.
static S q = S( 1, 2+3 ); // q.a = 1, q.b = 5, q.c = 0, q.d = 7
The static initializer syntax can also be used to initialize non-static variables, provided that the
member names are not given. The initializer need not be evaluatable at compile time.
void test(int i)
{
S q = { 1, i }; // q.a = 1, q.b = i, q.c = 0, q.d = 7
}
 233

Static Initialization of Unions

Unions are initialized explicitly.
union U { int a; double b; }
static U u = { b : 5.0 }; // u.b = 5.0
Other members of the union that overlay the initializer, but occupy more storage, have the extra
storage initialized to zero.

Dynamic Initialization of Structs

Structs can be dynamically initialized from another value of the same type:
struct S { int a; }
S t; // default initialized
t.a = 3;
S s = t; // s.a is set to 3
If opCall is overridden for the struct, and the struct is initialized with a value that is of a
different type, then the opCall operator is called:
struct S
{
int a;

static S opCall(int v)
{
S s;
s.a = v;
return s;
}

static S opCall(S v)
{
S s;
s.a = v.a + 1;
return s;
}
}

S s = 3; // sets s.a to 3
S t = s; // sets t.a to 3, S.opCall(s) is not called
234 CHAPTER 14. STRUCTS AND UNIONS

Struct Literals
Struct literals consist of the name of the struct followed by a parenthesized argument list:
struct S { int x; float y; }

int foo(S s) { return s.x; }

foo( S(1, 2) ); // set field x to 1, field y to 2

Struct literals are syntactically like function calls. If a struct has a member function named
opCall, then struct literals for that struct are not possible. See also opCall operator overloading for
the issue workaround. It is an error if there are more arguments than fields of the struct. If there
are fewer arguments than fields, the remaining fields are initialized with their respective default
initializers. If there are anonymous unions in the struct, only the first member of the anonymous
union can be initialized with a struct literal, and all subsequent non-overlapping fields are default
initialized.

Struct Properties
Struct Properties
Name Description
.sizeof Size in bytes of struct
.alignof Size boundary struct needs to be aligned on
.tupleof Gets type tuple of fields

Struct Field Properties

Struct Field Properties
Name Description
.offsetof Offset in bytes of field from beginning of struct

Const, Immutable and Shared Structs

A struct declaration can have a storage class of const, immutable or shared. It has an equivalent
effect as declaring each member of the struct as const, immutable or shared.
const struct S { int a; int b = 2; }

void main()
{
 235

S s = S(3); // initializes s.a to 3

S t; // initializes t.a to 0
t = s; // error, t.a and t.b are const, so cannot modify them.
t.a = 4; // error, t.a is const
}

Struct Constructors
Struct constructors are used to initialize an instance of a struct. The ParameterList may not be
empty. Struct instances that are not instantiated with a constructor are default initialized to their
.init value.
struct S
{
int x, y;

this() // error, cannot implement default ctor for structs

{
}

this(int a, int b)
{
x = a;
y = b;
}
}

void main()
{
S a = S(4, 5);
auto b = S(); // same as auto b = S.init;
}
A constructor qualifier allows the object to be constructed with that specific qualifier.
struct S1
{
int[] a;
this(int n) { a = new int[](n); }
}
struct S2
236 CHAPTER 14. STRUCTS AND UNIONS

{
int[] a;
this(int n) immutable { a = new int[](n); }
}
void main()
{
// Mutable constructor creates mutable object.
S1 m1 = S1(1);

// Constructed mutable object is implicitly convertible to const.

const S1 c1 = S1(1);

// Constructed mutable object is not implicitly convertible to immutable.

// immutable i1 = S1(1);

// Mutable constructor cannot construct immutable object.

// auto x1 = immutable S1(1);

// Immutable constructor cannot construct mutable object.

// auto x2 = S2(1);

// Constructed immutable object is not implicitly convertible to mutable.

// S2 m2 = immutable S2(1);

// Constructed immutable object is implicitly convertible to const.

const S2 c2 = immutable S2(1);

// Immutable constructor creates immutable object.

immutable i2 = immutable S2(1);
}
If struct constructor is annotated with @disable and has empty parameter, the struct is disabled
construction without calling other constructor.
struct S
{
int x;

// Disables default construction, function body can be empty.

@disable this();
 237

this(int v) { x = v; }
}
void main()
{
//S s; // default construction is disabled
//S s = S(); // also disabled
S s = S(1); // construction with calling constructor
}

Struct Postblits
Postblit:
this ( this ) MemberFunctionAttributes opt ;
this ( this ) MemberFunctionAttributes opt FunctionBody

Copy construction is defined as initializing a struct instance from another struct of the same
type. Copy construction is divided into two parts:

1. blitting the fields, i.e. copying the bits

2. running postblit on the result

The first part is done automatically by the language, the second part is done if a postblit
function is defined for the struct. The postblit has access only to the destination struct object, not
the source. Its job is to ‘fix up’ the destination as necessary, such as making copies of referenced
data, incrementing reference counts, etc. For example:
struct S
{
int[] a; // array is privately owned by this instance
this(this)
{
a = a.dup;
}
}
Disabling struct postblit makes the object not copyable.
struct T
{
@disable this(this); // disabling makes T not copyable
}
238 CHAPTER 14. STRUCTS AND UNIONS

struct S
{
T t; // uncopyable member makes S also not copyable
}

void main()
{
S s;
S t = s; // error, S is not copyable
}
Unions may not have fields that have postblits.

Struct Destructors
Destructors are called when an object goes out of scope. Their purpose is to free up resources owned
by the struct object.
Unions may not have fields that have destructors.

Identity Assignment Overload

While copy construction takes care of initializing an object from another object of the same type,
or elaborate destruction is needed for the type, assignment is defined as copying the contents of one
object over another, already initialized, type:
struct S { ... } // S has postblit or destructor
S s; // default construction of s
S t = s; // t is copy-constructed from s
t = s; // t is assigned from s
Struct assignment t=s is defined to be semantically equivalent to:
t.opAssign(s);
where opAssign is a member function of S:
ref S opAssign(S s)
{
S tmp = this; // bitcopy this into tmp
this = s; // bitcopy s into this
tmp.__dtor(); // call destructor on tmp
return this;
}
14.1. NESTED STRUCTS 239

While the compiler will generate a default opAssign as needed, a user-defined one can be
supplied. The user-defined one must still implement the equivalent semantics, but can be more
efficient.
One reason a custom opAssign might be more efficient is if the struct has a reference to a local
buffer:
struct S
{
int[] buf;
int a;

ref S opAssign(ref const S s)

{
a = s.a;
return this;
}

this(this)
{
buf = buf.dup;
}
}
Here, S has a temporary workspace buf[]. The normal postblit will pointlessly free and reallo-
cate it. The custom opAssign will reuse the existing storage.

14.1 Nested Structs

A nested struct is a struct that is declared inside the scope of a function or a templated struct that
has aliases to local functions as a template argument. Nested structs have member functions. It
has access to the context of its enclosing scope (via an added hidden field).
void foo()
{
int i = 7;
struct SS
{
int x,y;
int bar() { return x + i + 1; }
}
SS s;
240 CHAPTER 14. STRUCTS AND UNIONS

s.x = 3;
s.bar(); // returns 11
}
A struct can be prevented from being nested by using the static attribute, but then of course it
will not be able to access variables from its enclosing scope.
void foo()
{
int i = 7;
static struct SS
{
int x, y;
int bar()
{
return i; // error, SS is not a nested struct
}
}
}

14.2 Unions and Special Member Functions

Unions may not have postblits, destructors, or invariants.
Chapter 15

Classes

The object-oriented features of D all come from classes. The class hierarchy has as its root the class
Object. Object defines a minimum level of functionality that each derived class has, and a default
implementation for that functionality.
Classes are programmer defined types. Support for classes are what make D an object oriented
language, giving it encapsulation, inheritance, and polymorphism. D classes support the single
inheritance paradigm, extended by adding support for interfaces. Class objects are instantiated by
reference only.
A class can be exported, which means its name and all its non-private members are exposed
externally to the DLL or EXE.
A class declaration is defined:

ClassDeclaration:
class Identifier ;
class Identifier BaseClassList opt AggregateBody
ClassTemplateDeclaration

BaseClassList:
: SuperClass
: SuperClass , Interfaces
: Interfaces

SuperClass:
BasicType

Interfaces:
Interface
Interface , Interfaces

241
242 CHAPTER 15. CLASSES

Interface:
BasicType

Classes consist of:

• a super class
• interfaces
• dynamic fields
• static fields
• types
• an optional synchronized attribute
• member functions
– static member functions
– Virtual Functions
– Constructors
– Destructors
– Static Constructors
– Static Destructors
– SharedStaticConstructor s
– SharedStaticDestructor s
– Class Invariants
– Unit Tests
– Class Allocators
– Class Deallocators
– Alias This

A class is defined:
class Foo
{
... members ...
}
Note that there is no trailing ; after the closing } of the class definition. It is also not possible
to declare a variable var like:
class Foo { } var;
Instead:
 243

class Foo { }
Foo var;

Access Control
Access to class members is controlled using ProtectionAttributes. The default protection attribute
is public. Access control does not affect visibility.

Fields
Class members are always accessed with the . operator.
Members of a base class can be accessed by prepending the name of the base class followed by
a dot:
class A { int a; }
class B : A { int a; }

void foo(B b)
{
b.a = 3; // accesses field B.a
b.A.a = 4; // accesses field A.a
}
The D compiler is free to rearrange the order of fields in a class to optimally pack them in an
implementation-defined manner. Consider the fields much like the local variables in a function -
the compiler assigns some to registers and shuffles others around all to get the optimal stack frame
layout. This frees the code designer to organize the fields in a manner that makes the code more
readable rather than being forced to organize it according to machine optimization rules. Explicit
control of field layout is provided by struct/union types, not classes.

Field Properties
The .offsetof property gives the offset in bytes of the field from the beginning of the class instan-
tiation. .offsetof can only be applied to expressions which produce the type of the field itself,
not the class type:
class Foo
{
int x;
}
...
void test(Foo foo)
244 CHAPTER 15. CLASSES

{
size_t o;

o = Foo.x.offsetof; // error, Foo.x needs a ’this’ reference

o = foo.x.offsetof; // ok
}

Class Properties
The .tupleof property returns an ExpressionTuple of all the fields in the class, excluding the hidden
fields and the fields in the base class.
class Foo { int x; long y; }
void test(Foo foo)
{
foo.tupleof[0] = 1; // set foo.x to 1
foo.tupleof[1] = 2; // set foo.y to 2
foreach (x; foo.tupleof)
write(x); // prints 12
}
The properties .__vptr and .__monitor give access to the class object’s vtbl[] and monitor,
respectively, but should not be used in user code.

Super Class
All classes inherit from a super class. If one is not specified, it inherits from Object. Object forms
the root of the D class inheritance hierarchy.

Member Functions
Non-static member functions have an extra hidden parameter called this through which the class
object’s other members can be accessed.
Non-static member functions can have, in addition to the usual FunctionAttributes, the at-
tributes const, immutable, shared, or inout. These attributes apply to the hidden this parameter.
class C
{
int a;
const void foo()
{
a = 3; // error, ’this’ is const
 245

}
void foo() immutable
{
a = 3; // error, ’this’ is immutable
}
}

Synchronized Classes
All member functions of synchronized classes are synchronized. A static member function is syn-
chronized on the classinfo object for the class, which means that one monitor is used for all static
member functions for that synchronized class. For non-static functions of a synchronized class, the
monitor used is part of the class object. For example:
synchronized class Foo
{
void bar() { ...statements... }
}
is equivalent to (as far as the monitors go):
synchronized class Foo
{
void bar()
{
synchronized (this) { ...statements... }
}
}
Member functions of non-synchronized classes cannot be individually marked as synchronized.
The synchronized attribute must be applied to the class declaration itself:
class Foo
{
synchronized void foo() { } // disallowed!
}

synchronized class Bar

{
void bar() { } // bar is synchronized
}
Member fields of a synchronized class cannot be public:
246 CHAPTER 15. CLASSES

synchronized class Foo

{
int foo; // disallowed: public field
}

synchronized class Bar

{
private int bar; // ok
}
The synchronized attribute can only be applied to classes, structs cannot be marked to be
synchronized.

Constructors
Constructor:
this Parameters MemberFunctionAttributes opt ;
this Parameters MemberFunctionAttributes opt FunctionBody
ConstructorTemplate

Members are always initialized to the default initializer for their type, which is usually 0 for
integer types and NAN for floating point types. This eliminates an entire class of obscure problems
that come from neglecting to initialize a member in one of the constructors. In the class definition,
there can be a static initializer to be used instead of the default:
class Abc
{
int a; // default initializer for a is 0
long b = 7; // default initializer for b is 7
float f; // default initializer for f is NAN
}
This static initialization is done before any constructors are called.
Constructors are defined with a function name of this and having no return value:
class Foo
{
this(int x) // declare constructor for Foo
{ ...
}
this()
{ ...
 247

}
}
Base class construction is done by calling the base class constructor by the name super:
class A { this(int y) { } }

class B : A
{
int j;
this()
{
...
super(3); // call base constructor A.this(3)
...
}
}
Constructors can also call other constructors for the same class in order to share common
initializations (this is called delegating constructors):
class C
{
int j;
this()
{
...
}
this(int i)
{
this();
j = i;
}
}
If no call to constructors via this or super appear in a constructor, and the base class has a
constructor, a call to super() is inserted at the beginning of the constructor.
If there is no constructor for a class, but there is a constructor for the base class, a default
constructor of the form:
this() { }
is implicitly generated.
Class object construction is very flexible, but some restrictions apply:
248 CHAPTER 15. CLASSES

1. It is illegal for constructors to mutually call each other, although the compiler is not required
to detect it. It will result in undefined behavior.
this() { this(1); }
this(int i) { this(); } // illegal, cyclic constructor calls
2. If any constructor call appears inside a constructor, any path through the constructor must
make exactly one constructor call:
this() { a || super(); } // illegal

this() { (a) ? this(1) : super(); } // ok

this()
{
for (...)
{
super(); // illegal, inside loop
}
}
3. It is illegal to refer to this implicitly or explicitly prior to making a constructor call.
4. Constructor calls cannot appear after labels (in order to make it easy to check for the previous
conditions in the presence of goto’s).

Instances of class objects are created with NewExpressions:

A a = new A(3);
The following steps happen:

1. Storage is allocated for the object. If this fails, rather than return null, an OutOfMemoryError
is thrown. Thus, tedious checks for null references are unnecessary.
2. The raw data is statically initialized using the values provided in the class definition. The
pointer to the vtbl[] (the array of pointers to virtual functions) is assigned. This ensures that
constructors are passed fully formed objects for which virtual functions can be called. This
operation is equivalent to doing a memory copy of a static version of the object onto the newly
allocated one, although more advanced compilers may be able to optimize much of this away.
3. If there is a constructor defined for the class, the constructor matching the argument list is
called.
4. If class invariant checking is turned on, the class invariant is called at the end of the construc-
tor.
 249

Constructors can have one of these member function attributes: const, immutable, and shared.
Construction of qualified objects will then be restricted to the implemented qualified constructors.
class C
{
this(); // non-shared mutable constructor
}

// create mutable object

C m = new C();

// create const object using by mutable constructor

const C c2 = new const C();

// a mutable constructor cannot create an immutable object

// immutable C i = new immutable C();

// a mutable constructor cannot create a shared object

// shared C s = new shared C();
Constructors can be overloaded with different attributes.
class C
{
this(); // non-shared mutable constructor
this() shared; // shared mutable constructor
this() immutable; // immutable constructor
}

C m = new C();
shared s = new shared C();
immutable i = new immutable C();
If the constructor can create unique object (e.g. if it is pure), the object can be implicitly
convertible to any qualifiers.
class C
{
this() pure;
// Based on the definition, this creates a mutable object. But the
// created object cannot contain any mutable global data.
// Then compiler can guarantee that the created object is unique.
250 CHAPTER 15. CLASSES

this(int[] arr) immutable pure;

// Based on the definition, this creates an immutable object. But
// the argument int[] never appears in the created object so it
// isn’t implicitly convertible to immutable. Also, it cannot store
// any immutable global data.
// Therefore the compiler can guarantee that the created object is
// unique.
}

immutable i = new immutable C(); // this() pure is called

shared s = new shared C(); // this() pure is called
C m = new C([1,2,3]); // this(int[]) immutable pure is called

Field initialization inside constructor

Inside constructor, the first instance field assignment is specially handled for its initialization.
class C
{
int num;
this()
{
num = 1; // initialize
num = 2; // assignment
}
}
If the field type has opAssign method, it won’t be used for initialization.
struct A
{
this(int n) {}
void opAssign(A rhs) {}
}
class C
{
A val;
this()
{
val = A(1); // A(1) is moved in this.val for initializing
val = A(2); // rewritten to val.opAssign(A(2))
 251

}
}
If the field type is not modifiable, multiple initialization will be rejected.
class C
{
immutable int num;
this()
{
num = 1; // OK
num = 2; // Error: multiple field initialization
}
}
If the assignment expression for the field initialization may be invoked multiple times, it would
als be rejected.
class C
{
immutable int num;
immutable string str;
this()
{
foreach (i; 0..2)
{
num = 1; // Error: field initialization not allowed in loops
}
size_t i = 0;
Label:
str = "hello"; // Error: field initialization not allowed after labels
if (i++ < 2)
goto Label;
}
}

Destructors
Destructor:
~ this ( ) MemberFunctionAttributes opt ;
~ this ( ) MemberFunctionAttributes opt FunctionBody
252 CHAPTER 15. CLASSES

The garbage collector calls the destructor function when the object is deleted. The syntax is:
class Foo
{
~this() // destructor for Foo
{
}
}
There can be only one destructor per class, the destructor does not have any parameters, and
has no attributes. It is always virtual.
The destructor is expected to release any resources held by the object.
The program can explicitly inform the garbage collector that an object is no longer referred to
(with the delete expression), and then the garbage collector calls the destructor immediately, and
adds the object’s memory to the free storage. The destructor is guaranteed to never be called twice.
The destructor for the super class automatically gets called when the destructor ends. There is
no way to call the super destructor explicitly.
The garbage collector is not guaranteed to run the destructor for all unreferenced objects.
Furthermore, the order in which the garbage collector calls destructors for unreference objects is
not specified. This means that when the garbage collector calls a destructor for an object of a class
that has members that are references to garbage collected objects, those references may no longer
be valid. This means that destructors cannot reference sub objects. This rule does not apply to
auto objects or objects deleted with the DeleteExpression, as the destructor is not being run by the
garbage collector, meaning all references are valid.
Objects referenced from the data segment never get collected by the gc.

Static Constructors
StaticConstructor:
static this ( ) ;
static this ( ) FunctionBody

A static constructor is a function that performs initializations of thread local data before the
main() function gets control for the main thread, and upon thread startup.
Static constructors are used to initialize static class members with values that cannot be com-
puted at compile time.
Static constructors in other languages are built implicitly by using member initializers that
can’t be computed at compile time. The trouble with this stems from not having good control over
exactly when the code is executed, for example:
class Foo
 253

{
static int a = b + 1;
static int b = a * 2;
}
What values do a and b end up with, what order are the initializations executed in, what are
the values of a and b before the initializations are run, is this a compile error, or is this a runtime
error? Additional confusion comes from it not being obvious if an initializer is static or dynamic.
D makes this simple. All member initializations must be determinable by the compiler at
compile time, hence there is no order-of-evaluation dependency for member initializations, and it is
not possible to read a value that has not been initialized. Dynamic initialization is performed by a
static constructor, defined with a special syntax static this().
class Foo
{
static int a; // default initialized to 0
static int b = 1;
static int c = b + a; // error, not a constant initializer

static this() // static constructor

{
a = b + 1; // a is set to 2
b = a * 2; // b is set to 4
}
}
If main() or the thread returns normally, (does not throw an exception), the static destructor
is added to the list of functions to be called on thread termination.
Static constructors have empty parameter lists.
Static constructors within a module are executed in the lexical order in which they appear. All
the static constructors for modules that are directly or indirectly imported are executed before the
static constructors for the importer.
The static in the static constructor declaration is not an attribute, it must appear immediately
before the this:
class Foo
{
static this() { ... } // a static constructor
static private this() { ... } // not a static constructor
static
{
this() { ... } // not a static constructor
254 CHAPTER 15. CLASSES

}
static:
this() { ... } // not a static constructor
}

Static Destructors
StaticDestructor:
static ~ this ( ) MemberFunctionAttributes opt ;
static ~ this ( ) MemberFunctionAttributes opt FunctionBody

A static destructor is defined as a special static function with the syntax static ~this().
class Foo
{
static ~this() // static destructor
{
}
}
A static destructor gets called on thread termination, but only if the static constructor completed
successfully. Static destructors have empty parameter lists. Static destructors get called in the
reverse order that the static constructors were called in.
The static in the static destructor declaration is not an attribute, it must appear immediately
before the ~this:
class Foo
{
static ~this() { ... } // a static destructor
static private ~this() { ... } // not a static destructor
static
{
~this() { ... } // not a static destructor
}
static:
~this() { ... } // not a static destructor
}

Shared Static Constructors

SharedStaticConstructor:
 255

shared static this ( ) ;

shared static this ( ) FunctionBody

Shared static constructors are executed before any StaticConstructor s, and are intended for
initializing any shared global data.

Shared Static Destructors

SharedStaticDestructor:
shared static ~ this ( ) MemberFunctionAttributes opt ;
shared static ~ this ( ) MemberFunctionAttributes opt FunctionBody

Shared static destructors are executed at program termination in the reverse order that Shared-
StaticConstructor s were executed.

Class Invariants
Invariant:
invariant ( ) BlockStatement
invariant BlockStatement

Class invariants are used to specify characteristics of a class that always must be true (except
while executing a member function). They are described in Invariants.

Class Allocators
Note: Class allocators are deprecated in D2.

Allocator:
new Parameters ;
new Parameters FunctionBody

A class member function of the form:

new(uint size)
{
...
}
256 CHAPTER 15. CLASSES

is called a class allocator. The class allocator can have any number of parameters, provided the
first one is of type uint. Any number can be defined for a class, the correct one is determined by
the usual function overloading rules. When a new expression:
new Foo;

is executed, and Foo is a class that has an allocator, the allocator is called with the first argument
set to the size in bytes of the memory to be allocated for the instance. The allocator must allocate
the memory and return it as a void*. If the allocator fails, it must not return a null, but must
throw an exception. If there is more than one parameter to the allocator, the additional arguments
are specified within parentheses after the new in the NewExpression:
class Foo
{
this(char[] a) { ... }

new(uint size, int x, int y)

{
...
}
}

...

new(1,2) Foo(a); // calls new(Foo.sizeof,1,2)

Derived classes inherit any allocator from their base class, if one is not specified.
The class allocator is not called if the instance is created on the stack.
See also

Class Deallocators
Note: Class deallocators and the delete operator are deprecated in D2. Use the destroy function
to finalize an object by calling its destructor. The memory of the object is not immediately
deallocated, instead the GC will collect the memory of the object at an undetermined point after
finalization:
class Foo { int x; this() { x = 1; } }
Foo foo = new Foo;
destroy(foo);
assert(foo.x == int.init); // object is still accessible
 257

Deallocator:
delete Parameters ;
delete Parameters FunctionBody

A class member function of the form:

delete(void *p)
{
...
}
is called a class deallocator. The deallocator must have exactly one parameter of type void*.
Only one can be specified for a class. When a delete expression:
delete f;
is executed, and f is a reference to a class instance that has a deallocator, the deallocator is
called with a pointer to the class instance after the destructor (if any) for the class is called. It is
the responsibility of the deallocator to free the memory.
Derived classes inherit any deallocator from their base class, if one is not specified.
The class allocator is not called if the instance is created on the stack.
See also Explicit Class Instance Allocation.

Alias This
AliasThis:
alias Identifier this ;

An AliasThis declaration names a member to subtype. The Identifier names that member.
A class or struct can be implicitly converted to the AliasThis member.
struct S
{
int x;
alias x this;
}

int foo(int i) { return i * 2; }

void test()
{
258 CHAPTER 15. CLASSES

S s;
s.x = 7;
int i = -s; // i == -7
i = s + 8; // i == 15
i = s + s; // i == 14
i = 9 + s; // i == 16
i = foo(s); // implicit conversion to int
}
If the member is a class or struct, undefined lookups will be forwarded to the AliasThis member.
struct Foo
{
int baz = 4;
int get() { return 7; }
}

class Bar
{
Foo foo;
alias foo this;
}

void test()
{
auto bar = new Bar;
int i = bar.baz; // i == 4
i = bar.get(); // i == 7
}
If the Identifier refers to a property member function with no parameters, conversions and
undefined lookups are forwarded to the return value of the function.
struct S
{
int x;
@property int get()
{
return x * 2;
}
alias get this;
}
 259

void test()
{
S s;
s.x = 2;
int i = s; // i == 4
}

Multiple AliasThis are allowed. For implicit conversions and forwarded lookups, all AliasThis
declarations are attempted; if more than one AliasThis is eligible, the ambiguity is disallowed by
raising an error. Note: Multiple AliasThis is currently unimplemented.

Scope Classes
Note: Scope classes have been recommended for deprecation.
A scope class is a class with the scope attribute, as in:

scope class Foo { ... }

The scope characteristic is inherited, so any classes derived from a scope class are also scope.
A scope class reference can only appear as a function local variable. It must be declared as
being scope:

scope class Foo { ... }

void func()
{
Foo f; // error, reference to scope class must be scope
scope Foo g = new Foo(); // correct
}

When a scope class reference goes out of scope, the destructor (if any) for it is automatically
called. This holds true even if the scope was exited via a thrown exception.

Final Classes
Final classes cannot be subclassed:

final class A { }
class B : A { } // error, class A is final
260 CHAPTER 15. CLASSES

15.1 Nested Classes

A nested class is a class that is declared inside the scope of a function or another class. A nested
class has access to the variables and other symbols of the classes and functions it is nested inside:
class Outer
{
int m;

class Inner
{
int foo()
{
return m; // Ok to access member of Outer
}
}
}

void func()
{
int m;

class Inner
{
int foo()
{
return m; // Ok to access local variable m of func()
}
}
}
If a nested class has the static attribute, then it can not access variables of the enclosing scope
that are local to the stack or need a this:
class Outer
{
int m;
static int n;

static class Inner

{
int foo()
15.1. NESTED CLASSES 261

{
return m; // Error, Inner is static and m needs a this
return n; // Ok, n is static
}
}
}

void func()
{
int m;
static int n;

static class Inner

{
int foo()
{
return m; // Error, Inner is static and m is local to the stack
return n; // Ok, n is static
}
}
}
Non-static nested classes work by containing an extra hidden member (called the context pointer)
that is the frame pointer of the enclosing function if it is nested inside a function, or the this of
the enclosing class’s instance if it is nested inside a class.
When a non-static nested class is instantiated, the context pointer is assigned before the class’s
constructor is called, therefore the constructor has full access to the enclosing variables. A non-static
nested class can only be instantiated when the necessary context pointer information is available:
class Outer
{
class Inner { }

static class SInner { }

}

void func()
{
class Nested { }

Outer o = new Outer; // Ok

262 CHAPTER 15. CLASSES

Outer.Inner oi = new Outer.Inner; // Error, no ’this’ for Outer

Outer.SInner os = new Outer.SInner; // Ok

Nested n = new Nested; // Ok

}
A this can be supplied to the creation of an inner class instance by prefixing it to the NewEx-
pression:
class Outer
{
int a;

class Inner
{
int foo()
{
return a;
}
}
}

int bar()
{
Outer o = new Outer;
o.a = 3;
Outer.Inner oi = o.new Inner;
return oi.foo(); // returns 3
}
Here o supplies the this to the outer class instance of Outer.
The property .outer used in a nested class gives the this pointer to its enclosing class. If the
enclosing context is not a class, the .outer will give the pointer to it as a void* type.
class Outer
{
class Inner
{
Outer foo()
{
return this.outer;
}
15.1. NESTED CLASSES 263

void bar()
{
Inner i = new Inner;
assert(this == i.foo());
}
}

void test()
{
Outer o = new Outer;
o.bar();
}

Anonymous Nested Classes

An anonymous nested class is both defined and instantiated with a NewAnonClassExpression:

NewAnonClassExpression:
new AllocatorArguments opt class ClassArguments opt SuperClass opt Interfaces opt AggregateBody

ClassArguments:
( ArgumentList opt )

which is equivalent to:

\lstinline|class| \textit{Identifier} \lstinline|:| \textit{SuperClass} ⤦
Ç \textit{Interfaces} \textit{AggregateBody}

\lstinline|new| \lstinline|(|\textit{ArgumentList}\lstinline|)| ⤦
Ç \textit{Identifier} \lstinline|(|\textit{ArgumentList}\lstinline|)|;
where Identifier is the name generated for the anonymous nested class.

Const, Immutable and Shared Classes

If a ClassDeclaration has a const, immutable or shared storage class, then it is as if each member
of the class was declared with that storage class. If a base class is const, immutable or shared, then
all classes derived from it are also const, immutable or shared.
Chapter 16

Interfaces

InterfaceDeclaration:
interface Identifier ;
interface Identifier BaseInterfaceList opt AggregateBody
InterfaceTemplateDeclaration

BaseInterfaceList:
: Interfaces

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.
Some operating system objects, like COM/OLE/ActiveX for Win32, have specialized interfaces.
D interfaces that are compatible with COM/OLE/ActiveX are called COM Interfaces.
C++ Interfaces are another form of interfaces, meant to be binary compatible with C++.
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

265
266 CHAPTER 16. INTERFACES

{
void foo();
}

...

D d = new D(); // error, cannot create instance of interface

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
}
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()
}
All interface functions must be defined in a class that inherits from that interface:
interface D
{
void foo();
}

class A : D
{
 267

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;
Interfaces can be reimplemented in derived classes:
interface D
{
int foo();
}

class A : D
{
int foo() { return 1; }
268 CHAPTER 16. INTERFACES

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
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

16.1 Interfaces with Contracts

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
16.2. CONST AND IMMUTABLE INTERFACES 269

{
int foo(int i)
in { assert(i > 7); }
out (result) { assert(result & 1); }

void bar();
}

16.2 Const and Immutable Interfaces

If an interface has const or immutable storage class, then all members of the interface are const
or immutable. This storage class is not inherited.

16.3 COM Interfaces

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.
A COM interface is defined as one that derives from the interface core.stdc.win-
dows.com.IUnknown. A COM interface differs from a regular D interface in that:

• It derives from the interface core.stdc.windows.com.IUnknown.

• It cannot be the argument of a DeleteExpression.
• References cannot be upcast to the enclosing class object, nor can they be downcast to a
derived interface. To accomplish this, an appropriate QueryInterface() would have to be
implemented for that interface in standard COM fashion.
• Classes derived from COM interfaces are COM classes.
• The default linkage for member functions of COM classes is extern(System).
Note that if you want to implement or override any base-class methods of D interfaces or
classes (ones which do not inherit from IUnknown), you have to explicitly mark them as
having the extern(D) linkage:
import core.sys.windows.windows;
import core.stdc.windows.com;

interface IText
{
void write();
}
270 CHAPTER 16. INTERFACES

abstract class Printer : IText

{
void print() { }
}

class C : Printer, IUnknown

{
// Implements the IText \$(D write) class method.
extern(D) void write() { }

// Overrides the Printer \$(D print) class method.

extern(D) override void print() { }

// Overrides the Object base class \$(D toString) method.

extern(D) override string toString() { return "Class␣C"; }

// Methods of class implementing the IUnknown interface have

// the extern(System) calling convention by default.
HRESULT QueryInterface(const(IID)*, void**);
uint AddRef();
uint Release();
}
The same applies to other Object methods such as opCmp, toHash, etc.
• The first member of the vtbl[] is not the pointer to the InterfaceInfo, but the first virtual
function pointer.

For more information, see Modern COM Programming in D

16.4 C++ Interfaces

C++ interfaces are interfaces declared with C++ linkage:
extern (C++) interface Ifoo
{
void foo();
void bar();
}
which is meant to correspond with the following C++ declaration:
16.4. C++ INTERFACES 271

class Ifoo
{
virtual void foo();
virtual void bar();
};
Any interface that derives from a C++ interface is also a C++ interface. A C++ interface
differs from a D interface in that:

• It cannot be the argument of a DeleteExpression.

• References cannot be upcast to the enclosing class object, nor can they be downcast to a
derived interface.
• The C++ calling convention is the default convention for its member functions, rather than
the D calling convention.
• The first member of the vtbl[] is not the pointer to the Interface, but the first virtual
function pointer.
Chapter 17

Enums

EnumDeclaration:
enum Identifier EnumBody
enum Identifier : EnumBaseType EnumBody
AnonymousEnumDeclaration

EnumBaseType:
Type

EnumBody:
{ EnumMembers }
;

EnumMembers:
EnumMember
EnumMember ,
EnumMember , EnumMembers

EnumMember:
Identifier
Identifier = AssignExpression

AnonymousEnumDeclaration:
enum : EnumBaseType { EnumMembers }
enum { EnumMembers }
enum { AnonymousEnumMembers }

273
274 CHAPTER 17. ENUMS

AnonymousEnumMembers:
AnonymousEnumMember
AnonymousEnumMember ,
AnonymousEnumMember , AnonymousEnumMembers

AnonymousEnumMember:
EnumMember
Type Identifier = AssignExpression

Enum declarations are used to define a group of constants. They come in these forms:

1. Named enums, which have a name.

2. Anonymous enums, which do not have a name.
3. Manifest constants.

17.1 Named Enums

Named enums are used to declare related constants and group them by giving them a unique type.
The EnumMembers are declared in the scope of the named enum. The named enum declares a new
type, and all the EnumMembers have that type.
This defines a new type X which has values X.A=0, X.B=1, X.C=2:
enum X { A, B, C } // named enum
If the EnumBaseType is not explicitly set, and the first EnumMember has an AssignExpression,
it is set to the type of that AssignExpression. Otherwise, it defaults to type int.
Named enum members may not have individual Types.
A named enum member can be implicitly cast to its EnumBaseType, but EnumBaseType types
cannot be implicitly cast to an enum type.
The value of an EnumMember is given by its AssignExpression. If there is no AssignExpression
and it is the first EnumMember, its value is \textit{EnumBaseType}.init.
If there is no AssignExpression and it is not the first EnumMember, it is given the
value of the previous \textit{EnumMember}+1. If the value of the previous EnumMember is
\textit{EnumBaseType}.max, it is an error. If the value of the previous \textit{EnumMember}+1
is the same as the value of the previous EnumMember, it is an error. (This can happen with floating
point types.)
All EnumMember s are in scope for the AssignExpressions.
enum A = 3;
enum B
17.1. NAMED ENUMS 275

{
A = A // error, circular reference
}
enum C
{
A = B, // A = 4
B = D, // B = 4
C = 3, // C = 3
D // D = 4
}
enum E : C
{
E1 = C.D,
E2 // error, C.D is C.max
}
An empty enum body (For example enum E;) signifies an opaque enum - the enum members
are unknown.

Enum Default Initializer

The .init property of an enum type is the value of the first member of that enum. This is also the
default initializer for the enum type.
enum X { A=3, B, C }
X x; // x is initialized to 3

Enum Properties
Enum properties only exist for named enums.
<caption>Named Enum Properties</caption> .init First enum member value
.min Smallest value of enum
.max Largest value of enum
.sizeof Size of storage for an enumerated value
For example:
enum X { A=3, B, C }
X.min // is X.A
X.max // is X.C
X.sizeof // is same as int.sizeof
The EnumBaseType of named enums must support comparison in order to compute the .max
and .min properties.
276 CHAPTER 17. ENUMS

17.2 Anonymous Enums

If the enum Identifier is not present, then the enum is an anonymous enum, and the EnumMembers
are declared in the scope the EnumDeclaration appears in. No new type is created.
The EnumMembers can have different types. Those types are given by the first of:

1. The Type, if present. Types are not permitted when an EnumBaseType is present.
2. The EnumBaseType, if present.
3. The type of the AssignExpression, if present.
4. The type of the previous EnumMember, if present.
5. int

enum { A, B, C } // anonymous enum

Defines the constants A=0, B=1, C=2, all of type int.
Enums must have at least one member.
The value of an EnumMember is given by its AssignExpression. If there is no AssignExpression
and it is the first EnumMember, its value is the .init property of the EnumMember ’s type.
If there is no AssignExpression and it is not the first EnumMember, it is given the value of the pre-
vious \textit{EnumMember}+1. If the value of the previous EnumMember is the .max property if the
previous EnumMember ’s type, it is an error. If the value of the previous \textit{EnumMember}+1
is the same as the value of the previous EnumMember, it is an error. (This can happen with floating
point types.)
All EnumMember s are in scope for the AssignExpressions.
enum { A, B = 5+7, C, D = 8+C, E }
Sets A=0, B=12, C=13, D=21, and E=22, all of type int.
enum : long { A = 3, B }
Sets A=3, B=4 all of type long.
enum : string
{
A = "hello",
B = "betty",
C // error, cannot add 1 to "betty"
}

enum
{
A = 1.2f, // A is 1.2f of type float
17.3. MANIFEST CONSTANTS 277

B, // B is 2.2f of type float

int C = 3, // C is 3 of type int
D // D is 4 of type int
}

17.3 Manifest Constants

If there is only one member of an anonymous enum, the can be omitted. Gramatically speaking,
this is an AutoDeclaration.
enum i = 4; // i is 4 of type int
enum long l = 3; // l is 3 of type long
Such declarations are not lvalues, meaning their address cannot be taken. They exist only in
the memory of the compiler.
enum size = __traits(classInstanceSize, Foo); // evaluated at compile-time
Using manifest constants is an idiomatic D method to force compile-time evaluation of an
expression.
Chapter 18

Type Qualifiers

Type qualifiers modify a type by applying a TypeCtor. TypeCtor s are: const, immutable, shared,
and inout. Each applies transitively to all subtypes.

18.1 Const and Immutable

When examining a data structure or interface, it is very helpful to be able to easily tell which data
can be expected to not change, which data might change, and who may change that data. This is
done with the aid of the language typing system. Data can be marked as const or immutable, with
the default being changeable (or mutable).
immutable applies to data that cannot change. Immutable data values, once constructed, remain
the same for the duration of the program’s execution. Immutable data can be placed in ROM (Read
Only Memory) or in memory pages marked by the hardware as read only. Since immutable data
does not change, it enables many opportunities for program optimization, and has applications in
functional style programming.
const applies to data that cannot be changed by the const reference to that data. It may,
however, be changed by another reference to that same data. Const finds applications in passing
data through interfaces that promise not to modify them.
Both immutable and const are transitive, which means that any data reachable through an
immutable reference is also immutable, and likewise for const.

18.2 Immutable Storage Class

The simplest immutable declarations use it as a storage class. It can be used to declare manifest
constants.
immutable int x = 3; // x is set to 3

279
280 CHAPTER 18. TYPE QUALIFIERS

x = 4; // error, x is immutable
char[x] s; // s is an array of 3 char’s
The type can be inferred from the initializer:
immutable y = 4; // y is of type int
y = 5; // error, y is immutable
If the initializer is not present, the immutable can be initialized from the corresponding con-
structor:
immutable int z;
void test()
{
z = 3; // error, z is immutable
}
static this()
{
z = 3; // ok, can set immutable that doesn’t
// have static initializer
}
The initializer for a non-local immutable declaration must be evaluatable at compile time:
int foo(int f) { return f * 3; }
int i = 5;
immutable x = 3 * 4; // ok, 12
immutable y = i + 1; // error, cannot evaluate at compile time
immutable z = foo(2) + 1; // ok, foo(2) can be evaluated at compile time, 7
The initializer for a non-static local immutable declaration is evaluated at run time:
int foo(int f)
{
immutable x = f + 1; // evaluated at run time
x = 3; // error, x is immutable
}
Because immutable is transitive, data referred to by an immutable is also immutable:
immutable char[] s = "foo";
s[0] = ’a’; // error, s refers to immutable data
s = "bar"; // error, s is immutable
Immutable declarations can appear as lvalues, i.e. they can have their address taken, and occupy
storage.
18.3. CONST STORAGE CLASS 281

18.3 Const Storage Class

A const declaration is exactly like an immutable declaration, with the following differences:

• Any data referenced by the const declaration cannot be changed from the const declaration,
but it might be changed by other references to the same data.
• The type of a const declaration is itself const.

18.4 Immutable Type

Data that will never change its value can be typed as immutable. The immutable keyword can be
used as a type qualifier :
immutable(char)[] s = "hello";
The immutable applies to the type within the following parentheses. So, while s can be assigned
new values, the contents of s[] cannot be:
s[0] = ’b’; // error, s[] is immutable
s = null; // ok, s itself is not immutable
Immutability is transitive, meaning it applies to anything that can be referenced from the
immutable type:
immutable(char*)** p = ...;
p = ...; // ok, p is not immutable
*p = ...; // ok, *p is not immutable
**p = ...; // error, **p is immutable
***p = ...; // error, ***p is immutable
Immutable used as a storage class is equivalent to using immutable as a type qualifier for the
entire type of a declaration:
immutable int x = 3; // x is typed as immutable(int)
immutable(int) y = 3; // y is immutable

18.5 Creating Immutable Data

The first way is to use a literal that is already immutable, such as string literals. String literals are
always immutable.
auto s = "hello"; // s is immutable(char)[5]
char[] p = "world"; // error, cannot implicitly convert immutable
// to mutable
282 CHAPTER 18. TYPE QUALIFIERS

The second way is to cast data to immutable. When doing so, it is up to the programmer to
ensure that no other mutable references to the same data exist.
char[] s = ...;
immutable(char)[] p = cast(immutable)s; // undefined behavior
immutable(char)[] p = cast(immutable)s.dup; // ok, unique reference
The .idup property is a convenient way to create an immutable copy of an array:
auto p = s.idup;
p[0] = ...; // error, p[] is immutable

18.6 Removing Immutable or Const with a Cast

An immutable or const type qualifier can be removed with a cast:
immutable int* p = ...;
int* q = cast(int*)p;
This does not mean, however, that one can change the data:
*q = 3; // allowed by compiler, but result is undefined behavior
The ability to cast away immutable-correctness is necessary in some cases where the static typing
is incorrect and not fixable, such as when referencing code in a library one cannot change. Casting is,
as always, a blunt and effective instrument, and when using it to cast away immutable-correctness,
one must assume the responsibility to ensure the immutability of the data, as the compiler will no
longer be able to statically do so.
Note that casting away a const qualifier and then mutating is undefined behavior, too, even when
the referenced data is mutable. This is so that compilers and programmers can make assumptions
based on const alone. For example, here it may be assumed that f does not alter x:
void f(const int* a);
void main()
{
int x = 1;
f(&x);
assert(x == 1); // guaranteed to hold
}

18.7 Immutable Member Functions

Immutable member functions are guaranteed that the object and anything referred to by the this
reference is immutable. They are declared as:
18.8. CONST TYPE 283

struct S
{
int x;

void foo() immutable

{
x = 4; // error, x is immutable
this.x = 4; // error, x is immutable
}
}
Note that using immutable on the left hand side of a method does not apply to the return type:
struct S
{
immutable int[] bar() // bar is still immutable, return type is not!
{
}
}
To make the return type immutable, you need to surround the return type with parentheses:
struct S
{
immutable(int[]) bar() // bar is now mutable, return type is immutable.
{
}
}
To make both the return type and the method immutable, you can write:
struct S
{
immutable(int[]) bar() immutable
{
}
}

18.8 Const Type

Const types are like immutable types, except that const forms a read-only view of data. Other
aliases to that same data may change it at any time.
284 CHAPTER 18. TYPE QUALIFIERS

18.9 Const Member Functions

Const member functions are functions that are not allowed to change any part of the object through
the member function’s this reference.

18.10 Implicit Conversions

Values can be implicitly converted between mutable, const, immutable, shared const, inout and
inout shared.
References can be converted according to the following rules:

Implicit Conversion of Reference Types

inout shared const

shared const

inout shared
inout const

immutable
mutable

shared
const

inout
from/to
mutable ✓ ✓
const ✓
shared ✓ ✓
shared const ✓
inout ✓ ✓ ✓
inout const ✓ ✓
inout shared ✓ ✓ ✓
inout shared const ✓ ✓
immutable ✓ ✓ ✓ ✓ ✓

If an implicit conversion is disallowed by the table, an Expression may be converted if:

An expression may be converted from mutable or shared to immutable if the expression is unique
and all expressions it transitively refers to are either unique or immutable.
An expression may be converted from mutable to shared if the expression is unique and all
expressions it transitively refers to are either unique, immutable, or shared.
An expression may be converted from immutable to mutable if the expression is unique.
An expression may be converted from shared to mutable if the expression is unique.
A Unique Expression is one for which there are no other references to the value of the expression
and all expressions it transitively refers to are either also unique or are immutable. For example:
18.10. IMPLICIT CONVERSIONS 285

void main()
{
immutable int** p = new int*(null); // ok, unique

int x;
immutable int** q = new int*(&x); // error, there may be other references to x

immutable int y;
immutable int** r = new immutable(int)*(&y); // ok, y is immutable
}
Otherwise, a CastExpression can be used to force a conversion when an implicit version is
disallowed, but this cannot be done in @safe code, and the correctness of it must be verified by the
user.
Chapter 19

Functions

FuncDeclaration:
StorageClasses opt BasicType FuncDeclarator FunctionBody
AutoFuncDeclaration

AutoFuncDeclaration:
StorageClasses Identifier FuncDeclaratorSuffix FunctionBody

FuncDeclarator:
BasicType2 opt Identifier FuncDeclaratorSuffix

FuncDeclaratorSuffix:
Parameters MemberFunctionAttributes opt
TemplateParameters Parameters MemberFunctionAttributes opt Constraint opt

Parameters:
( ParameterList opt )

ParameterList:
Parameter
Parameter , ParameterList
...

Parameter:
InOut opt BasicType Declarator
InOut opt BasicType Declarator ...
InOut opt BasicType Declarator = AssignExpression

287
288 CHAPTER 19. FUNCTIONS

InOut opt Type

InOut opt Type ...

InOut:
InOutX
InOut InOutX

InOutX:
auto
TypeCtor
final
in
lazy
out
ref
scope

FunctionAttributes:
FunctionAttribute
FunctionAttribute FunctionAttributes

FunctionAttribute:
nothrow
pure
Property

MemberFunctionAttributes:
MemberFunctionAttribute
MemberFunctionAttribute MemberFunctionAttributes

MemberFunctionAttribute:
const
immutable
inout
shared
FunctionAttribute

FunctionBody:
BlockStatement
 289

FunctionContracts opt BodyStatement

FunctionContracts

FunctionContracts:
InStatement OutStatement opt
OutStatement InStatement opt

InStatement:
in BlockStatement

OutStatement:
out BlockStatement
out ( Identifier ) BlockStatement

BodyStatement:
body BlockStatement

Contracts

The in and out blocks of a function declaration specify the pre- and post-conditions of the function.
They are used in Contract Programming. The code inside these blocks should not have any side-
effects, including modifying function parameters and/or return values.

Function Return Values

Function return values are considered to be rvalues. This means they cannot be passed by reference
to other functions.

Functions Without Bodies

Functions without bodies:

int foo();

that are not declared as abstract are expected to have their implementations elsewhere, and
that implementation will be provided at the link step. This enables an implementation of a function
to be completely hidden from the user of it, and the implementation may be in another language
such as C, assembler, etc.
290 CHAPTER 19. FUNCTIONS

Pure Functions
Pure functions are functions which cannot access global or static, mutable state save through their
arguments. This can enable optimizations based on the fact that a pure function is guaranteed to
mutate nothing which isn’t passed to it, and in cases where the compiler can guarantee that a pure
function cannot alter its arguments, it can enable full, functional purity (i.e. the guarantee that the
function will always return the same result for the same arguments). To that end, a pure function:

• does not read or write any global or static mutable state

• cannot call functions that are not pure
• can override an impure function, but an impure function cannot override a pure one
• is covariant with an impure function
• cannot perform I/O

As a concession to practicality, a pure function can:

• allocate memory via a NewExpression

• terminate the program
• read and write the floating point exception flags
• read and write the floating point mode flags, as long as those flags are restored to their initial
state upon function entry
• perform impure operations in statements that are in a ConditionalStatement controlled by a
DebugCondition.

A pure function can throw exceptions.

import std.stdio;
int x;
immutable int y;
const int* pz;

pure int foo(int i,

char* p,
const char* q,
immutable int* s)
{
debug writeln("in␣foo()"); // ok, impure code allowed in debug statement
x = i; // error, modifying global state
i = x; // error, reading mutable global state
i = y; // ok, reading immutable global state
i = *pz; // error, reading const global state
 291

return i;
}

Nothrow Functions
Nothrow functions do not throw any exceptions derived from class Exception.
Nothrow functions are covariant with throwing ones.

Ref Functions
Ref functions allow functions to return by reference. This is analogous to ref function parameters.
ref int foo()
{
auto p = new int;
return *p;
}
...
foo() = 3; // reference returns can be lvalues

Auto Functions
Auto functions have their return type inferred from any ReturnStatements in the function body.
An auto function is declared without a return type. If it does not already have a storage class,
use the auto storage class.
If there are multiple ReturnStatements, the types of them must be implicitly convertible to a
common type. If there are no ReturnStatements, the return type is inferred to be void.
auto foo(int x) { return x + 3; } // inferred to be int
auto foo(int x) { return x; return 2.5; } // inferred to be double

Auto Ref Functions

Auto ref functions infer their return type just as auto functions do. In addition, they become
ref functions if all return expressions are lvalues, and it would not be a reference to a local or a
parameter.
auto ref foo(int x) { return x; } // value return
auto ref foo() { return 3; } // value return
auto ref foo(ref int x) { return x; } // ref return
auto ref foo(out int x) { return x; } // ref return
auto ref foo() { static int x; return x; } // ref return
292 CHAPTER 19. FUNCTIONS

The ref-ness of a function is determined from all ReturnStatements in the function body:
auto ref foo(ref int x) { return 3; return x; } // ok, value return
auto ref foo(ref int x) { return x; return 3; } // ok, value return
auto ref foo(ref int x, ref double y)
{
return x; return y;
// The return type is deduced to double, but cast(double)x is not an lvalue,
// then become a value return.
}
Auto ref function can have explicit return type.
auto ref int foo(ref int x) { return x; } // ok, ref return
auto ref int foo(double x) { return x; } // error, cannot convert double to int

Inout Functions
Functions that deal with mutable, const, or immutable types with equanimity often need to transmit
their type to the return value:
int[] foo(int[] a, int x, int y) { return a[x .. y]; }

const(int)[] foo(const(int)[] a, int x, int y) { return a[x .. y]; }

immutable(int)[] foo(immutable(int)[] a, int x, int y) { return a[x .. y]; }

The code generated by these three functions is identical. To indicate that these can be one
function, the inout type constructor is employed:
inout(int)[] foo(inout(int)[] a, int x, int y) { return a[x .. y]; }
The inout forms a wildcard that stands in for any of mutable, const, immutable, inout, or inout
const. When the function is called, the inout of the return type is changed to whatever the mutable,
const, immutable, inout, or inout const status of the argument type to the parameter inout was.
Inout types can be implicitly converted to const or inout const, but to nothing else. Other types
cannot be implicitly converted to inout. Casting to or from inout is not allowed in @safe functions.
A set of arguments to a function with inout parameters is considered a match if any inout
argument types match exactly, or:

1. No argument types are composed of inout types.

2. A mutable, const or immutable argument type can be matched against each corresponding
parameter inout type.
 293

If such a match occurs, the inout is considered the common qualifier of the matched qualifiers.
If more than two parameters exist, the common qualifier calculation is recursively applied.

Common qualifier of the two type qualifiers

mutable const immutable inout inout const
mutable (= m) m c c c c
const (= c) c c c c c
immutable (= i) c c i wc wc
inout (= w) c c wc w wc
inout const (= wc) c c wc wc wc

The inout in the return type is then rewritten to be the inout matched qualifiers:
int[] ma;
const(int)[] ca;
immutable(int)[] ia;

inout(int)[] foo(inout(int)[] a) { return a; }

void test1()
{
// inout matches to mutable, so inout(int)[] is
// rewritten to int[]
int[] x = foo(ma);

// inout matches to const, so inout(int)[] is

// rewritten to const(int)[]
const(int)[] y = foo(ca);

// inout matches to immutable, so inout(int)[] is

// rewritten to immutable(int)[]
immutable(int)[] z = foo(ia);
}

inout(const(int))[] bar(inout(int)[] a) { return a; }

void test2()
{
// inout matches to mutable, so inout(const(int))[] is
// rewritten to const(int)[]
const(int)[] x = foo(ma);
294 CHAPTER 19. FUNCTIONS

// inout matches to const, so inout(const(int))[] is

// rewritten to const(int)[]
const(int)[] y = foo(ca);

// inout matches to immutable, so inout(int)[] is

// rewritten to immutable(int)[]
immutable(int)[] z = foo(ia);
}
Note: Shared types are not overlooked. Shared types cannot be matched with inout.

Property Functions
Property functions are tagged with the @property attribute. They cannot be called with parentheses
(hence they act like fields except in some cases).
If a property function has no parameters, it works as a getter. If has exactly one parameter, it
works as a setter.
struct S
{
int m_x;
@property
{
int x() { return m_x; }
int x(int newx) { return m_x = newx; }

int function(int, int) adder()

{
return function int(int a, int b) { return a + b; }
}
}
}
void main()
{
S s;
s.x; // lowered to s.x()
s.x = 3; // lowered to s.x(3)

//s.x(); // NG: lowered to s.x()(), but the int value

// returned by s.x() is not callable
//s.x(3); // NG: lowered to s.x()(3), but the int value
 295

// returned by s.x() is not callable

assert(s.adder(1, 2) == 3);
// OK lowered to s.adder()(1, 2)
}
If a getter property function returns a reference to other storage, it also works as a setter.
struct S
{
int m_x;
@property ref int x() { return m_x; }
}
void main()
{
S s;
int n = s.x; // s.x()
assert(s.m_x == n);
s.x = 2; // s.x() = 2;
assert(s.m_x == 2);
}
In most places, getter property functions are called immediately. One exceptional case is the
address operator.
struct S
{
int m_x;
@property int x1() { return m_x; }
@property ref int x2() { return m_x; }
}
void main()
{
S s;
auto x1 = &s.x1;
auto x2 = &s.x2;
static assert(is(typeof(x1) == delegate));
static assert(is(typeof(x2) == delegate));
// Both x1 and x2 are delegate, not int pointer.

int n = x1();
assert(s.m_x == n);
x2() = 1;
296 CHAPTER 19. FUNCTIONS

assert(s.m_x == 1);
}
Even if the given operand is a property function, the address operator returns the address of
the property function rather than the address of its return value.

Optional parenthesis
If a function call does not take any arguments syntactically, it is callable without parenthesis, like
a getter property functions.
void foo() {} // no arguments
void bar(int[] arr) {} // for UFCS

void main()
{
foo(); // OK
foo; // also OK

int[] arr;
arr.bar(); // OK
arr.bar; // also OK
}
However, assignment syntax is disallowed unlike with property functions.
struct S
{
void foo(int) {} // one argument
}
void main()
{
S s;
s.foo(1); // OK
//s.foo = 1; // disallowed
}

Virtual Functions
Virtual functions are functions that are called indirectly through a function pointer table, called a
vtbl[], rather than directly. All public and protected member functions which are non-static and
aren’t templatized are virtual unless the compiler can determine that they will never be overridden
 297

(e.g. they’re marked with final and don’t override any functions in a base class), in which case, it
will make them non-virtual. This results in fewer bugs caused by not declaring a function virtual
and then overriding it anyway.
Member functions which are private or package are never virtual, and hence cannot be over-
ridden.
Functions with non-D linkage cannot be virtual and hence cannot be overridden.
Member template functions cannot be virtual and hence cannot be overridden.
Functions marked as final may not be overridden in a derived class, unless they are also
private. For example:

class A
{
int def() { ... }
final int foo() { ... }
final private int bar() { ... }
private int abc() { ... }
}

class B : A
{
override int def() { ... } // ok, overrides A.def
override int foo() { ... } // error, A.foo is final
int bar() { ... } // ok, A.bar is final private, but not virtual
int abc() { ... } // ok, A.abc is not virtual, B.abc is virtual
}

void test(A a)
{
a.def(); // calls B.def
a.foo(); // calls A.foo
a.bar(); // calls A.bar
a.abc(); // calls A.abc
}

void func()
{
B b = new B();
test(b);
}
298 CHAPTER 19. FUNCTIONS

Covariant return types are supported, which means that the overriding function in a derived
class can return a type that is derived from the type returned by the overridden function:
class A { }
class B : A { }

class Foo
{
A test() { return null; }
}

class Bar : Foo

{
override B test() { return null; } // overrides and is covariant with ⤦
Ç Foo.test()
}
Virtual functions all have a hidden parameter called the this reference, which refers to the class
object for which the function is called.
To avoid dynamic binding on member function call, insert base class name before the member
function name. For example:
class B
{
int foo() { return 1; }
}
class C : B
{
override int foo() { return 2; }

void test()
{
assert(B.foo() == 1); // translated to this.B.foo(), and
// calls B.foo statically.
assert(C.foo() == 2); // calls C.foo statically, even if
// the actual instance of ’this’ is D.
}
}
class D : C
{
override int foo() { return 3; }
}
 299

void main()
{
auto d = new D();
assert(d.foo() == 3); // calls D.foo
assert(d.B.foo() == 1); // calls B.foo
assert(d.C.foo() == 2); // calls C.foo
d.test();
}

Function Inheritance and Overriding

A function in a derived class with the same name and parameter types as a function in a base class
overrides that function:
class A
{
int foo(int x) { ... }
}

class B : A
{
override int foo(int x) { ... }
}

void test()
{
B b = new B();
bar(b);
}

void bar(A a)
{
a.foo(1); // calls B.foo(int)
}
However, when doing overload resolution, the functions in the base class are not considered:
class A
{
int foo(int x) { ... }
int foo(long y) { ... }
300 CHAPTER 19. FUNCTIONS

class B : A
{
override int foo(long x) { ... }
}

void test()
{
B b = new B();
b.foo(1); // calls B.foo(long), since A.foo(int) not considered
A a = b;

a.foo(1); // issues runtime error (instead of calling A.foo(int))

}
To consider the base class’s functions in the overload resolution process, use an AliasDeclaration:
class A
{
int foo(int x) { ... }
int foo(long y) { ... }
}

class B : A
{
alias foo = A.foo;
override int foo(long x) { ... }
}

void test()
{
B b = new B();
bar(b);
}

void bar(A a)
{
a.foo(1); // calls A.foo(int)
B b = new B();
b.foo(1); // calls A.foo(int)
 301

}
If such an AliasDeclaration is not used, the derived class’s functions completely override all the
functions of the same name in the base class, even if the types of the parameters in the base class
functions are different. If, through implicit conversions to the base class, those other functions do
get called, a compile-time error will be given:
class A
{
void set(long i) { }
void set(int i) { }
}
class B : A
{
void set(long i) { }
}

void foo(A a)
{
int i;
a.set(3); // error, use of A.set(int) is hidden by B
// use ’alias set = A.set;’ to introduce base class overload set.
assert(i == 1);
}

void main()
{
foo(new B);
}
If an error occurs during the compilation of your program, the use of overloads and overrides needs
to be reexamined in the relevant classes.
The compiler will not give an error if the hidden function is disjoint, as far as overloading is
concerned, from all the other virtual functions is the inheritance hierarchy.
A function parameter’s default value is not inherited:
class A
{
void foo(int x = 5) { ... }
}

class B : A
302 CHAPTER 19. FUNCTIONS

{
void foo(int x = 7) { ... }
}

class C : B
{
void foo(int x) { ... }
}

void test()
{
A a = new A();
a.foo(); // calls A.foo(5)

B b = new B();
b.foo(); // calls B.foo(7)

C c = new C();
c.foo(); // error, need an argument for C.foo
}

If a derived class overrides a base class member function with diferrent FunctionAttributes, the
missing attributes will be automatically compensated by the compiler.

class B
{
void foo() pure nothrow @safe {}
}
class D : B
{
override void foo() {}
}
void main()
{
auto d = new D();
pragma(msg, typeof(&d.foo));
// prints "void delegate() pure nothrow @safe" in compile time
}
 303

Inline Functions
There is no inline keyword. The compiler makes the decision whether to inline a function or
not, analogously to the register keyword no longer being relevant to a compiler’s decisions on
enregistering variables. (There is no register keyword either.)
If a FunctionLiteral is immediately called, its inlining would be enforced normally.

Function Overloading
Functions are overloaded based on how well the arguments to a function can match up with the
parameters. The function with the best match is selected. The levels of matching are:

1. no match
2. match with implicit conversions
3. match with conversion to const
4. exact match

Each argument (including any this pointer) is compared against the function’s corresponding
parameter, to determine the match level for that argument. The match level for a function is the
worst match level of each of its arguments.
Literals do not match ref or out parameters.
If two or more functions have the same match level, then partial ordering is used to try to find
the best match. Partial ordering finds the most specialized function. If neither function is more
specialized than the other, then it is an ambiguity error. Partial ordering is determined for functions
f() and g() by taking the parameter types of f(), constructing a list of arguments by taking the
default values of those types, and attempting to match them against g(). If it succeeds, then g()
is at least as specialized as f(). For example:
class A { }
class B : A { }
class C : B { }
void foo(A);
void foo(B);

void test()
{
C c;
/* Both foo(A) and foo(B) match with implicit conversion rules.
* Applying partial ordering rules,
* foo(B) cannot be called with an A, and foo(A) can be called
* with a B. Therefore, foo(B) is more specialized, and is selected.
304 CHAPTER 19. FUNCTIONS

*/
foo(c); // calls foo(B)
}
A function with a variadic argument is considered less specialized than a function without.
Functions defined with non-D linkage cannot be overloaded. This is because the name mangling
might not take the parameter types into account.

Overload Sets
Functions declared at the same scope overload against each other, and are called an Overload Set.
A typical example of an overload set are functions defined at module level:
module A;
void foo() { }
void foo(long i) { }
A.foo() and A.foo(long) form an overload set. A different module can also define functions
with the same name:
module B;
class C { }
void foo(C) { }
void foo(int i) { }
and A and B can be imported by a third module, C. Both overload sets, the A.foo overload
set and the B.foo overload set, are found. An instance of foo is selected based on it matching in
exactly one overload set:
import A;
import B;

void bar(C c)
{
foo(); // calls A.foo()
foo(1L); // calls A.foo(long)
foo(c); // calls B.foo(C)
foo(1,2); // error, does not match any foo
foo(1); // error, matches A.foo(long) and B.foo(int)
A.foo(1); // calls A.foo(long)
}
Even though B.foo(int) is a better match than A.foo(long) for foo(1), it is an
error because the two matches are in different overload sets.
Overload sets can be merged with an alias declaration:
 305

import A;
import B;

alias foo = A.foo;

alias foo = B.foo;

void bar(C c)
{
foo(); // calls A.foo()
foo(1L); // calls A.foo(long)
foo(c); // calls B.foo(C)
foo(1,2); // error, does not match any foo
foo(1); // calls B.foo(int)
A.foo(1); // calls A.foo(long)
}

Function Parameters

Parameter storage classes are in, out, ref, lazy, const, immutable, shared, inout or scope. For
example:

int foo(in int x, out int y, ref int z, int q);

x is in, y is out, z is ref, and q is none.

• The function declaration makes it clear what the inputs and outputs to the function are.
• It eliminates the need for IDL (interface description language) as a separate language.
• It provides more information to the compiler, enabling more error checking and possibly better
code generation.
306 CHAPTER 19. FUNCTIONS

Parameter Storage Classes

Storage Class Description
none parameter becomes a mutable copy of its argument
in equivalent to const scope
out parameter is initialized upon function entry with the default value for its type
ref parameter is passed by reference
scope references in the parameter cannot be escaped (e.g. assigned to a global
variable)
lazy argument is evaluated by the called function and not by the caller
const argument is implicitly converted to a const type
immutable argument is implicitly converted to an immutable type
shared argument is implicitly converted to a shared type
inout argument is implicitly converted to an inout type

void foo(out int x)

{
// x is set to int.init,
// which is 0, at start of foo()
}

int a = 3;
foo(a);
// a is now 0

void abc(out int x)

{
x = 2;
}

int y = 3;
abc(y);
// y is now 2

void def(ref int x)

{
x += 1;
}

int z = 3;
 307

def(z);
// z is now 4
For dynamic array and object parameters, which are passed by reference, in/out/ref apply only
to the reference and not the contents.
lazy arguments are evaluated not when the function is called, but when the parameter is
evaluated within the function. Hence, a lazy argument can be executed 0 or more times. A lazy
parameter cannot be an lvalue.
void dotimes(int n, lazy void exp)
{
while (n--)
exp();
}

void test()
{
int x;
dotimes(3, writeln(x++));
}
prints to the console:
0 1 2
A lazy parameter of type void can accept an argument of any type.

Function Default Arguments

Function parameter declarations can have default values:
void foo(int x, int y = 3)
{
...
}
...
foo(4); // same as foo(4, 3);
Default parameters are evaluated in the context of the function declaration. If the default value
for a parameter is given, all following parameters must also have default values.

Variadic Functions
Functions taking a variable number of arguments are called variadic functions. A variadic function
can take one of three forms:
308 CHAPTER 19. FUNCTIONS

1. C-style variadic functions

2. Variadic functions with type info
3. Typesafe variadic functions

C-style Variadic Functions

A C-style variadic function is declared as taking a parameter of ... after the required function
parameters. It has non-D linkage, such as extern (C):
extern (C) void foo(int x, int y, ...);

foo(3, 4); // ok
foo(3, 4, 6.8); // ok, one variadic argument
foo(2); // error, y is a required argument
There must be at least one non-variadic parameter declared.
extern (C) int def(...); // error, must have at least one parameter
C-style variadic functions match the C calling convention for variadic functions, and is most
useful for calling C library functions like printf.
Access to variadic arguments is done using the standard library module core.stdc.stdarg.
import core.stdc.stdarg;

void test()
{
foo(3, 4, 5); // first variadic argument is 5
}

void foo(int x, int y, ...)

{
va_list args;

version (X86)
va_start(args, y); // y is the last named parameter
else
version (Win64)
va_start(args, y); // ditto
else
version (X86_64)
va_start(args, __va_argsave);
else
 309

static assert(0, "Platform␣not␣supported.");

int z;
va_arg(args, z); // z is set to 5
}

D-style Variadic Functions

Variadic functions with argument and type info are declared as taking a parameter of ... after the
required function parameters. It has D linkage, and need not have any non-variadic parameters
declared:
int abc(char c, ...); // one required parameter: c
int def(...); // ok
To access them, the following import is required:
import core.vararg;
These variadic functions have a special local variable declared for them, _argptr, which is a
core.vararg reference to the first of the variadic arguments. To access the arguments, _argptr
must be used in conjuction with va_arg:
import core.vararg;

void test()
{
foo(3, 4, 5); // first variadic argument is 5
}

void foo(int x, int y, ...)

{
int z;

z = va_arg!int(_argptr); // z is set to 5
}
An additional hidden argument with the name _arguments and type TypeInfo[] is passed to
the function. _arguments gives the number of arguments and the type of each, enabling type safety
to be checked at run time.
import std.stdio;
import core.vararg;
310 CHAPTER 19. FUNCTIONS

class Foo { int x = 3; }

class Bar { long y = 4; }

void printargs(int x, ...)

{
writefln("%d␣arguments", _arguments.length);
for (int i = 0; i < _arguments.length; i++)
{
writeln(_arguments[i]);

if (_arguments[i] == typeid(int))
{
int j = va_arg!(int)(_argptr);
writefln("\t%d", j);
}
else if (_arguments[i] == typeid(long))
{
long j = va_arg!(long)(_argptr);
writefln("\t%d", j);
}
else if (_arguments[i] == typeid(double))
{
double d = va_arg!(double)(_argptr);
writefln("\t%g", d);
}
else if (_arguments[i] == typeid(Foo))
{
Foo f = va_arg!(Foo)(_argptr);
writefln("\t%s", f);
}
else if (_arguments[i] == typeid(Bar))
{
Bar b = va_arg!(Bar)(_argptr);
writefln("\t%s", b);
}
else
assert(0);
}
}
 311

void main()
{
Foo f = new Foo();
Bar b = new Bar();

writefln("%s", f);
printargs(1, 2, 3L, 4.5, f, b);
}
which prints:
0x00870FE0
5 arguments
int
2
long
3
double
4.5
Foo
0x00870FE0
Bar
0x00870FD0

Typesafe Variadic Functions

Typesafe variadic functions are used when the variable argument portion of the arguments are used
to construct an array or class object.
For arrays:
int test()
{
return sum(1, 2, 3) + sum(); // returns 6+0
}

int func()
{
int[3] ii = [4, 5, 6];
return sum(ii); // returns 15
}
312 CHAPTER 19. FUNCTIONS

int sum(int[] ar ...)

{
int s;
foreach (int x; ar)
s += x;
return s;
}
For static arrays:
int test()
{
return sum(2, 3); // error, need 3 values for array
return sum(1, 2, 3); // returns 6
}

int func()
{
int[3] ii = [4, 5, 6];
int[] jj = ii;
return sum(ii); // returns 15
return sum(jj); // error, type mismatch
}

int sum(int[3] ar ...)

{
int s;
foreach (int x; ar)
s += x;
return s;
}
For class objects:
class Foo
{
int x;
string s;

this(int x, string s)
{
this.x = x;
 313

this.s = s;
}
}

void test(int x, Foo f ...);

...

Foo g = new Foo(3, "abc");

test(1, g); // ok, since g is an instance of Foo
test(1, 4, "def"); // ok
test(1, 5); // error, no matching constructor for Foo

An implementation may construct the object or array instance on the stack. Therefore, it is an
error to refer to that instance after the variadic function has returned:

Foo test(Foo f ...)

{
return f; // error, f instance contents invalid after return
}

int[] test(int[] a ...)

{
return a; // error, array contents invalid after return
return a[0..1]; // error, array contents invalid after return
return a.dup; // ok, since copy is made
}

For other types, the argument is built with itself, as in:

int test(int i ...)

{
return i;
}

...
test(3); // returns 3
test(3, 4); // error, too many arguments
int[] x;
test(x); // error, type mismatch
314 CHAPTER 19. FUNCTIONS

Lazy Variadic Functions

If the variadic parameter is an array of delegates with no parameters:
void foo(int delegate()[] dgs ...);
Then each of the arguments whose type does not match that of the delegate is converted to a
delegate.
int delegate() dg;
foo(1, 3+x, dg, cast(int delegate())null);
is the same as:
foo( { return 1; }, { return 3+x; }, dg, null );

Local Variables
It is an error to use a local variable without first assigning it a value. The implementation may not
always be able to detect these cases. Other language compilers sometimes issue a warning for this,
but since it is always a bug, it should be an error.
It is an error to declare a local variable that is never referred to. Dead variables, like anachronistic
dead code, are just a source of confusion for maintenance programmers.
It is an error to declare a local variable that hides another local variable in the same function:
void func(int x)
{
int x; // error, hides previous definition of x
double y;
...
{
char y; // error, hides previous definition of y
int z;
}
{
wchar z; // legal, previous z is out of scope
}
}
While this might look unreasonable, in practice whenever this is done it either is a bug or at
least looks like a bug.
It is an error to return the address of or a reference to a local variable.
It is an error to have a local variable and a label with the same name.
 315

Local Static Variables

Local variables in functions can be declared as static or __gshared in which case they are statically
allocated rather than being allocated on the stack. As such, their value persists beyond the exit of
the function.
void foo()
{
static int n;
if (++n == 100)
writeln("called␣100␣times");
}
The initializer for a static variable must be evaluatable at compile time, and they are initialized
upon the start of the thread (or the start of the program for __gshared). There are no static
constructors or static destructors for static local variables.
Although static variable name visibility follows the usual scoping rules, the names of them must
be unique within a particular function.
void main()
{
{ static int x; }
{ static int x; } // error
{ int i; }
{ int i; } // ok
}

Nested Functions
Functions may be nested within other functions:
int bar(int a)
{
int foo(int b)
{
int abc() { return 1; }

return b + abc();
}
return foo(a);
}
316 CHAPTER 19. FUNCTIONS

void test()
{
int i = bar(3); // i is assigned 4
}
Nested functions can be accessed only if the name is in scope.
void foo()
{
void A()
{
B(); // error, B() is forward referenced
C(); // error, C undefined
}
void B()
{
A(); // ok, in scope
void C()
{
void D()
{
A(); // ok
B(); // ok
C(); // ok
D(); // ok
}
}
}
A(); // ok
B(); // ok
C(); // error, C undefined
}
and:
int bar(int a)
{
int foo(int b) { return b + 1; }
int abc(int b) { return foo(b); } // ok
return foo(a);
}
 317

void test()
{
int i = bar(3); // ok
int j = bar.foo(3); // error, bar.foo not visible
}
Nested functions have access to the variables and other symbols defined by the lexically enclosing
function. This access includes both the ability to read and write them.
int bar(int a)
{
int c = 3;

int foo(int b)
{
b += c; // 4 is added to b
c++; // bar.c is now 5
return b + c; // 12 is returned
}
c = 4;
int i = foo(a); // i is set to 12
return i + c; // returns 17
}

void test()
{
int i = bar(3); // i is assigned 17
}
This access can span multiple nesting levels:
int bar(int a)
{
int c = 3;

int foo(int b)
{
int abc()
{
return c; // access bar.c
}
return b + c + abc();
318 CHAPTER 19. FUNCTIONS

}
return foo(3);
}

Static nested functions cannot access any stack variables of any lexically enclosing function, but
can access static variables. This is analogous to how static member functions behave.
int bar(int a)
{
int c;
static int d;

static int foo(int b)

{
b = d; // ok
b = c; // error, foo() cannot access frame of bar()
return b + 1;
}
return foo(a);
}

Functions can be nested within member functions:

struct Foo
{
int a;

int bar()
{
int c;

int foo()
{
return c + a;
}
return 0;
}
}

Nested functions always have the D function linkage type.

Unlike module level declarations, declarations within function scope are processed in order. This
means that two nested functions cannot mutually call each other:
 319

void test()
{
void foo() { bar(); } // error, bar not defined
void bar() { foo(); } // ok
}
There are several workarounds for this limitation:

• Declare the functions to be static members of a nested struct:

void test()
{
static struct S
{
static void foo() { bar(); } // ok
static void bar() { foo(); } // ok
}

S.foo(); // compiles (but note the infinite runtime loop)

}
• Declare one or more of the functions to be function templates even if they take no specific
template arguments:
void test()
{
void foo()() { bar(); } // ok (foo is a function template)
void bar() { foo(); } // ok
}
• Declare the functions inside of a mixin template:
mixin template T()
{
void foo() { bar(); } // ok
void bar() { foo(); } // ok
}

void test()
{
mixin T!();
}
• Use a delegate:
320 CHAPTER 19. FUNCTIONS

void test()
{
void delegate() fp;
void foo() { fp(); }
void bar() { foo(); }
fp = &bar;
}

Nested functions cannot be overloaded.

Delegates, Function Pointers, and Closures

A function pointer can point to a static nested function:
int function() fp;

void test()
{
static int a = 7;
static int foo() { return a + 3; }

fp = &foo;
}

void bar()
{
test();
int i = fp(); // i is set to 10
}
Note: Two functions with identical bodies, or two functions that compile to identical assembly
code, are not guaranteed to have distinct function pointer values. The compiler is free to merge
functions bodies into one if they compile to identical code.
int abc(int x) { return x + 1; }
int def(int y) { return y + 1; }

int function() fp1 = &abc;

int function() fp2 = &def;
// Do not rely on fp1 and fp2 being different values; the compiler may merge
// them.
 321

A delegate can be set to a non-static nested function:

int delegate() dg;

void test()
{
int a = 7;
int foo() { return a + 3; }

dg = &foo;
int i = dg(); // i is set to 10
}
The stack variables referenced by a nested function are still valid even after the function exits
(this is different from D 1.0). This is called a closure. Returning addresses of stack variables,
however, is not a closure and is an error.
int* bar()
{
int b;
test();
int i = dg(); // ok, test.a is in a closure and still exists
return &b; // error, bar.b not valid after bar() exits
}
Delegates to non-static nested functions contain two pieces of data: the pointer to the stack
frame of the lexically enclosing function (called the frame pointer ) and the address of the function.
This is analogous to struct/class non-static member function delegates consisting of a this pointer
and the address of the member function. Both forms of delegates are interchangeable, and are
actually the same type:
struct Foo
{
int a = 7;
int bar() { return a; }
}

int foo(int delegate() dg)

{
return dg() + 1;
}

void test()
322 CHAPTER 19. FUNCTIONS

{
int x = 27;
int abc() { return x; }
Foo f;
int i;

i = foo(&abc); // i is set to 28
i = foo(&f.bar); // i is set to 8
}
This combining of the environment and the function is called a dynamic closure.
The .ptr property of a delegate will return the frame pointer value as a void*.
The .funcptr property of a delegate will return the function pointer value as a function type.
Future directions: Function pointers and delegates may merge into a common syntax and be
interchangeable with each other.

Anonymous Functions and Anonymous Delegates

See FunctionLiteral s.

main() Function
For console programs, main() serves as the entry point. It gets called after all the module initializers
are run, and after any unittests are run. After it returns, all the module destructors are run. main()
must be declared using one of the following forms:
void main() { ... }
void main(string[] args) { ... }
int main() { ... }
int main(string[] args) { ... }

Function Templates
Template functions are useful for avoiding code duplication - instead of writing several copies of
a function, each with a different parameter type, a single function template can be sufficient. For
example:
// Only one copy of func needs to be written
void func(T)(T x)
{
writeln(x);
}
 323

void main()
{
func!(int)(1); // pass an int
func(1); // pass an int, inferring T = int
func("x"); // pass a string
func(1.0); // pass a float

struct S {}
S s;
func(s); // pass a struct
}
func takes a template parameter T and a runtime parameter, x. T is a placeholder identifier that
can accept any type. In this case T can be inferred from the runtime argument type.
Note: Using the name T is just a convention. The name TypeOfX could have been used instead.
For more information, see function templates.

Compile Time Function Execution (CTFE)

Functions which are both portable and free of side-effects can be executed at compile time. This
is useful when constant folding algorithms need to include recursion and looping. Compile time
function execution is subject to the following restrictions:

1. The function source code must be available to the compiler. Functions which exist in the
source code only as extern declarations cannot be executed at compile time.
2. Executed expressions may not reference any global or local static variables.
3. asm statements are not permitted
4. Non-portable casts (eg, from int[] to float[]), including casts which depend on endianness,
are not permitted. Casts between signed and unsigned types are permitted

Pointers are permitted in CTFE, provided they are used safely:

• C-style semantics on pointer arithmetic are strictly enforced. Pointer arithmetic is permitted
only on pointers which point to static or dynamic array elements. Such pointers must point to
an element of the array, or to the first element past the array. Pointer arithmetic is completely
forbidden on pointers which are null, or which point to a non-array.
• The memory location of different memory blocks is not defined. Ordered comparison (<, <=,
>, >=) between two pointers is permitted when both pointers point to the same array, or when
at least one pointer is null.
324 CHAPTER 19. FUNCTIONS

• Pointer comparisons between independent memory blocks will generate a compile-time error,
unless two such comparisons are combined using && or || to yield a result which is independent
of the ordering of memory blocks. Each comparison must consist of two pointer expressions
compared with <, <=, >, or >=, and may optionally be negated with !.
For example, the expression (p1 > q1 && p2 <= q2) is permitted when p1, p2 are expressions
yielding pointers to memory block P, and q1, q2 are expressions yielding pointers to memory
block Q, even when P and Q are unrelated memory blocks. It returns true if [p1..p2] lies
inside [q1..q2], and false otherwise. Similarly, the expression (p1 < q1 | p2 > q2)| is true
if [p1..p2] lies outside [q1..q2], and false otherwise.
• Equality comparisons (==, !=, is, !is) are permitted between all pointers, without restriction.
• Any pointer may be cast to void * and from void * back to its original type. Casting between
pointer and non-pointer types is prohibited.

Note that the above restrictions apply only to expressions which are actually executed. For
example:
static int y = 0;

int countTen(int x)
{
if (x > 10)
++y;
return x;
}

static assert(countTen(6) == 6); // OK

static assert(countTen(12) == 12); // invalid, modifies y.
The __ctfe boolean pseudo-variable, which evaluates to true at compile time, but false at run
time, can be used to provide an alternative execution path to avoid operations which are forbidden
at compile time. Every usage of __ctfe is evaluated before code generation and therefore has no
run-time cost, even if no optimizer is used.
In order to be executed at compile time, the function must appear in a context where it must
be so executed, for example:

• initialization of a static variable

• dimension of a static array
• argument for a template value parameter

template eval( A... )

{
 325

const typeof(A[0]) eval = A[0];

}

int square(int i)
{
return i * i;
}

void foo()
{
static j = square(3); // compile time
writeln(j);
writeln(square(4)); // run time
writeln(eval!(square(5))); // compile time
}
Executing functions at compile time can take considerably longer than executing it at run time.
If the function goes into an infinite loop, it will hang at compile time (rather than hanging at run
time).
Non-recoverable errors (such as assert failures) do not throw exceptions; instead, they end
interpretation immediately.
Functions executed at compile time can give different results from run time in the following
scenarios:

• floating point computations may be done at a higher precision than run time
• dependency on implementation defined order of evaluation
• use of uninitialized variables

These are the same kinds of scenarios where different optimization settings affect the results.

String Mixins and Compile Time Function Execution

Any functions that execute at compile time must also be executable at run time. The compile time
evaluation of a function does the equivalent of running the function at run time. This means that
the semantics of a function cannot depend on compile time values of the function. For example:
int foo(char[] s)
{
return mixin(s);
}

const int x = foo("1");

326 CHAPTER 19. FUNCTIONS

is illegal, because the runtime code for foo() cannot be generated. A function template would
be the appropriate method to implement this sort of thing.

Function Safety
Safe functions are functions that are statically checked to exhibit no possibility of undefined behavior.
Undefined behavior is often used as a vector for malicious attacks.

Safe Functions
Safe functions are marked with the @safe attribute.
The following operations are not allowed in safe functions:

• No casting from a pointer type to any type other than void*.

• No casting from any non-pointer type to a pointer type.
• No modification of pointer values.
• Cannot access unions that have pointers or references overlapping with other types.
• Calling any system functions.
• No catching of exceptions that are not derived from class Exception.
• No inline assembler.
• No explicit casting of mutable objects to immutable.
• No explicit casting of immutable objects to mutable.
• No explicit casting of thread local objects to shared.
• No explicit casting of shared objects to thread local.
• No taking the address of a local variable or function parameter.
• Cannot access __gshared variables.

Functions nested inside safe functions default to being safe functions.

Safe functions are covariant with trusted or system functions.
Note: The verifiable safety of functions may be compromised by bugs in the compiler and
specification. Please report all such errors so they can be corrected.

Trusted Functions
Trusted functions are marked with the @trusted attribute.
Trusted functions are guaranteed by the programmer to not exhibit any undefined behavior if
called by a safe function. Generally, trusted functions should be kept small so that they are easier
to manually verify.
Trusted functions may call safe, trusted, or system functions.
Trusted functions are covariant with safe or system functions.
 327

System Functions
System functions are functions not marked with @safe or @trusted and are not nested inside @safe
functions. System functions may be marked with the @system attribute. A function being system
does not mean it actually is unsafe, it just means that the compiler is unable to verify that it cannot
exhibit undefined behavior.
System functions are not covariant with trusted or safe functions.

Function Attribute Inference

FunctionLiteral s and function templates, since their function bodies are always present, infer the
pure, nothrow, and @safe attributes unless specifically overridden.
Attribute inference is not done for other functions, even if the function body is present.
The inference is done by determining if the function body follows the rules of the particular
attribute.
Cyclic functions (i.e. functions that wind up directly or indirectly calling themselves) are inferred
as being impure, throwing, and @system.
If a function attempts to test itself for those attributes, then the function is inferred as not
having those attributes.

Uniform Function Call Syntax (UFCS)

A free function can be called with a syntax that looks as if the function were a member function of
its first parameter type.
void func(X thisObj);

X obj;
obj.func();
// If ’obj’ does not have regular member ’func’,
// it’s automatically rewritten to ’func(obj)’
This provides a way to add functions to a class externally as if they were public final member
functions, which enables function chaining and component programming.
stdin.byLine(KeepTerminator.yes)
.map!(a => a.idup)
.array
.sort
.copy(stdout.lockingTextWriter());
It also works with @property functions:
328 CHAPTER 19. FUNCTIONS

@property prop(X thisObj);

@property prop(X thisObj, int value);

X obj;
obj.prop; // Rewrites to: prop(obj);
obj.prop = 1; // Rewrites to: prop(obj, 1);
Syntactically parenthesis-less check for @property functions is done at the same time as UFCS
rewrite.
When UFCS rewrite is necessary, compiler searches the name on accessible module level scope,
in order from the innermost scope.
module a;
void foo(X);
alias boo = foo;
void main()
{
void bar(X);
import b : baz; // void baz(X);

X obj;
obj.foo(); // OK, calls a.foo;
//obj.bar(); // NG, UFCS does not see nested functions
obj.baz(); // OK, calls b.baz, because it is declared at the
// top level scope of module b

import b : boo = baz;

obj.boo(); // OK, calls aliased b.baz instead of a.boo (== a.foo),
// because the declared alias name ’boo’ in local scope
// overrides module scope name
}
class C
{
void mfoo(X);
static void sbar(X);
import b : ibaz = baz; // void baz(X);
void test()
{
X obj;
//obj.mfoo(); // NG, UFCS does not see member functions
//obj.sbar(); // NG, UFCS does not see static member functions
 329

obj.ibaz(); // OK, ibaz is an alias of baz which declared at

// the top level scope of module b
}
}
The reason why local symbols are not considered by UFCS, is to avoid unexpected name conflicts.
See below problematic examples.
int front(int[] arr) { return arr[0]; }

void main()
{
int[] a = [1,2,3];
auto x = a.front(); // call .front by UFCS

auto front = x; // front is now a variable

auto y = a.front(); // Error, front is not a function
}

class C
{
int[] arr;
int front()
{
return arr.front(); // Error, C.front is not callable
// using argument types (int[])
}
}
Chapter 20

Operator Overloading

Operator overloading is accomplished by rewriting operators whose operands are class or struct
objects into calls to specially named member functions. No additional syntax is used.

• Unary Operator Overloading

• Cast Operator Overloading
• Binary Operator Overloading
• Overloading the Comparison Operators

– Overloading == and !=
– Overloading <, <=, >, and >=

• Function Call Operator Overloading

• Assignment Operator Overloading
• Op Assignment Operator Overloading
• Array Indexing and Slicing Operators Overloading

– Index Operator Overloading

– Slice Operator Overloading
– Dollar Operator Overloading

• Forwarding
• D1 style operator overloading

331
332 CHAPTER 20. OPERATOR OVERLOADING

20.1 Unary Operator Overloading

Overloadable Unary Operators
op rewrite
-e e.opUnary!("-")()
+e e.opUnary!("+")()
~e e.opUnary!("~")()
*e e.opUnary!("*")()
++e e.opUnary!("++")()
--e e.opUnary!("--")()

For example, in order to overload the - (negation) operator for struct S, and no other operator:
struct S
{
int m;

int opUnary(string s)() if (s == "-")

{
return -m;
}
}

int foo(S s)
{
return -s;
}

Postincrement e++ and Postdecrement e-- Operators

These are not directly overloadable, but instead are rewritten in terms of the ++e and –e prefix
operators:

Postfix Operator Rewrites

op rewrite
e-- (auto t = e, --e, t)
e++ (auto t = e, ++e, t)
20.1. UNARY OPERATOR OVERLOADING 333

Overloading Index Unary Operators

Overloadable Index Unary Operators
op rewrite
.opIndexUna
-a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] a Ç \text
.opIndexUna
+a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] a Ç \text
.opIndexUna
~a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] a Ç \text
.opIndexUna
*a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] a Ç \text
.opIndexUna
++a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] a Ç \text
.opIndexUna
--a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] a Ç \text

Overloading Slice Unary Operators

Overloadable Slice Unary Operators
op rewrite
-a[i..j ] a.opIndexUnary!("-")(a.opSlice(i, j ))
+a[i..j ] a.opIndexUnary!("+")(a.opSlice(i, j ))
~a[i..j ] a.opIndexUnary!("~")(a.opSlice(i, j ))
*a[i..j ] a.opIndexUnary!("*")(a.opSlice(i, j ))
++a[i..j ] a.opIndexUnary!("++")(a.opSlice(i, j ))
--a[i..j ] a.opIndexUnary!("--")(a.opSlice(i, j ))
-a[ ] a.opIndexUnary!("-")()
+a[ ] a.opIndexUnary!("+")()
~a[ ] a.opIndexUnary!("~")()
*a[ ] a.opIndexUnary!("*")()
++a[ ] a.opIndexUnary!("++")()
--a[ ] a.opIndexUnary!("--")()

For backward compatibility, if the above rewrites fail and opSliceUnary is defined, then the
rewrites a.opSliceUnary!(op)(a, i, j) and a.opSliceUnary!(op) are tried instead, respec-
tively.
334 CHAPTER 20. OPERATOR OVERLOADING

20.2 Cast Operator Overloading

Cast Operators
op rewrite
cast(type ) \textit{e} e.opCast!(type)()

Boolean Operations
Notably absent from the list of overloaded unary operators is the ! logical negation operator. More
obscurely absent is a unary operator to convert to a bool result. Instead, these are covered by a
rewrite to:
opCast!(bool)(e)
So,
if (e) => if (e.opCast!(bool))
if (!e) => if (!e.opCast!(bool))
etc., whenever a bool result is expected. This only happens, however, for instances of structs.
Class references are converted to bool by checking to see if the class reference is null or not.

20.3 Binary Operator Overloading

The following binary operators are overloadable:

Overloadable Binary Operators

+ - * / % ^^ &
| ^ << >> >>> ~ in

The expression:
a op b
is rewritten as both:
a.opBinary!(\textquotedblleft{}op \textquotedblright{})(b)
b.opBinaryRight!(\textquotedblleft{}op \textquotedblright{})(a)
and the one with the ‘better’ match is selected. It is an error for both to equally match.
Operator overloading for a number of operators can be done at the same time. For example, if
only the + or - operators are supported:
20.4. OVERLOADING THE COMPARISON OPERATORS 335

T opBinary(string op)(T rhs)

{
static if (op == "+") return data + rhs.data;
else static if (op == "-") return data - rhs.data;
else static assert(0, "Operator␣"~op~"␣not␣implemented");
}

To do them all en masse:

T opBinary(string op)(T rhs)

{
return mixin("data␣"~op~"␣rhs.data");
}

20.4 Overloading the Comparison Operators

D allows overloading of the comparison operators ==, !=, <, <=, >=, > via two functions, opEquals
and opCmp.
The equality and inequality operators are treated separately because while practically all user-
defined types can be compared for equality, only a subset of types have a meaningful ordering. For
example, while it makes sense to determine if two RGB color vectors are equal, it is not meaningful
to say that one color is greater than another, because colors do not have an ordering. Thus, one
would define opEquals for a Color type, but not opCmp.
Furthermore, even with orderable types, the order relation may not be linear. For example, one
may define an ordering on sets via the subset relation, such that x < y is true if x is a (strict) subset
of y. If x and y are disjoint sets, then neither x < y nor y < x holds, but that does not imply that
x == y. Thus, it is insufficient to determine equality purely based on opCmp alone. For this reason,
opCmp is only used for the inequality operators <, <=, >=, and >. The equality operators == and !=
always employ opEquals instead.
Therefore, it is the programmer’s responsibility to ensure that opCmp and opEquals are
consistent with each other. If opEquals is not specified, the compiler provides a default
version that does member-wise comparison. If this suffices, one may define only opCmp to customize
the behaviour of the inequality operators. But if not, then a custom version of opEquals should
be defined as well, in order to preserve consistent semantics between the two kinds of comparison
operators.
Finally, if the user-defined type is to be used as a key in the built-in associative arrays, then
the programmer must ensure that the semantics of opEquals and toHash are consistent. If not, the
associative array may not work in the expected manner.
336 CHAPTER 20. OPERATOR OVERLOADING

Overloading == and !=
Expressions of the form a != b are rewritten as !(a == b).
Given a == b :

1. If a and b are both class objects, then the expression is rewritten as:
.object.opEquals(a, b)
and that function is implemented as:
bool opEquals(Object a, Object b)
{
if (a is b) return true;
if (a is null || b is null) return false;
if (typeid(a) == typeid(b)) return a.opEquals(b);
return a.opEquals(b) && b.opEquals(a);
}
2. Otherwise the expressions a.opEquals(b) and b.opEquals(a) are tried. If both re-
solve to the same opEquals function, then the expression is rewritten to be
a.opEquals(b).
3. If one is a better match than the other, or one compiles and the other does not, the first is
selected.
4. Otherwise, an error results.

If overridding Object.opEquals() for classes, the class member function signature should look
like:
class C
{
override bool opEquals(Object o) { ... }
}
If structs declare an opEquals member function for the identity comparison, it could have several
forms, such as:
struct S
{
// lhs should be mutable object
bool opEquals(const S s) { ... } // for r-values (e.g. temporaries)
bool opEquals(ref const S s) { ... } // for l-values (e.g. variables)

// both hand side can be const object

20.4. OVERLOADING THE COMPARISON OPERATORS 337

bool opEquals(const S s) const { ... } // for r-values (e.g. temporaries)

}
Alternatively, you can declare a single templated opEquals function with an auto ref parameter:
struct S
{
// for l-values and r-values,
// with converting both hand side implicitly to const
bool opEquals()(auto ref const S s) const { ... }
}

Overloading <, <=, >, and >=

Comparison operations are rewritten as follows:

Overloadable Unary Operators

comparison rewrite 1 rewrite 2
a <b a.opCmp(b) <0 b.opCmp(a) >0
a <= b a.opCmp(b) <= 0 b.opCmp(a) >= 0
a >b a.opCmp(b) >0 b.opCmp(a) <0
a >= b a.opCmp(b) >= 0 b.opCmp(a) <= 0

Both rewrites are tried. If only one compiles, that one is taken. If they both resolve to the same
function, the first rewrite is done. If they resolve to different functions, the best matching one is
used. If they both match the same, but are different functions, an ambiguity error results.
If overriding Object.opCmp() for classes, the class member function signature should look like:
class C
{
override int opCmp(Object o) { ... }
}
If structs declare an opCmp member function, it should have the following form:
struct S
{
int opCmp(ref const S s) const { ... }
}
Note that opCmp is only used for the inequality operators; expressions like a == b always uses
opEquals. If opCmp is defined but opEquals isn’t, the compiler will supply a default version of
opEquals that performs member-wise comparison. If this member-wise comparison is not consistent
338 CHAPTER 20. OPERATOR OVERLOADING

with the user-defined opCmp, then it is up to the programmer to supply an appropriate

version of opEquals. Otherwise, inequalities like a <= b will behave inconsistently with equalities
like a == b.

20.5 Function Call Operator Overloading f()

The function call operator, (), can be overloaded by declaring a function named opCall:
struct F
{
int opCall();
int opCall(int x, int y, int z);
}

void test()
{
F f;
int i;

i = f(); // same as i = f.opCall();

i = f(3,4,5); // same as i = f.opCall(3,4,5);
}
In this way a struct or class object can behave as if it were a function.
Note that merely declaring opCall automatically disables struct literal syntax. To avoid the
limitation, you need to also declare a constructor so that it takes priority over opCall in Type(...)
syntax.
struct Multiplier
{
int factor;
this(int num) { factor = num; }
int opCall(int value) { return value * factor; }
}
void test()
{
Multiplier m = Multiplier(10); // invoke constructor
int result = m(5); // invoke opCall
assert(result == 50);
}
20.6. ASSIGNMENT OPERATOR OVERLOADING 339

Static opCall
static opCall also works as expected for a function call operator with type names.
struct Double
{
static int opCall(int x) { return x * 2; }
}
void test()
{
int i = Double(2);
assert(i == 4);
}
Mixing struct constructors and static opCall is not allowed.
struct S
{
this(int i) {}
static S opCall() // disallowed due to constructor
{
return S.init;
}
}
Note: static opCall can be used to simulate struct constructors with no arguments, but this
is not recommended practice. Instead, the preferred solution is to use a factory function to create
struct instances.

20.6 Assignment Operator Overloading

The assignment operator = can be overloaded if the left hand side is a struct aggregate, and opAssign
is a member function of that aggregate.
For struct types, operator overloading for the identity assignment is allowed.
struct S
{
// identiy assignment, allowed.
void opAssign(S rhs);

// not identity assignment, also allowed.

void opAssign(int);
}
340 CHAPTER 20. OPERATOR OVERLOADING

S s;
s = S(); // Rewritten to s.opAssign(S());
s = 1; // Rewritten to s.opAssign(1);
However for class types, identity assignment is not allowed. All class types have reference
semantics, so identity assignment by default rebinds the left-hand-side to the argument at the
right, and this is not overridable.
class C
{
// If X is the same type as C or the type which is
// implicitly convertible to C, then opAssign would
// accept identity assignment, which is disallowed.
// C opAssign(...);
// C opAssign(X);
// C opAssign(X, ...);
// C opAssign(X ...);
// C opAssign(X, U = defaultValue, etc.);

// not an identity assignment - allowed

void opAssign(int);
}
C c = new C();
c = new C(); // Rebinding referencee
c = 1; // Rewritten to c.opAssign(1);

Index Assignment Operator Overloading

If the left hand side of an assignment is an index operation on a struct or class instance, it
can be overloaded by providing an opIndexAssign member function. Expressions of the form
a[\textit{b}₁, \textit{b}₂, ... \textit{b}_n] = c
are rewritten as a.opIndexAssign(c,\textit{b}₁, \textit{b}₂, ⤦
Ç ... \textit{b}_n).
struct A
{
int opIndexAssign(int value, size_t i1, size_t i2);
}

void test()
{
20.7. OP ASSIGNMENT OPERATOR OVERLOADING 341

A a;
a[i,3] = 7; // same as a.opIndexAssign(7,i,3);
}

Slice Assignment Operator Overloading

If the left hand side of an assignment is a slice operation on a struct or class instance, it can be
overloaded by implementing an opIndexAssign member function that takes the return
value of the opSlice function as parameter(s). Expressions of the form a[i..j ] = c are
rewritten as a.opIndexAssign(c, a.opSlice(i, j )), and a[] = c as a.opIndexAssign(c).
See Array Indexing and Slicing Operators Overloading for more details.
struct A
{
int opIndexAssign(int v); // overloads a[] = v
int opIndexAssign(int v, size_t[2] x); // overloads a[i .. j] = v
int[2] opSlice(size_t x, size_t y); // overloads i .. j
}

void test()
{
A a;
int v;

a[] = v; // same as a.opIndexAssign(v);

a[3..4] = v; // same as a.opIndexAssign(v, a.opSlice(3,4));
}
For backward compatibility, if rewriting a[i..j ] as a.opIndexAssign(a.opSlice(i, j )) fails to
compile, the legacy rewrite opSliceAssign(c, i, j ) is used instead.

20.7 Op Assignment Operator Overloading

The following op assignment operators are overloadable:

Overloadable Op Assignment Operators

+= -= *= /= %= ^^= &=
|= ^= <<= >>= >>>= ~=

The expression:
342 CHAPTER 20. OPERATOR OVERLOADING

a op = b
is rewritten as:
a.opOpAssign!(\textquotedblleft{}op \textquotedblright{})(b)

Index Op Assignment Operator Overloading

If the left hand side of an op= is an index expression on a struct or class instance and
opIndexOpAssign is a member:
a[b₁, b₂, ... b_n ] op = c
it is rewritten as:
a.opIndexOpAssign!(\textquotedblleft{}op \textquotedblright{})(c, b₁,
b₂, ... b_n )

Slice Op Assignment Operator Overloading

If the left hand side of an op= is a slice expression on a struct or class instance and opIndexOpAssign
is a member:
a[i..j ] op = c
it is rewritten as:
a.opIndexOpAssign!(\textquotedblleft{}op \textquotedblright{})(c, a.opSlice(i, j ))
and
a[] op = c
it is rewritten as:
a.opIndexOpAssign!(\textquotedblleft{}op \textquotedblright{})(c)
For backward compatibility, if the above rewrites fail and opSliceOpAssign is de-
fined, then the rewrites a.opSliceOpAssign(c, i, j) and a.opSliceOpAssign(c) are tried, re-
spectively.

20.8 Array Indexing and Slicing Operators Overloading

The array indexing and slicing operators are overloaded by implementing the opIndex, opSlice,
and opDollar methods. These may be combined to implement multidimensional arrays.
20.8. ARRAY INDEXING AND SLICING OPERATORS OVERLOADING 343

Index Operator Overloading

Expressions of the form arr[b₁, b₂, ... b_n] are trans-
lated into arr.opIndex(b₁, b₂, ... b_n). For example:
struct A
{
int opIndex(size_t i1, size_t i2, size_t i3);
}

void test()
{
A a;
int i;
i = a[5,6,7]; // same as i = a.opIndex(5,6,7);
}
In this way a struct or class object can behave as if it were an array.
If an index expression can be rewritten using opIndexAssign or opIndexOpAssign, those are
preferred over opIndex.

Slice Operator Overloading

Overloading the slicing operator means overloading expressions like a[] or a[i..j ], where the ex-
pressions inside the square brackets contain slice expressions of the form i..j.
To overload a[], simply define opIndex with no parameters:
struct S
{
int[] impl;
int[] opIndex()
{
return impl[];
}
}
void test()
{
auto s = S([1,2,3]);
auto t = s[]; // calls s.opIndex()
assert(t == [1,2,3]);
}
344 CHAPTER 20. OPERATOR OVERLOADING

To overload array indexing of the form a[i..j , ...], two steps are needed. First, the expressions
of the form i..j are translated via opSlice into user-defined objects that encapsulate the endpoints
i and j. Then these user-defined objects are passed to opIndex to perform the actual slicing. This
design was chosen in order to support mixed indexing and slicing in multidimensional arrays; for
example, in translating expressions like arr[1, 2..3, 4].
More precisely, an expression of the form arr[b₁, b₂, ...
b_n] is translated into arr.opIndex(c₁, c₂, ...
c_n). Each argument b_i can be either a single expression, in which
case it is passed directly as the corresponding argument c_i to opIndex; or it can be
a slice expression of the form x _i..y_i, in which case the corresponding
argument c_i to opIndex is arr.opSlice!i(x _i, y_i).
Namely:

op rewrite
arr[1, 2, 3] arr.opIndex(1, 2, 3)
arr[1..2, 3..4, 5..6] arr.opIndex(arr.opSlice!0(1,2), arr.opSlice!1(3,4), arr.opSlice!2(5,6))
arr[1, 2..3, 4] arr.opIndex(1, arr.opSlice!1(2,3), 4)

Similar translations are done for assignment operators involving slicing, for example:

op rewrite
arr[1, 2..3, 4] = c arr.opIndexAssign(c, 1, arr.opSlice!1(2, 3), 4)
arr[2, 3..4] += c arr.opIndexOpAssign!"+"(c, 2, arr.opSlice!1(2, 3))

The intention is that opSlice!i should return a user-defined object that represents an interval
of indices along the i’th dimension of the array. This object is then passed to opIndex to perform
the actual slicing operation. If only one-dimensional slicing is desired, opSlice may be declared
without the compile-time parameter i.
Note that in all cases, arr is only evaluated once. Thus, an expression like getArray()[1, ⤦
Ç 2..3, $-1]=c has the effect of:
auto __tmp = getArray();
__tmp.opIndexAssign(c, 1, __tmp.opSlice!1(2,3), __tmp.opDollar!2 - 1);
where the initial function call to getArray is only executed once.
For backward compatibility, a[] and a[i..j ] can also be overloaded by implementing opSlice()
with no arguments and opSlice(i, j ) with two arguments, respectively. This only applies for one-
dimensional slicing, and dates from when D did not have full support for multidimensional arrays.
This usage of opSlice is discouraged.
20.8. ARRAY INDEXING AND SLICING OPERATORS OVERLOADING 345

Dollar Operator Overloading

Within the arguments to array index and slicing operators, $ gets translated to opDollar!i, where
i is the position of the expression $ appears in. For example:

op rewrite
arr[$-1, $-2, 3] arr.opIndex(arr.opDollar!0 - 1, arr.opDollar!1 - 2, 3)
arr[1, 2, 3..$] arr.opIndex(1, 2, arr.opSlice!2(3, arr.opDollar!2))

The intention is that opDollar!i should return the length of the array along its i’th dimension,
or a user-defined object representing the end of the array along that dimension, that is understood
by opSlice and opIndex.
struct Rectangle
{
int width, height;
int[][] impl;
this(int w, int h)
{
width = w;
height = h;
impl = new int[w][h];
}
int opIndex(size_t i1, size_t i2)
{
return impl[i1][i2];
}
int opDollar(size_t pos)()
{
static if (pos==0)
return width;
else
return height;
}
}

void test()
{
auto r = Rectangle(10,20);
int i = r[$-1, 0]; // same as: r.opIndex(r.opDollar!0, 0),
346 CHAPTER 20. OPERATOR OVERLOADING

// which is r.opIndex(r.width-1, 0)
int j = r[0, $-1]; // same as: r.opIndex(0, r.opDollar!1)
// which is r.opIndex(0, r.height-1)
}
As the above example shows, a different compile-time argument is passed to opDollar de-
pending on which argument it appears in. A $ appearing in the first argument gets translated to
opDollar!0, a $ appearing in the second argument gets translated to opDollar!1, and so
on. Thus, the appropriate value for $ can be returned to implement multidimensional arrays.
Note that opDollar!i is only evaluated once for each i where $ occurs in the corresponding
position in the indexing operation. Thus, an expression like arr[$-sqrt($), 0, $-1] has the effect
of:
auto __tmp1 = arr.opDollar!0;
auto __tmp2 = arr.opDollar!2;
arr.opIndex(__tmp1 - sqrt(__tmp1), 0, __tmp2 - 1);
If opIndex is declared with only one argument, the compile-time argument to opDollar may be
omitted. In this case, it is illegal to use $ inside an array indexing expression with more than one
argument.

20.9 Forwarding
Member names not found in a class or struct can be forwarded to a template function named
opDispatch for resolution.
import std.stdio;

struct S
{
void opDispatch(string s, T)(T i)
{
writefln("S.opDispatch(’%s’,␣%s)", s, i);
}
}

class C
{
void opDispatch(string s)(int i)
{
writefln("C.opDispatch(’%s’,␣%s)", s, i);
}
20.10. D1 STYLE OPERATOR OVERLOADING 347

struct D
{
template opDispatch(string s)
{
enum int opDispatch = 8;
}
}

void main()
{
S s;
s.opDispatch!("hello")(7);
s.foo(7);

auto c = new C();

c.foo(8);

D d;
writefln("d.foo␣=␣%s", d.foo);
assert(d.foo == 8);
}

20.10 D1 style operator overloading

While the preferred style for operator overloading is to use the above mechanisms, the D1 oper-
ator overload mechanisms are still allowed. There is no guarantee that these mechanisms will be
supported in the future.
Chapter 21

Templates

I think that I can safely say that nobody understands C++ template mechanics.

– Richard Deyman

Templates are D’s approach to generic programming. Templates are defined with a Templat-
eDeclaration:

TemplateDeclaration:
template Identifier TemplateParameters Constraint opt { DeclDefs opt }

TemplateParameters:
( TemplateParameterList opt )

TemplateParameterList:
TemplateParameter
TemplateParameter ,
TemplateParameter , TemplateParameterList

TemplateParameter:
TemplateTypeParameter
TemplateValueParameter
TemplateAliasParameter
TemplateTupleParameter
TemplateThisParameter

349
350 CHAPTER 21. TEMPLATES

The body of the TemplateDeclaration must be syntactically correct even if never instantiated.
Semantic analysis is not done until instantiated. A template forms its own scope, and the template
body can contain classes, structs, types, enums, variables, functions, and other templates.
Template parameters can be types, values, symbols, or tuples. Types can be any type. Value
parameters must be of an integral type, floating point type, or string type and specializations for
them must resolve to an integral constant, floating point constant, null, or a string literal. Symbols
can be any non-local symbol. Tuples are a sequence of 0 or more types, values or symbols.
Template parameter specializations constrain the values or types the TemplateParameter can
accept.
Template parameter defaults are the value or type to use for the TemplateParameter in case
one is not supplied.

21.1 Explicit Template Instantiation

Templates are explicitly instantiated with:

TemplateInstance:
Identifier TemplateArguments

TemplateArguments:
! ( TemplateArgumentList opt )
! TemplateSingleArgument

TemplateArgumentList:
TemplateArgument
TemplateArgument ,
TemplateArgument , TemplateArgumentList

TemplateArgument:
Type
AssignExpression
Symbol

Symbol:
SymbolTail
. SymbolTail

SymbolTail:
Identifier
Identifier . SymbolTail
21.1. EXPLICIT TEMPLATE INSTANTIATION 351

TemplateInstance
TemplateInstance . SymbolTail

TemplateSingleArgument:
Identifier
BasicTypeX
CharacterLiteral
StringLiteral
IntegerLiteral
FloatLiteral
true
false
null
this
SpecialKeyword

Once instantiated, the declarations inside the template, called the template members, are in the
scope of the TemplateInstance:
template TFoo(T) { alias t = T*; }
...
TFoo!(int).t x; // declare x to be of type int*
If the TemplateArgument is one token long, the parentheses can be omitted:
TFoo!int.t x; // same as TFoo!(int).t x;
A template instantiation can be aliased:
template TFoo(T) { alias t = T*; }
alias abc = TFoo!(int);
abc.t x; // declare x to be of type int*
Multiple instantiations of a TemplateDeclaration with the same TemplateArgumentList all will
refer to the same instantiation. For example:
template TFoo(T) { T f; }
alias a = TFoo!(int);
alias b = TFoo!(int);
...
a.f = 3;
assert(b.f == 3); // a and b refer to the same instance of TFoo
352 CHAPTER 21. TEMPLATES

This is true even if the TemplateInstances are done in different modules.

Even if template arguments are implicitly converted to the same template parameter type, they
still refer to same instance:
struct TFoo(int x) { }

// 3 and 2+1 are both 3 of type int

static assert(is(TFoo!(3) == TFoo!(2 + 1)));

// 3u is implicitly converted to 3 to match int parameter,

// and refers exactly same instance with TFoo!(3).
static assert(is(TFoo!(3) == TFoo!(3u)));
If multiple templates with the same Identifier are declared, they are distinct if they have a
different number of arguments or are differently specialized.
For example, a simple generic copy template would be:
template TCopy(T)
{
void copy(out T to, T from)
{
to = from;
}
}
To use the template, it must first be instantiated with a specific type:
int i;
TCopy!(int).copy(i, 3);

21.2 Instantiation Scope

TemplateInstantances are always performed in the scope of where the TemplateDeclaration is de-
clared, with the addition of the template parameters being declared as aliases for their deduced
types.
For example:
module a
template TFoo(T) { void bar() { func(); } }
module b
import a;
21.3. ARGUMENT DEDUCTION 353

void func() { }
alias f = TFoo!(int); // error: func not defined in module a
and:
module a
template TFoo(T) { void bar() { func(1); } }
void func(double d) { }
module b
import a;

void func(int i) { }
alias f = TFoo!(int);
...
f.bar(); // will call a.func(double)
TemplateParameter specializations and default values are evaluated in the scope of the Tem-
plateDeclaration.

21.3 Argument Deduction

The types of template parameters are deduced for a particular template instantiation by comparing
the template argument with the corresponding template parameter.
For each template parameter, the following rules are applied in order until a type is deduced for
each parameter:

1. If there is no type specialization for the parameter, the type of the parameter is set to the
template argument.
2. If the type specialization is dependent on a type parameter, the type of that parameter is set
to be the corresponding part of the type argument.
3. If after all the type arguments are examined there are any type parameters left with no type
assigned, they are assigned types corresponding to the template argument in the same position
in the TemplateArgumentList.
4. If applying the above rules does not result in exactly one type for each template parameter,
then it is an error.

For example:
template TFoo(T) { }
alias Foo1 = TFoo!(int); // (1) T is deduced to be int
alias Foo2 = TFoo!(char*); // (1) T is deduced to be char*
354 CHAPTER 21. TEMPLATES

template TBar(T : T*) { }

alias Foo3 = TBar!(char*); // (2) T is deduced to be char

template TAbc(D, U : D[]) { }

alias Bar1 = TAbc!(int, int[]); // (2) D is deduced to be int, U is int[]
alias Bar2 = TAbc!(char, int[]); // (4) error, D is both char and int

template TDef(D : E*, E) { }

alias Bar3 = TDef!(int*, int); // (1) E is int
// (3) D is int*
Deduction from a specialization can provide values for more than one parameter:
template Foo(T: T[U], U)
{
...
}

Foo!(int[long]) // instantiates Foo with T set to int, U set to long

When considering matches, a class is considered to be a match for any super classes or interfaces:
class A { }
class B : A { }

template TFoo(T : A) { }
alias Foo4 = TFoo!(B); // (3) T is B

template TBar(T : U*, U : A) { }

alias Foo5 = TBar!(B*, B); // (2) T is B*
// (3) U is B

21.4 Template Type Parameters

TemplateTypeParameter:
Identifier
Identifier TemplateTypeParameterSpecialization
Identifier TemplateTypeParameterDefault
Identifier TemplateTypeParameterSpecialization TemplateTypeParameterDefault
21.5. TEMPLATE THIS PARAMETERS 355

TemplateTypeParameterSpecialization:
: Type

TemplateTypeParameterDefault:
= Type

Specialization
Templates may be specialized for particular types of arguments by following the template parameter
identifier with a : and the specialized type. For example:
template TFoo(T) { ... } // #1
template TFoo(T : T[]) { ... } // #2
template TFoo(T : char) { ... } // #3
template TFoo(T, U, V) { ... } // #4

alias foo1 = TFoo!(int); // instantiates #1

alias foo2 = TFoo!(double[]); // instantiates #2 with T being double
alias foo3 = TFoo!(char); // instantiates #3
alias fooe = TFoo!(char, int); // error, number of arguments mismatch
alias foo4 = TFoo!(char, int, int); // instantiates #4
The template picked to instantiate is the one that is most specialized that fits the types of the
TemplateArgumentList. Determine which is more specialized is done the same way as the C++
partial ordering rules. If the result is ambiguous, it is an error.

21.5 Template This Parameters

TemplateThisParameter:
this TemplateTypeParameter

TemplateThisParameter s are used in member function templates to pick up the type of the this
reference.
import std.stdio;

struct S
{
const void foo(this T)(int i)
{
356 CHAPTER 21. TEMPLATES

writeln(typeid(T));
}
}

void main()
{
const(S) s;
(&s).foo(1);
S s2;
s2.foo(2);
immutable(S) s3;
s3.foo(3);
}
Prints:
const(S) S immutable(S)
This is especially useful when used with inheritance. For example, you might want to implement
a final base method which returns a derived class type. Typically you would return a base type,
but this won’t allow you to call or access derived properties of the type:
interface Addable(T)
{
final auto add(T t)
{
return this;
}
}

class List(T) : Addable!T

{
List remove(T t)
{
return this;
}
}

void main()
{
auto list = new List!int;
list.add(1).remove(1); // error: no ’remove’ method for Addable!int
}
21.6. TEMPLATE VALUE PARAMETERS 357

Here the method add returns the base type, which doesn’t implement the remove method. The
template this parameter can be used for this purpose:
interface Addable(T)
{
final R add(this R)(T t)
{
return cast(R)this; // cast is necessary, but safe
}
}

class List(T) : Addable!T

{
List remove(T t)
{
return this;
}
}

void main()
{
auto list = new List!int;
list.add(1).remove(1); // ok
}

21.6 Template Value Parameters

TemplateValueParameter:
BasicType Declarator
BasicType Declarator TemplateValueParameterSpecialization
BasicType Declarator TemplateValueParameterDefault
BasicType Declarator TemplateValueParameterSpecialization TemplateValueParameterDefault

TemplateValueParameterSpecialization:
: ConditionalExpression

TemplateValueParameterDefault:
= AssignExpression
= SpecialKeyword
358 CHAPTER 21. TEMPLATES

Template value parameter types can be any type which can be statically initialized at compile
time. Template value arguments can be integer values, floating point values, nulls, string values,
array literals of template value arguments, associative array literals of template value arguments,
or struct literals of template value arguments.
template foo(string s)
{
string bar() { return s ~ "␣betty"; }
}

void main()
{
writefln("%s", foo!("hello").bar()); // prints: hello betty
}
This example of template foo has a value parameter that is specialized for 10:
template foo(U : int, int T : 10)
{
U x = T;
}

void main()
{
assert(foo!(int, 10).x == 10);
}

21.7 Template Alias Parameters

TemplateAliasParameter:
alias Identifier TemplateAliasParameterSpecialization opt TemplateAliasParameterDefault opt
alias BasicType Declarator TemplateAliasParameterSpecialization opt TemplateAliasParameterDefau

TemplateAliasParameterSpecialization:
: Type
: ConditionalExpression

TemplateAliasParameterDefault:
= Type
= ConditionalExpression
21.7. TEMPLATE ALIAS PARAMETERS 359

Alias parameters enable templates to be parameterized with any type of D symbol, including
global names, local names, module names, template names, and template instance names. Literals
can also be used as arguments to alias parameters.

• Global names
int x;

template Foo(alias X)
{
static int* p = &X;
}

void test()
{
alias bar = Foo!(x);
*bar.p = 3; // set x to 3
static int y;
alias abc = Foo!(y);
*abc.p = 3; // set y to 3
}
• Type names
class Foo
{
static int p;
}

template Bar(alias T)
{
alias q = T.p;
}

void test()
{
alias bar = Bar!(Foo);
bar.q = 3; // sets Foo.p to 3
}
• Module names
import std.string;
360 CHAPTER 21. TEMPLATES

template Foo(alias X)
{
alias y = X.toString;
}

void test()
{
alias bar = Foo!(std.string);
bar.y(3); // calls std.string.toString(3)
}
• Template names
int x;

template Foo(alias X)
{
static int* p = &X;
}

template Bar(alias T)
{
alias abc = T!(x);
}

void test()
{
alias bar = Bar!(Foo);
*bar.abc.p = 3; // sets x to 3
}
• Template alias names
int x;

template Foo(alias X)
{
static int* p = &X;
}

template Bar(alias T)
21.7. TEMPLATE ALIAS PARAMETERS 361

{
alias q = T.p;
}

void test()
{
alias foo = Foo!(x);
alias bar = Bar!(foo);
*bar.q = 3; // sets x to 3
}

• Literals
template Foo(alias X, alias Y)
{
static int i = X;
static string s = Y;
}

void test()
{
alias foo = Foo!(3, "bar");
writeln(foo.i, foo.s); // prints 3bar
}

Typed alias parameters

Alias parameters can also be typed. These parameters will accept symbols of that type:
template Foo(alias int x) { }
int x;
float f;

Foo!x; // ok
Foo!f; // fails to instantiate

Specialization
Alias parameters can accept both literals and user-defined type symbols, but they are less specialized
than the matches to type parameters and value parameters:
362 CHAPTER 21. TEMPLATES

template Foo(T) { ... } // #1

template Foo(int n) { ... } // #2
template Foo(alias sym) { ... } // #3

struct S {}
int var;

alias foo1 = Foo!(S); // instantiates #1

alias foo2 = Foo!(1); // instantiates #2
alias foo3a = Foo!([1,2]); // instantiates #3
alias foo3b = Foo!(var); // instantiates #3

template Bar(alias A) { ... } // #4

template Bar(T : U!V, alias U, V...) { ... } // #5

class C(T) {}
alias bar = Bar!(C!int); // instantiates #5

21.8 Template Tuple Parameters

TemplateTupleParameter:
Identifier ...

If the last template parameter in the TemplateParameterList is declared as a TemplateTuplePa-

rameter, it is a match with any trailing template arguments. The sequence of arguments form a
Tuple. A Tuple is not a type, an expression, or a symbol. It is a sequence of any mix of types,
expressions or symbols.
A Tuple whose elements consist entirely of types is called a TypeTuple. A Tuple whose elements
consist entirely of expressions is called an ExpressionTuple.
A Tuple can be used as an argument list to instantiate another template, or as the list of
parameters for a function.
template Print(args...)
{
void print()
{
writeln("args␣are␣", args); // args is an ExpressionTuple
}
}
21.8. TEMPLATE TUPLE PARAMETERS 363

template Write(Args...)
{
void write(Args args) // Args is a TypeTuple
// args is an ExpressionTuple
{
writeln("args␣are␣", args);
}
}

void main()
{
Print!(1,’a’,6.8).print(); // prints: args are 1a6.8
Write!(int, char, double).write(1, ’a’, 6.8); // prints: args are 1a6.8
}

The number of elements in a Tuple can be retrieved with the .length property. The nth
element can be retrieved by indexing the Tuple with [n], and sub tuples can be created with the
slicing syntax.
Tuples are static compile time entities, there is no way to dynamically change, add, or remove
elements.
Template tuples can be deduced from the types of the trailing parameters of an implicitly
instantiated function template:
template print(T, Args...)
{
void print(T first, Args args)
{
writeln(first);
static if (args.length) // if more arguments
print(args); // recurse for remaining arguments
}
}

void main()
{
print(1, ’a’, 6.8);
}

prints:
1 a 6.8
364 CHAPTER 21. TEMPLATES

Template tuples can also be deduced from the type of a delegate or function parameter list
passed as a function argument:
import std.stdio;

/* Partially applies a delegate by tying its first argument to a particular value.

* R = return type
* T = first argument type
* Args = TypeTuple of remaining argument types
*/
R delegate(Args) partial(R, T, Args...)(R delegate(T, Args) dg, T first)
{
// return a closure
return (Args args) => dg(first, args);
}

void main()
{
int plus(int x, int y, int z)
{
return x + y + z;
}

auto plus_two = partial(&plus, 2);

writefln("%d", plus_two(6, 8)); // prints 16
}
See also: std.functional.partial

Specialization
If both a template with a tuple parameter and a template without a tuple parameter exactly match
a template instantiation, the template without a TemplateTupleParameter is selected.
template Foo(T) { pragma(msg, "1"); } // #1
template Foo(int n) { pragma(msg, "2"); } // #2
template Foo(alias sym) { pragma(msg, "3"); } // #3
template Foo(Args...) { pragma(msg, "4"); } // #4

import std.stdio;

// Any sole template argument will never match to #4

21.9. TEMPLATE PARAMETER DEFAULT VALUES 365

alias foo1 = Foo!(int); // instantiates #1

alias foo2 = Foo!(3); // instantiates #2
alias foo3 = Foo!(std); // instantiates #3

alias foo4 = Foo!(int, 3, std); // instantiates #4

21.9 Template Parameter Default Values

Trailing template parameters can be given default values:
template Foo(T, U = int) { ... }
Foo!(uint,long); // instantiate Foo with T as uint, and U as long
Foo!(uint); // instantiate Foo with T as uint, and U as int

template Foo(T, U = T*) { ... }

Foo!(uint); // instantiate Foo with T as uint, and U as uint*

21.10 Implicit Template Properties

If a template has exactly one member in it, and the name of that member is the same as the
template name, that member is assumed to be referred to in a template instantiation:
template Foo(T)
{
T Foo; // declare variable Foo of type T
}

void test()
{
Foo!(int) = 6; // instead of Foo!(int).Foo
}

21.11 Template Constructors

ConstructorTemplate:
this TemplateParameters Parameters MemberFunctionAttributes opt Constraint opt :
this TemplateParameters Parameters MemberFunctionAttributes opt Constraint opt FunctionBody

Templates can be used to form constructors for classes and structs.

366 CHAPTER 21. TEMPLATES

21.12 Aggregate Templates

ClassTemplateDeclaration:
class Identifier TemplateParameters Constraint opt BaseClassList opt AggregateBody
class Identifier TemplateParameters BaseClassList opt Constraint opt AggregateBody

InterfaceTemplateDeclaration:
interface Identifier TemplateParameters Constraint opt BaseInterfaceList opt AggregateBody
interface Identifier TemplateParameters BaseInterfaceList Constraint AggregateBody

StructTemplateDeclaration:
struct Identifier TemplateParameters Constraint opt AggregateBody

UnionTemplateDeclaration:
union Identifier TemplateParameters Constraint opt AggregateBody

If a template declares exactly one member, and that member is a class with the same name as
the template:
template Bar(T)
{
class Bar
{
T member;
}
}
then the semantic equivalent, called a ClassTemplateDeclaration can be written as:
class Bar(T)
{
T member;
}
Analogously to class templates, struct, union and interfaces can be transformed into templates
by supplying a template parameter list.

21.13 Function Templates

If a template declares exactly one member, and that member is a function with the same name as
the template, it is a function template declaration. Alternatively, a function template declaration
is a function declaration with a TemplateParameterList immediately preceding the Parameters.
21.13. FUNCTION TEMPLATES 367

A function template to compute the square of type T is:

T Square(T)(T t)
{
return t * t;
}
Function templates can be explicitly instantiated with a !(TemplateArgumentList):
writefln("The␣square␣of␣%s␣is␣%s", 3, Square!(int)(3));
or implicitly, where the TemplateArgumentList is deduced from the types of the function argu-
ments:
writefln("The␣square␣of␣%s␣is␣%s", 3, Square(3)); // T is deduced to be int
If there are fewer arguments supplied in the TemplateArgumentList than parameters in the
TemplateParameterList, the arguments fulfill parameters from left to right, and the rest of the
parameters are then deduced from the function arguments.
Function template type parameters that are to be implicitly deduced may not have specializa-
tions:
void Foo(T : T*)(T t) { ... }

int x,y;
Foo!(int*)(x); // ok, T is not deduced from function argument
Foo(&y); // error, T has specialization
Template arguments not implicitly deduced can have default values:
void Foo(T, U=T*)(T t) { U p; ... }

int x;
Foo(x); // T is int, U is int*
The deduced type parameter for dynamic array and pointer arguments has an unqualified head:
void foo(T)(T arg) { pragma(msg, T); }

int[] marr;
const(int[]) carr;
immutable(int[]) iarr;
foo(marr); // T == int[]
foo(carr); // T == const(int)[]
foo(iarr); // T == immutable(int)[]
368 CHAPTER 21. TEMPLATES

int* mptr;
const(int*) cptr;
immutable(int*) iptr;
foo(mptr); // T == int*
foo(cptr); // T == const(int)*
foo(iptr); // T == immutable(int)*
Function templates can have their return types deduced based on the first ReturnStatement in
the function:
auto Square(T)(T t)
{
return t * t;
}
If there is more than one return statement, then the types of the return statement expressions
must match. If there are no return statements, then the return type of the function template is
void.

21.14 Variable Templates

Same as aggregates and functions, variable declarations with Initializer can have optional template
parameters:
enum string constant(TL...) = TL.stringof;
ubyte[T.sizeof] storage(T) = 0;
auto array(alias a) = a;
These declarations are transformed into templates:
template constant(TL...)
{
enum string constant = TL.stringof;
}
template storage(T)
{
ubyte[T.sizeof] storage = 0;
}
template array(alias a)
{
auto array = a;
}
21.15. ALIAS TEMPLATES 369

21.15 Alias Templates

AliasDeclaration can also have optional template parameters:
alias Sequence(TL...) = TL;
It is lowered to:
template Sequence(TL...)
{
alias Sequence = TL;
}

Function Templates with Auto Ref Parameters

An auto ref function template parameter becomes a ref parameter if its corresponding argument is
an lvalue, otherwise it becomes a value parameter:
int foo(Args...)(auto ref Args args)
{
int result;

foreach (i, v; args)

{
if (v == 10)
assert(__traits(isRef, args[i]));
else
assert(!__traits(isRef, args[i]));
result += v;
}
return result;
}

void main()
{
int y = 10;
int r;
r = foo(8); // returns 8
r = foo(y); // returns 10
r = foo(3, 4, y); // returns 17
r = foo(4, 5, y); // returns 19
r = foo(y, 6, y); // returns 26
370 CHAPTER 21. TEMPLATES

}
Auto ref parameters can be combined with auto ref return attributes:
auto ref min(T, U)(auto ref T lhs, auto ref U rhs)
{
return lhs > rhs ? rhs : lhs;
}

void main()
{
int x = 7, y = 8;
int i;

i = min(4, 3); // returns 3

i = min(x, y); // returns 7
min(x, y) = 10; // sets x to 10
static assert(!__traits(compiles, min(3, y) = 10));
static assert(!__traits(compiles, min(y, 3) = 10));
}

21.16 Nested Templates

If a template is declared in aggregate or function local scope, the instantiated functions will implicitly
capture the context of the enclosing scope.
class C
{
int num;

this(int n) { num = n; }

template Foo()
{
// ’foo’ can access ’this’ reference of class C object.
void foo(int n) { this.num = n; }
}
}

void main()
{
21.16. NESTED TEMPLATES 371

auto c = new C(1);

assert(c.num == 1);

c.Foo!().foo(5);
assert(c.num == 5);

template Bar()
{
// ’bar’ can access local variable of ’main’ function.
void bar(int n) { c.num = n; }
}
Bar!().bar(10);
assert(c.num == 10);
}
Above, Foo!().foo will work just the same as a member function of class C, and Bar!().bar
will work just the same as a nested function within function main().
If a template has a template alias parameter, and is instantiated with a local symbol, the
instantiated function will implicitly become nested in order to access runtime data of the given
local symbol.
template Foo(alias sym)
{
void foo() { sym = 10; }
}

class C
{
int num;

this(int n) { num = n; }

void main()
{
assert(this.num == 1);

alias fooX = Foo!(C.num).foo;

// fooX will become member function implicitly, so &fooX returns ⤦

Ç delegate object.
static assert(is(typeof(&fooX) == delegate));
372 CHAPTER 21. TEMPLATES

fooX(); // called by using valid ’this’ reference.

assert(this.num == 10); // OK
}
}

void main()
{
new C(1).main();

int num;
alias fooX = Foo!num.foo;

// fooX will become nested function implicitly, so &fooX returns delegate ⤦

Ç object.
static assert(is(typeof(&fooX) == delegate));

fooX();
assert(num == 10); // OK
}
Not only functions, but also instantiated class and struct types can become nested via implicitly
captured context.
class C
{
int num;
this(int n) { num = n; }

class N(T)
{
// instantiated class N!T can become nested in C
T foo() { return num * 2; }
}
}

void main()
{
auto c = new C(10);
auto n = c.new N!int();
assert(n.foo() == 20);
21.16. NESTED TEMPLATES 373

void main()
{
int num = 10;
struct S(T)
{
// instantiated struct S!T can become nested in main()
T foo() { return num * 2; }
}
S!int s;
assert(s.foo() == 20);
}
A templated struct can become a nested struct if it is instantiated with a local symbol passed
as an aliased argument:
struct A(alias F)
{
int fun(int i) { return F(i); }
}

A!F makeA(alias F)() { return A!F(); }

void main()
{
int x = 40;
int fun(int i) { return x + i; }
A!fun a = makeA!fun();
assert(a.fun(2) == 42);
}

Limitation:
Currently nested templates can capture at most one context. As a typical example, non-static
template member functions cannot take local symbol by using template alias parameter.
class C
{
int num;
void foo(alias sym)() { num = sym * 2; }
}
374 CHAPTER 21. TEMPLATES

void main()
{
auto c = new C();
int var = 10;
c.foo!var(); // NG, foo!var requires two contexts, ’this’ and ’main()’
}
But, if one context is indirectly accessible from other context, it is allowed.
int sum(alias x, alias y)() { return x + y; }

void main()
{
int a = 10;
void nested()
{
int b = 20;
assert(sum!(a, b)() == 30);
}
nested();
}
Two local variables a and b are in different contexts, but outer context is indirectly accessible
from innter context, so nested template instance sum!(a, b) will capture only inner context.

21.17 Recursive Templates

Template features can be combined to produce some interesting effects, such as compile time eval-
uation of non-trivial functions. For example, a factorial template can be written:
template factorial(int n : 1)
{
enum { factorial = 1 }
}

template factorial(int n)
{
enum { factorial = n* factorial!(n-1) }
}

void test()
21.18. TEMPLATE CONSTRAINTS 375

{
writefln("%s", factorial!(4)); // prints 24
}

21.18 Template Constraints

Constraint:
if ( Expression )

Constraints are used to impose additional constraints on matching arguments to a template

beyond what is possible in the TemplateParameterList. The Expression is computed at compile
time and returns a result that is converted to a boolean value. If that value is true, then the
template is matched, otherwise the template is not matched.
For example, the following function template only matches with odd values of N:
void foo(int N)()
if (N & 1)
{
...
}
...
foo!(3)(); // ok, matches
foo!(4)(); // error, no match

21.19 Limitations
Templates cannot be used to add non-static members or virtual functions to classes. For example:
class Foo
{
template TBar(T)
{
T xx; // becomes a static member of Foo
int func(T) { ... } // non-virtual

static T yy; // Ok
static int func(T t, int y) { ... } // Ok
}
}
376 CHAPTER 21. TEMPLATES

Templates cannot be declared inside functions.

Templates cannot add functions to interfaces:
interface TestInterface { void tpl(T)(); } // error
Chapter 22

Template Mixins

A TemplateMixin takes an arbitrary set of declarations from the body of a TemplateDeclaration

and inserts them into the current context.

TemplateMixinDeclaration:
mixin template Identifier TemplateParameters Constraint opt { DeclDefs opt }

TemplateMixin:
mixin MixinTemplateName TemplateArguments opt Identifier opt ;

MixinTemplateName:
. QualifiedIdentifierList
QualifiedIdentifierList
Typeof . QualifiedIdentifierList

QualifiedIdentifierList:
Identifier
Identifier . QualifiedIdentifierList
TemplateInstance . QualifiedIdentifierList

A TemplateMixin can occur in declaration lists of modules, classes, structs, unions, and as a
statement. The MixinTemplateName refers to a TemplateDeclaration. If the TemplateDeclaration
has no parameters, the mixin form that has no !(TemplateArgumentList) can be used.
Unlike a template instantiation, a template mixin’s body is evaluated within the scope where the
mixin appears, not where the template declaration is defined. It is analogous to cutting and pasting
the body of the template into the location of the mixin. It is useful for injecting parameterized

377
378 CHAPTER 22. TEMPLATE MIXINS

‘boilerplate’ code, as well as for creating templated nested functions, which is not possible with
template instantiations.
mixin template Foo()
{
int x = 5;
}

mixin Foo;

struct Bar
{
mixin Foo;
}

void test()
{
writefln("x␣=␣%d", x); // prints 5
{
Bar b;
int x = 3;

writefln("b.x␣=␣%d", b.x); // prints 5

writefln("x␣=␣%d", x); // prints 3
{
mixin Foo;
writefln("x␣=␣%d", x); // prints 5
x = 4;
writefln("x␣=␣%d", x); // prints 4
}
writefln("x␣=␣%d", x); // prints 3
}
writefln("x␣=␣%d", x); // prints 5
}
Mixins can be parameterized:
mixin template Foo(T)
{
T x = 5;
}
 379

mixin Foo!(int); // create x of type int

Mixins can add virtual functions to a class:
mixin template Foo()
{
void func() { writeln("Foo.func()"); }
}

class Bar
{
mixin Foo;
}

class Code : Bar

{
override void func() { writeln("Code.func()"); }
}

void test()
{
Bar b = new Bar();
b.func(); // calls Foo.func()

b = new Code();
b.func(); // calls Code.func()
}
Mixins are evaluated in the scope of where they appear, not the scope of the template declaration:
int y = 3;

mixin template Foo()

{
int abc() { return y; }
}

void test()
{
int y = 8;
mixin Foo; // local y is picked up, not global y
assert(abc() == 8);
380 CHAPTER 22. TEMPLATE MIXINS

}
Mixins can parameterize symbols using alias parameters:
mixin template Foo(alias b)
{
int abc() { return b; }
}

void test()
{
int y = 8;
mixin Foo!(y);
assert(abc() == 8);
}
This example uses a mixin to implement a generic Duff’s device for an arbitrary statement (in
this case, the arbitrary statement is in bold). A nested function is generated as well as a delegate
literal, these can be inlined by the compiler:
mixin template duffs_device(alias id1, alias id2, alias s)
{
void duff_loop()
{
if (id1 < id2)
{
typeof(id1) n = (id2 - id1 + 7) / 8;
switch ((id2 - id1) % 8)
{
case 0: do { s(); goto case;
case 7: s(); goto case;
case 6: s(); goto case;
case 5: s(); goto case;
case 4: s(); goto case;
case 3: s(); goto case;
case 2: s(); goto case;
case 1: s(); continue;
default: assert(0, "Impossible");
} while (--n > 0);
}
}
}
22.1. MIXIN SCOPE 381

void foo() { writeln("foo"); }

void test()
{
int i = 1;
int j = 11;

mixin duffs_device!(i, j, delegate { foo(); });

duff_loop(); // executes foo() 10 times
}

22.1 Mixin Scope

The declarations in a mixin are ‘imported’ into the surrounding scope. If the name of a declaration
in a mixin is the same as a declaration in the surrounding scope, the surrounding declaration
overrides the mixin one:
int x = 3;

mixin template Foo()

{
int x = 5;
int y = 5;
}

mixin Foo;
int y = 3;

void test()
{
writefln("x␣=␣%d", x); // prints 3
writefln("y␣=␣%d", y); // prints 3
}
If two different mixins are put in the same scope, and each define a declaration with the same
name, there is an ambiguity error when the declaration is referenced:
mixin template Foo()
{
382 CHAPTER 22. TEMPLATE MIXINS

int x = 5;
void func(int x) { }
}

mixin template Bar()

{
int x = 4;
void func(long x) { }
}

mixin Foo;
mixin Bar;

void test()
{
import std.stdio : writefln;
writefln("x␣=␣%d", x); // error, x is ambiguous
func(1); // error, func is ambiguous
}
The call to func() is ambiguous because Foo.func and Bar.func are in different scopes.
If a mixin has an Identifier, it can be used to disambiguate between conflicting symbols:
int x = 6;

mixin template Foo()

{
int x = 5;
int y = 7;
void func() { }
}

mixin template Bar()

{
int x = 4;
void func() { }
}

mixin Foo F;
mixin Bar B;
22.1. MIXIN SCOPE 383

void test()
{
writefln("y␣=␣%d", y); // prints 7
writefln("x␣=␣%d", x); // prints 6
writefln("F.x␣=␣%d", F.x); // prints 5
writefln("B.x␣=␣%d", B.x); // prints 4
F.func(); // calls Foo.func
B.func(); // calls Bar.func
}
Alias declarations can be used to overload together functions declared in different mixins:
mixin template Foo()
{
void func(int x) { }
}

mixin template Bar()

{
void func(long x) { }
}

mixin Foo!() F;
mixin Bar!() B;

alias func = F.func;

alias func = B.func;

void main()
{
func(1); // calls B.func
func(1L); // calls F.func
}
A mixin has its own scope, even if a declaration is overridden by the enclosing one:
int x = 4;

mixin template Foo()

{
int x = 5;
int bar() { return x; }
384 CHAPTER 22. TEMPLATE MIXINS

mixin Foo;

void test()
{
writefln("x␣=␣%d", x); // prints 4
writefln("bar()␣=␣%d", bar()); // prints 5
}
Chapter 23

Contract Programming

Contracts are a breakthrough technique to reduce the programming effort for large projects. Con-
tracts are the concept of preconditions, postconditions, errors, and invariants. Contracts can be
done in C++ without modification to the language, but the result is clumsy and inconsistent.
Building contract support into the language makes for:

1. a consistent look and feel for the contracts

2. tool support
3. it’s possible the compiler can generate better code using information gathered from the con-
tracts
4. easier management and enforcement of contracts
5. handling of contract inheritance

The idea of a contract is simple - it’s just an expression that must evaluate to true. If it does
not, the contract is broken, and by definition, the program has a bug in it. Contracts form part of
the specification for a program, moving it from the documentation to the code itself. And as every
programmer knows, documentation tends to be incomplete, out of date, wrong, or non-existent.
Moving the contracts into the code makes them verifiable against the program.

23.1 Assert Contract

The most basic contract is the AssertExpression. An assert declares an expression that must
evaluate to true:
assert(expression);
As a contract, an assert represents a guarantee that the code must uphold. Any failure of this
expression represents a logic error in the code that must be fixed in the source code. A program for
which the assert contract is false is, by definition, invalid, and therefore has undefined behaviour.

385
386 CHAPTER 23. CONTRACT PROGRAMMING

As a debugging aid, the compiler may insert a runtime check to verify that the expression is
indeed true. If it is false, an AssertError is thrown. When compiling for release, this
check is not generated. The special assert(0) expression, however, is generated even in release
mode. See the AssertExpression documentation for more information.
The compiler is free to assume the assert expression is true and optimize subsequent code
accordingly.

23.2 Pre and Post Contracts

The pre contracts specify the preconditions before a statement is executed. The most typical use
of this would be in validating the parameters to a function. The post contracts validate the result
of the statement. The most typical use of this would be in validating the return value of a function
and of any side effects it has. The syntax is:
in
{
...contract preconditions...
}
out (result)
{
...contract postconditions...
}
body
{
...code...
}
By definition, if a pre contract fails, then the body received bad parameters. An AssertError is
thrown. If a post contract fails, then there is a bug in the body. An AssertError is thrown.
Either the <code>in</code> or the <code>out</code> clause can be omitted. If the
<code>out</code> clause is for a function body, the variable <code>result</code> is declared
and assigned the return value of the function. For example, let’s implement a square root function:
long square_root(long x)
in
{
assert(x >= 0);
}
out (result)
{
assert((result * result) <= x && (result+1) * (result+1) > x);
23.3. IN, OUT AND INHERITANCE 387

}
body
{
return cast(long)std.math.sqrt(cast(real)x);
}
The assert’s in the in and out bodies are called <dfn>contracts</dfn>. Any other D statement or
expression is allowed in the bodies, but it is important to ensure that the code has no side effects,
and that the release version of the code will not depend on any effects of the code. For a release
build of the code, the in and out code is not inserted.
If the function returns a void, there is no result, and so there can be no result declaration in the
out clause. In that case, use:
void func()
out
{
...contracts...
}
body
{
...
}
In an out statement, result is initialized and set to the return value of the function.

23.3 In, Out and Inheritance

If a function in a derived class overrides a function in its super class, then only one of the in contracts
of the function and its base functions must be satisfied. Overriding functions then becomes a process
of loosening the in contracts.
A function without an in contract means that any values of the function parameters are allowed.
This implies that if any function in an inheritance hierarchy has no in contract, then in contracts
on functions overriding it have no useful effect.
Conversely, all of the out contracts needs to be satisfied, so overriding functions becomes a
processes of tightening the out contracts.

23.4 Invariants
Invariants are used to specify characteristics of a class or struct that always must be true (except
while executing a member function). For example, a class representing a date might have an
invariant that the day must be 1..31 and the hour must be 0..23:
388 CHAPTER 23. CONTRACT PROGRAMMING

class Date
{
int day;
int hour;

this(int d, int h)
{
day = d;
hour = h;
}

invariant
{
assert(1 <= day && day <= 31);
assert(0 <= hour && hour < 24);
}
}
The invariant is a contract saying that the asserts must hold true. The invariant is checked when
a class or struct constructor completes, at the start of the class or struct destructor. For public or
exported functions, the order of execution is:

1. preconditions
2. invariant
3. body
4. invariant
5. postconditions

The invariant is not checked if the class or struct is implicitly constructed using the default
.init value.
The code in the invariant may not call any public non-static members of the class or struct,
either directly or indirectly. Doing so will result in a stack overflow, as the invariant will wind up
being called in an infinitely recursive manner.
Invariants are implicitly const.
Since the invariant is called at the start of public or exported members, such members should
not be called from constructors.
class Foo
{
public void f() { }
private void g() { }
23.5. REFERENCES 389

invariant
{
f(); // error, cannot call public member function from invariant
g(); // ok, g() is not public
}
}
The invariant can be checked with an assert() expression:

1. classes need to pass a class object

2. structs need to pass the address of an instance

auto mydate = new Date(); //class

auto s = S(); //struct
...
assert(mydate); // check that class Date invariant holds
assert(&s); // check that struct S invariant holds
Invariants contain assert expressions, and so when they fail, they throw a AssertErrors. Class
invariants are inherited, that is, any class invariant is implicitly anded with the invariants of its
base classes.
There can be only one Invariant per class or struct.
When compiling for release, the invariant code is not generated, and the compiled program runs
at maximum speed. The compiler is free to assume the invariant holds true, regardless of whether
code is generated for it or not, and may optimize code accordingly.

23.5 References
• Contracts Reading List

• Adding Contracts to Java

Chapter 24

Conditional Compilation

Conditional compilation is the process of selecting which code to compile and which code to not
compile. (In C and C++, conditional compilation is done with the preprocessor directives #if /
#else / #endif.)

ConditionalDeclaration:
Condition DeclarationBlock
Condition DeclarationBlock else DeclarationBlock
Condition : DeclDefs opt
Condition DeclarationBlock else : DeclDefs opt

ConditionalStatement:
Condition NoScopeNonEmptyStatement
Condition NoScopeNonEmptyStatement else NoScopeNonEmptyStatement

If the Condition is satisfied, then the following DeclarationBlock or Statement is compiled in.
If it is not satisfied, the DeclarationBlock or Statement after the optional else is compiled in.
Any DeclarationBlock or Statement that is not compiled in still must be syntactically correct.
No new scope is introduced, even if the DeclarationBlock or Statement is enclosed by { }.
ConditionalDeclarations and ConditionalStatements can be nested.
The StaticAssert can be used to issue errors at compilation time for branches of the conditional
compilation that are errors.
Condition comes in the following forms:

Condition:
VersionCondition
DebugCondition

391
392 CHAPTER 24. CONDITIONAL COMPILATION

StaticIfCondition

Version Condition
VersionCondition:
version ( IntegerLiteral )
version ( Identifier )
version ( unittest )
version ( assert )

Versions enable multiple versions of a module to be implemented with a single source file.
The VersionCondition is satisfied if the IntegerLiteral is greater than or equal to the current
version level, or if Identifier matches a version identifier.
The version level and version identifier can be set on the command line by the -version switch
or in the module itself with a VersionSpecification, or they can be predefined by the compiler.
Version identifiers are in their own unique name space, they do not conflict with debug identifiers
or other symbols in the module. Version identifiers defined in one module have no influence over
other imported modules.
int k;
version (Demo) // compile in this code block for the demo version
{
int i;
int k; // error, k already defined

i = 3;
}
x = i; // uses the i declared above

version (X86)
{
... // implement custom inline assembler version
}
else
{
... // use default, but slow, version
}
The version(unittest) is satisfied if and only if the code is compiled with unit tests enabled
(the -unittest option on dmd).
 393

Version Specification
VersionSpecification:
version = Identifier ;
version = IntegerLiteral ;

The version specification makes it straightforward to group a set of features under one major
version, for example:
version (ProfessionalEdition)
{
version = FeatureA;
version = FeatureB;
version = FeatureC;
}
version (HomeEdition)
{
version = FeatureA;
}
...
version (FeatureB)
{
... implement Feature B ...
}
Version identifiers or levels may not be forward referenced:
version (Foo)
{
int x;
}
version = Foo; // error, Foo already used
VersionSpecifications may only appear at module scope.
While the debug and version conditions superficially behave the same, they are intended for
very different purposes. Debug statements are for adding debug code that is removed for the
release version. Version statements are to aid in portability and multiple release versions.
Here’s an example of a full version as opposed to a demo version:
class Foo
{
int a, b;
394 CHAPTER 24. CONDITIONAL COMPILATION

version(full)
{
int extrafunctionality()
{
...
return 1; // extra functionality is supported
}
}
else // demo
{
int extrafunctionality()
{
return 0; // extra functionality is not supported
}
}
}
Various different version builds can be built with a parameter to version:
version(n) // add in version code if version level is >= n
{
... version code ...
}

version(identifier) // add in version code if version

// keyword is identifier
{
... version code ...
}
These are presumably set by the command line as -version=n and -version=identifier.

Predefined Versions
Several environmental version identifiers and identifier name spaces are predefined for consistent
usage. Version identifiers do not conflict with other identifiers in the code, they are in a separate
name space. Predefined version identifiers are global, i.e. they apply to all modules being compiled
and imported.
 395

Table 24.1: Predefined Version Identifiers

Version Identifier Description
DigitalMars DMD (Digital Mars D) is the compiler
GNU GDC (GNU D Compiler) is the compiler
LDC LDC (LLVM D Compiler) is the compiler
SDC SDC (Stupid D Compiler) is the compiler
Windows Microsoft Windows systems
Win32 Microsoft 32-bit Windows systems
Win64 Microsoft 64-bit Windows systems
linux All Linux systems
OSX Mac OS X
FreeBSD FreeBSD
OpenBSD OpenBSD
NetBSD NetBSD
DragonFlyBSD DragonFlyBSD
BSD All other BSDs
Solaris Solaris
Posix All POSIX systems (includes Linux, FreeBSD, OS X, So-
laris, etc.)
AIX IBM Advanced Interactive eXecutive OS
Haiku The Haiku operating system
SkyOS The SkyOS operating system
SysV3 System V Release 3
SysV4 System V Release 4
Hurd GNU Hurd
Android The Android platform
Cygwin The Cygwin environment
MinGW The MinGW environment
FreeStanding An environment without an operating system (such as Bare-
metal targets)
CRuntime_Bionic Bionic C runtime
CRuntime_Digitalmars DigitalMars C runtime
CRuntime_Glibc Glibc C runtime
CRuntime_Microsoft Microsoft C runtime
X86 Intel and AMD 32-bit processors
X86_64 Intel and AMD 64-bit processors
ARM The ARM architecture (32-bit) (AArch32 et al)
ARM_Thumb ARM in any Thumb mode
↩
396 CHAPTER 24. CONDITIONAL COMPILATION

(continued)
Version Identifier Description
ARM_SoftFloat The ARM soft floating point ABI
ARM_SoftFP The ARM softfp floating point ABI
ARM_HardFloat The ARM hardfp floating point ABI
AArch64 The Advanced RISC Machine architecture (64-bit)
Epiphany The Epiphany architecture
PPC The PowerPC architecture, 32-bit
PPC_SoftFloat The PowerPC soft float ABI
PPC_HardFloat The PowerPC hard float ABI
PPC64 The PowerPC architecture, 64-bit
IA64 The Itanium architecture (64-bit)
MIPS32 The MIPS architecture, 32-bit
MIPS64 The MIPS architecture, 64-bit
MIPS_O32 The MIPS O32 ABI
MIPS_N32 The MIPS N32 ABI
MIPS_O64 The MIPS O64 ABI
MIPS_N64 The MIPS N64 ABI
MIPS_EABI The MIPS EABI
MIPS_SoftFloat The MIPS soft-float ABI
MIPS_HardFloat The MIPS hard-float ABI
NVPTX The Nvidia Parallel Thread Execution (PTX) architecture,
32-bit
NVPTX64 The Nvidia Parallel Thread Execution (PTX) architecture,
64-bit
SPARC The SPARC architecture, 32-bit
SPARC_V8Plus The SPARC v8+ ABI
SPARC_SoftFloat The SPARC soft float ABI
SPARC_HardFloat The SPARC hard float ABI
SPARC64 The SPARC architecture, 64-bit
S390 The System/390 architecture, 32-bit
SystemZ The System Z architecture, 64-bit
HPPA The HP PA-RISC architecture, 32-bit
HPPA64 The HP PA-RISC architecture, 64-bit
SH The SuperH architecture, 32-bit
SH64 The SuperH architecture, 64-bit
Alpha The Alpha architecture
Alpha_SoftFloat The Alpha soft float ABI
↩
 397

(continued)
Version Identifier Description
Alpha_HardFloat The Alpha hard float ABI
LittleEndian Byte order, least significant first
BigEndian Byte order, most significant first
ELFv1 The Executable and Linkable Format v1
ELFv2 The Executable and Linkable Format v2
D_Coverage Code coverage analysis instrumentation (command line
switch -cov) is being generated
D_Ddoc Ddoc documentation (command line switch -D) is being gen-
erated
D_InlineAsm_X86 Inline assembler for X86 is implemented
D_InlineAsm_X86_64 Inline assembler for X86-64 is implemented
D_LP64 Pointers are 64 bits (command line switch -m64). (Do not
confuse this with C’s LP64 model)
D_X32 Pointers are 32 bits, but words are still 64 bits (x32 ABI)
(This can be defined in parallel to X86_64)
D_HardFloat The target hardware has a floating point unit
D_SoftFloat The target hardware does not have a floating point unit
D_PIC Position Independent Code (command line switch -fPIC) is
being generated
D_SIMD Vector extensions (via __simd) are supported
D_Version2 This is a D version 2 compiler
D_NoBoundsChecks Array bounds checks are disabled (command line switch
-noboundscheck)
D_ObjectiveC The target supports interfacing with Objective-C
unittest Unit tests are enabled (command line switch -unittest)
assert Checks are being emitted for assert expressions
none Never defined; used to just disable a section of code
all Always defined; used as the opposite of none

The following identifiers are defined, but are deprecated:

Predefined Version Identifiers (deprecated)

Version Identifier Description
darwin The Darwin operating system; use OSX instead
Thumb ARM in Thumb mode; use ARM_Thumb instead
S390X The System/390X architecture 64-bit; use SystemZ instead
398 CHAPTER 24. CONDITIONAL COMPILATION

Others will be added as they make sense and new implementations appear.
It is inevitable that the D language will evolve over time. Therefore, the version identifier
namespace beginning with "D_" is reserved for identifiers indicating D language specification or
new feature conformance. Further, all identifiers derived from the ones listed above by appending
any character(s) are reserved. This means that e.g. ARM_foo and Windows_bar are reserved while
foo_ARM and bar_Windows are not.
Furthermore, predefined version identifiers from this list cannot be set from the command line or
from version statements. (This prevents things like both Windows and linux being simultaneously
set.)
Compiler vendor specific versions can be predefined if the trademarked vendor identifier prefixes
it, as in:
version(DigitalMars_funky_extension)
{
...
}
It is important to use the right version identifier for the right purpose. For example, use the
vendor identifier when using a vendor specific feature. Use the operating system identifier when
using an operating system specific feature, etc.

24.1 Debug Condition

DebugCondition:
debug
debug ( IntegerLiteral )
debug ( Identifier )

Two versions of programs are commonly built, a release build and a debug build. The debug
build includes extra error checking code, test harnesses, pretty-printing code, etc. The debug
statement conditionally compiles in its statement body. It is D’s way of what in C is done with
#ifdef DEBUG / #endif pairs.
The debug condition is satisfied when the -debug switch is passed to the compiler or when the
debug level is >= 1.
The debug ( IntegerLiteral ) condition is satisfied when the debug level is >= IntegerLiteral.
The debug ( Identifier ) condition is satisfied when the debug identifier matches Identifier.
class Foo
{
int a, b;
24.2. STATIC IF CONDITION 399

debug:
int flag;
}

Debug Specification
DebugSpecification:
debug = Identifier ;
debug = IntegerLiteral ;

Debug identifiers and levels are set either by the command line switch -debug or by a De-
bugSpecification.
Debug specifications only affect the module they appear in, they do not affect any imported
modules. Debug identifiers are in their own namespace, independent from version identifiers and
other symbols.
It is illegal to forward reference a debug specification:
debug(foo) writeln("Foo");
debug = foo; // error, foo used before set
DebugSpecifications may only appear at module scope.
Various different debug builds can be built with a parameter to debug:
debug(IntegerLiteral) { } // add in debug code if debug level is >= IntegerLiteral
debug(identifier) { } // add in debug code if debug keyword is identifier
These are presumably set by the command line as -debug=n and -debug=identifier.

24.2 Static If Condition

StaticIfCondition:
static if ( AssignExpression )

AssignExpression is implicitly converted to a boolean type, and is evaluated at compile time.

The condition is satisfied if it evaluates to true. It is not satisfied if it evaluates to false.
It is an error if AssignExpression cannot be implicitly converted to a boolean type or if it cannot
be evaluated at compile time.
StaticIfConditions can appear in module, class, template, struct, union, or function scope. In
function scope, the symbols referred to in the AssignExpression can be any that can normally be
referenced by an expression at that point.
400 CHAPTER 24. CONDITIONAL COMPILATION

const int i = 3;
int j = 4;

static if (i == 3) // ok, at module scope

int x;

class C
{
const int k = 5;

static if (i == 3) // ok
int x;
else
long x;

static if (j == 3) // error, j is not a constant

int y;

static if (k == 5) // ok, k is in current scope

int z;
}

template INT(int i)
{
static if (i == 32)
alias INT = int;
else static if (i == 16)
alias INT = short;
else
static assert(0); // not supported
}

INT!(32) a; // a is an int
INT!(16) b; // b is a short
INT!(17) c; // error, static assert trips

A StaticIfConditional condition differs from an IfStatement in the following ways:

1. It can be used to conditionally compile declarations, not just statements.

2. It does not introduce a new scope even if { } are used for conditionally compiled statements.
24.3. STATIC ASSERT 401

3. For unsatisfied conditions, the conditionally compiled code need only be syntactically correct.
It does not have to be semantically correct.
4. It must be evaluatable at compile time.

24.3 Static Assert

StaticAssert:
static assert ( AssignExpression );
static assert ( AssignExpression , AssignExpression );

AssignExpression is evaluated at compile time, and converted to a boolean value. If the value is
true, the static assert is ignored. If the value is false, an error diagnostic is issued and the compile
fails.
Unlike AssertExpressions, StaticAsserts are always checked and evaluted by the compiler unless
they appear in an unsatisfied conditional.
void foo()
{
if (0)
{
assert(0); // never trips
static assert(0); // always trips
}
version (BAR)
{
}
else
{
static assert(0); // trips when version BAR is not defined
}
}
StaticAssert is useful tool for drawing attention to conditional configurations not supported in
the code.
The optional second AssignExpression can be used to supply additional information, such as a
text string, that will be printed out along with the error diagnostic.
Chapter 25

Traits

Traits are extensions to the language to enable programs, at compile time, to get at information
internal to the compiler. This is also known as compile time reflection. It is done as a special, easily
extended syntax (similar to Pragmas) so that new capabilities can be added as required.

TraitsExpression:
__traits ( TraitsKeyword , TraitsArguments )

TraitsKeyword:
isAbstractClass
isArithmetic
isAssociativeArray
isFinalClass
isPOD
isNested
isFloating
isIntegral
isScalar
isStaticArray
isUnsigned
isVirtualFunction
isVirtualMethod
isAbstractFunction
isFinalFunction
isStaticFunction
isOverrideFunction
isTemplate
isRef

403
404 CHAPTER 25. TRAITS

isOut
isLazy
hasMember
identifier
getAliasThis
getAttributes
getFunctionAttributes
getMember
getOverloads
getPointerBitmap
getProtection
getVirtualFunctions
getVirtualMethods
getUnitTests
parent
classInstanceSize
getVirtualIndex
allMembers
derivedMembers
isSame
compiles

TraitsArguments:
TraitsArgument
TraitsArgument , TraitsArguments

TraitsArgument:
AssignExpression
Type

Additionally special keywords are provided for debugging purposes:

SpecialKeyword:
__FILE__
__MODULE__
__LINE__
__FUNCTION__
__PRETTY_FUNCTION__
25.1. ISARITHMETIC 405

25.1 isArithmetic
If the arguments are all either types that are arithmetic types, or expressions that are typed as
arithmetic types, then true is returned. Otherwise, false is returned. If there are no arguments,
false is returned.
import std.stdio;

void main()
{
int i;
writeln(__traits(isArithmetic, int));
writeln(__traits(isArithmetic, i, i+1, int));
writeln(__traits(isArithmetic));
writeln(__traits(isArithmetic, int*));
}
Prints:
true true false false

25.2 isFloating
Works like isArithmetic, except it’s for floating point types (including imaginary and complex
types).

25.3 isIntegral
Works like isArithmetic, except it’s for integral types (including character types).

25.4 isScalar
Works like isArithmetic, except it’s for scalar types.

25.5 isUnsigned
Works like isArithmetic, except it’s for unsigned types.

25.6 isStaticArray
Works like isArithmetic, except it’s for static array types.
406 CHAPTER 25. TRAITS

25.7 isAssociativeArray
Works like isArithmetic, except it’s for associative array types.

25.8 isAbstractClass
If the arguments are all either types that are abstract classes, or expressions that are typed as
abstract classes, then true is returned. Otherwise, false is returned. If there are no arguments,
false is returned.
import std.stdio;

abstract class C { int foo(); }

void main()
{
C c;
writeln(__traits(isAbstractClass, C));
writeln(__traits(isAbstractClass, c, C));
writeln(__traits(isAbstractClass));
writeln(__traits(isAbstractClass, int*));
}
Prints:
true true false false

25.9 isFinalClass
Works like isAbstractClass, except it’s for final classes.

25.10 isPOD
Takes one argument, which must be a type. It returns true if the type is a POD type, otherwise
false.

25.11 isNested
Takes one argument. It returns true if the argument is a nested type which internally stores a
context pointer, otherwise it returns false. Nested types can be classes, structs, and functions.
25.12. ISVIRTUALFUNCTION 407

25.12 isVirtualFunction
The same as isVirtualMethod, except that final functions that don’t override anything return true.

25.13 isVirtualMethod
Takes one argument. If that argument is a virtual function, true is returned, otherwise false.
Final functions that don’t override anything return false.
import std.stdio;

struct S
{
void bar() { }
}

class C
{
void bar() { }
}

void main()
{
writeln(__traits(isVirtualMethod, C.bar)); // true
writeln(__traits(isVirtualMethod, S.bar)); // false
}

25.14 isAbstractFunction
Takes one argument. If that argument is an abstract function, true is returned, otherwise false.
import std.stdio;

struct S
{
void bar() { }
}

class C
{
408 CHAPTER 25. TRAITS

void bar() { }
}

class AC
{
abstract void foo();
}

void main()
{
writeln(__traits(isAbstractFunction, C.bar)); // false
writeln(__traits(isAbstractFunction, S.bar)); // false
writeln(__traits(isAbstractFunction, AC.foo)); // true
}

25.15 isFinalFunction
Takes one argument. If that argument is a final function, true is returned, otherwise false.
import std.stdio;

struct S
{
void bar() { }
}

class C
{
void bar() { }
final void foo();
}

final class FC
{
void foo();
}

void main()
{
writeln(__traits(isFinalFunction, C.bar)); // false
25.16. ISOVERRIDEFUNCTION 409

writeln(__traits(isFinalFunction, S.bar)); // false

writeln(__traits(isFinalFunction, C.foo)); // true
writeln(__traits(isFinalFunction, FC.foo)); // true
}

25.16 isOverrideFunction
Takes one argument. If that argument is a function marked with override, true is returned, other-
wise false.
import std.stdio;

class Base
{
void foo() { }
}

class Foo : Base

{
override void foo() { }
void bar() { }
}

void main()
{
writeln(__traits(isOverrideFunction, Base.foo)); // false
writeln(__traits(isOverrideFunction, Foo.foo)); // true
writeln(__traits(isOverrideFunction, Foo.bar)); // false
}

25.17 isStaticFunction
Takes one argument. If that argument is a static function, meaning it has no context pointer, true
is returned, otherwise false.

25.18 isRef, isOut, isLazy

Takes one argument. If that argument is a declaration, true is returned if it is ref, out, or lazy,
otherwise false.
410 CHAPTER 25. TRAITS

void fooref(ref int x)

{
static assert(__traits(isRef, x));
static assert(!__traits(isOut, x));
static assert(!__traits(isLazy, x));
}

void fooout(out int x)

{
static assert(!__traits(isRef, x));
static assert(__traits(isOut, x));
static assert(!__traits(isLazy, x));
}

void foolazy(lazy int x)

{
static assert(!__traits(isRef, x));
static assert(!__traits(isOut, x));
static assert(__traits(isLazy, x));
}

25.19 isTemplate
Takes one argument. If that argument is a template then true is returned, otherwise false.
void foo(T)(){}
static assert(__traits(isTemplate,foo));
static assert(!__traits(isTemplate,foo!int()));
static assert(!__traits(isTemplate,"string"));

25.20 hasMember
The first argument is a type that has members, or is an expression of a type that has members.
The second argument is a string. If the string is a valid property of the type, true is returned,
otherwise false.
import std.stdio;

struct S
25.21. IDENTIFIER 411

{
int m;
}

void main()
{
S s;

writeln(__traits(hasMember, S, "m")); // true

writeln(__traits(hasMember, s, "m")); // true
writeln(__traits(hasMember, S, "y")); // false
writeln(__traits(hasMember, int, "sizeof")); // true
}

25.21 identifier
Takes one argument, a symbol. Returns the identifier for that symbol as a string literal.

25.22 getAliasThis
Takes one argument, a symbol of aggregate type. If the given aggregate type has alias this,
returns a list of alias this names, by a tuple of strings. Otherwise returns an empty tuple.

25.23 getAttributes
Takes one argument, a symbol. Returns a tuple of all attached user defined attributes. If no UDA’s
exist it will return an empty tuple.
For more information, see: User Defined Attributes
@(3) int a;
@("string", 7) int b;

enum Foo;
@Foo int c;

pragma(msg, __traits(getAttributes, a));

pragma(msg, __traits(getAttributes, b));
pragma(msg, __traits(getAttributes, c));
412 CHAPTER 25. TRAITS

Prints:
tuple(3) tuple("string", 7) tuple((Foo))

25.24 getFunctionAttributes
Takes one argument which must either be a function symbol, function literal, or a function pointer.
It returns a string tuple of all the attributes of that function excluding any user defined attributes
(UDAs can be retrieved with the getAttributes trait). If no attributes exist it will return an empty
tuple.
Note: The order of the attributes in the returned tuple is implementation-defined and should
not be relied upon.
A list of currently supported attributes are:

• pure, nothrow, @nogc, @property, @system, @trusted, @safe, and ref

Note: ref is a function attribute even though it applies to the return type.
Additionally the following attributes are only valid for non-static member functions:

• const, immutable, inout, shared

For example:
int sum(int x, int y) pure nothrow { return x + y; }

// prints ("pure", "nothrow", "@system")

pragma(msg, __traits(getFunctionAttributes, sum));

struct S
{
void test() const @system { }
}

// prints ("const", "@system")

pragma(msg, __traits(getFunctionAttributes, S.test));

Note that some attributes can be inferred. For example:

// prints ("pure", "nothrow", "@nogc", "@trusted")
pragma(msg, __traits(getFunctionAttributes, (int x) @trusted { return x * 2; }));
25.25. GETMEMBER 413

25.25 getMember
Takes two arguments, the second must be a string. The result is an expression formed from the
first argument, followed by a ‘.’, followed by the second argument as an identifier.
import std.stdio;

struct S
{
int mx;
static int my;
}

void main()
{
S s;

__traits(getMember, s, "mx") = 1; // same as s.mx=1;

writeln(__traits(getMember, s, "m" ~ "x")); // 1

__traits(getMember, S, "mx") = 1; // error, no this for S.mx

__traits(getMember, S, "my") = 2; // ok
}

25.26 getOverloads
The first argument is an aggregate (e.g. struct/class/module). The second argument is a string
that matches the name of one of the functions in that aggregate. The result is a tuple of all the
overloads of that function.
import std.stdio;

class D
{
this() { }
~this() { }
void foo() { }
int foo(int) { return 2; }
}
414 CHAPTER 25. TRAITS

void main()
{
D d = new D();

foreach (t; __traits(getOverloads, D, "foo"))

writeln(typeid(typeof(t)));

alias b = typeof(__traits(getOverloads, D, "foo"));

foreach (t; b)
writeln(typeid(t));

auto i = __traits(getOverloads, d, "foo")[1](1);

writeln(i);
}
Prints:
void() int() void() int() 2

25.27 getPointerBitmap
The argument is a type. The result is an array of size_t describing the memory used by an instance
of the given type.
The first element of the array is the size of the type (for classes it is the classInstanceSize).
The following elements describe the locations of GC managed pointers within the memory
occupied by an instance of the type. For type T, there are T.sizeof / size_t.sizeof possible
pointers represented by the bits of the array values.
This array can be used by a precise GC to avoid false pointers.
class C
{
// implicit virtual function table pointer not marked
// implicit monitor field not marked, usually managed manually
C next;
size_t sz;
void* p;
void function () fn; // not a GC managed pointer
}

struct S
{
size_t val1;
25.28. GETPROTECTION 415

void* p;
C c;
byte[] arr; // { length, ptr }
void delegate () dg; // { context, func }
}

static assert (__traits(getPointerBitmap, C) == [6*size_t.sizeof, 0b010100]);

static assert (__traits(getPointerBitmap, S) == [7*size_t.sizeof, 0b0110110]);

25.28 getProtection
The argument is a symbol. The result is a string giving its protection level: "public", "private",
"protected", "export", or "package".
import std.stdio;

class D
{
export void foo() { }
public int bar;
}

void main()
{
D d = new D();

auto i = __traits(getProtection, d.foo);

writeln(i);

auto j = __traits(getProtection, d.bar);

writeln(j);
}
Prints:
export public

25.29 getVirtualFunctions
The same as getVirtualMethods, except that final functions that do not override anything are in-
cluded.
416 CHAPTER 25. TRAITS

25.30 getVirtualMethods
The first argument is a class type or an expression of class type. The second argument is a string
that matches the name of one of the functions of that class. The result is a tuple of the virtual
overloads of that function. It does not include final functions that do not override anything.

import std.stdio;

class D
{
this() { }
~this() { }
void foo() { }
int foo(int) { return 2; }
}

void main()
{
D d = new D();

foreach (t; __traits(getVirtualMethods, D, "foo"))

writeln(typeid(typeof(t)));

alias b = typeof(__traits(getVirtualMethods, D, "foo"));

foreach (t; b)
writeln(typeid(t));

auto i = __traits(getVirtualMethods, d, "foo")[1](1);

writeln(i);
}

Prints:
void() int() void() int() 2

25.31 getUnitTests
Takes one argument, a symbol of an aggregate (e.g. struct/class/module). The result is a tuple of
all the unit test functions of that aggregate. The functions returned are like normal nested static
functions, CTEF will work and UDA’s will be accessible.
25.31. GETUNITTESTS 417

Note:
The -unittest flag needs to be passed to the compiler. If the flag is not passed
__traits(getUnitTests) will always return an empty tuple.
module foo;

import core.runtime;
import std.stdio;

struct name { string name; }

class Foo
{
unittest
{
writeln("foo.Foo.unittest");
}
}

@name("foo") unittest
{
writeln("foo.unittest");
}

template Tuple (T...)

{
alias Tuple = T;
}

shared static this()

{
// Override the default unit test runner to do nothing. After that, "main" will
// be called.
Runtime.moduleUnitTester = { return true; };
}

void main()
{
writeln("start␣main");
418 CHAPTER 25. TRAITS

alias tests = Tuple!(__traits(getUnitTests, foo));

static assert(tests.length == 1);

alias attributes = Tuple!(__traits(getAttributes, tests[0]));

static assert(attributes.length == 1);

foreach (test; tests)

test();

foreach (test; __traits(getUnitTests, Foo))

test();
}
By default, the above will print:
start main foo.unittest foo.Foo.unittest

25.32 parent
Takes a single argument which must evaluate to a symbol. The result is the symbol that is the
parent of it.

25.33 classInstanceSize
Takes a single argument, which must evaluate to either a class type or an expression of class type.
The result is of type size_t, and the value is the number of bytes in the runtime instance of the
class type. It is based on the static type of a class, not the polymorphic type.

25.34 getVirtualIndex
Takes a single argument which must evaluate to a function. The result is a ptrdiff_t containing
the index of that function within the vtable of the parent type. If the function passed in is final
and does not override a virtual function, -1 is returned instead.

25.35 allMembers
Takes a single argument, which must evaluate to either a type or an expression of type. A tuple of
string literals is returned, each of which is the name of a member of that type combined with all of
the members of the base classes (if the type is a class). No name is repeated. Builtin properties are
not included.
25.36. DERIVEDMEMBERS 419

import std.stdio;

class D
{
this() { }
~this() { }
void foo() { }
int foo(int) { return 0; }
}

void main()
{
auto b = [ __traits(allMembers, D) ];
writeln(b);
// ["__ctor", "__dtor", "foo", "toString", "toHash", "opCmp", "opEquals", ⤦
Ç "Monitor", "factory"]
}
The order in which the strings appear in the result is not defined.

25.36 derivedMembers
Takes a single argument, which must evaluate to either a type or an expression of type. A tuple of
string literals is returned, each of which is the name of a member of that type. No name is repeated.
Base class member names are not included. Builtin properties are not included.
import std.stdio;

class D
{
this() { }
~this() { }
void foo() { }
int foo(int) { return 0; }
}

void main()
{
auto a = [__traits(derivedMembers, D)];
writeln(a); // ["__ctor", "__dtor", "foo"]
}
420 CHAPTER 25. TRAITS

The order in which the strings appear in the result is not defined.

25.37 isSame
Takes two arguments and returns bool true if they are the same symbol, false if not.
import std.stdio;

struct S { }

int foo();
int bar();

void main()
{
writeln(__traits(isSame, foo, foo)); // true
writeln(__traits(isSame, foo, bar)); // false
writeln(__traits(isSame, foo, S)); // false
writeln(__traits(isSame, S, S)); // true
writeln(__traits(isSame, std, S)); // false
writeln(__traits(isSame, std, std)); // true
}
If the two arguments are expressions made up of literals or enums that evaluate to the same
value, true is returned.

25.38 compiles
Returns a bool true if all of the arguments compile (are semantically correct). The arguments
can be symbols, types, or expressions that are syntactically correct. The arguments cannot be
statements or declarations.
If there are no arguments, the result is false.
import std.stdio;

struct S
{
static int s1;
int s2;
}
25.39. SPECIAL KEYWORDS 421

int foo();
int bar();

void main()
{
writeln(__traits(compiles)); // false
writeln(__traits(compiles, foo)); // true
writeln(__traits(compiles, foo + 1)); // true
writeln(__traits(compiles, &foo + 1)); // false
writeln(__traits(compiles, typeof(1))); // true
writeln(__traits(compiles, S.s1)); // true
writeln(__traits(compiles, S.s3)); // false
writeln(__traits(compiles, 1,2,3,int,long,std)); // true
writeln(__traits(compiles, 3[1])); // false
writeln(__traits(compiles, 1,2,3,int,long,3[1])); // false
}
This is useful for:

• Giving better error messages inside generic code than the sometimes hard to follow compiler
ones.
• Doing a finer grained specialization than template partial specialization allows for.

25.39 Special Keywords

__FILE__ and __LINE__ expand to the source file name and line number at the point of instantiation.
__MODULE__ expands to the module name at the point of instantiation.
__FUNCTION__ expands to the fully qualified name of the function at the point of instantiation.
__PRETTY_FUNCTION__ is similar to __FUNCTION__, but also expands the function return type,
its parameter types, and its attributes.
Example usage:
module test;
import std.stdio;

void test(string file = __FILE__, size_t line = __LINE__, string mod = __MODULE__,
string func = __FUNCTION__, string pretty = __PRETTY_FUNCTION__)
{
writefln("file:␣’%s’,␣line:␣’%s’,␣module:␣’%s’,\nfunction:␣’%s’,␣pretty␣⤦
Ç function:␣’%s’",
file, line, mod, func, pretty);
422 CHAPTER 25. TRAITS

int main(string[] args)

{
test();
return 0;
}
This will output:
file: ’test.d’, line: ’13’, module: ’test’, function: ’test.main’, pretty
function: ’int test.main(string[] args)’
Chapter 26

Error Handling

I came, I coded, I crashed.

– Julius C’ster

All programs have to deal with errors. Errors are unexpected conditions that are not part of
the normal operation of a program. Examples of common errors are:

• Out of memory.
• Out of disk space.
• Invalid file name.
• Attempting to write to a read-only file.
• Attempting to read a non-existent file.
• Requesting a system service that is not supported.

26.1 The Error Handling Problem

The traditional C way of detecting and reporting errors is not traditional, it is ad-hoc and varies
from function to function, including:

• Returning a NULL pointer.

• Returning a 0 value.
• Returning a non-zero error code.
• Requiring errno to be checked.
• Requiring that a function be called to check if the previous function failed.

To deal with these possible errors, tedious error handling code must be added to each function
call. If an error happened, code must be written to recover from the error, and the error must be

423
424 CHAPTER 26. ERROR HANDLING

reported to the user in some user friendly fashion. If an error cannot be handled locally, it must
be explicitly propagated back to its caller. The long list of errno values needs to be converted into
appropriate text to be displayed. Adding all the code to do this can consume a large part of the
time spent coding a project - and still, if a new errno value is added to the runtime system, the old
code can not properly display a meaningful error message.
Good error handling code tends to clutter up what otherwise would be a neat and clean looking
implementation.
Even worse, good error handling code is itself error prone, tends to be the least tested (and
therefore buggy) part of the project, and is frequently simply omitted. The end result is likely a
"blue screen of death" as the program failed to deal with some unanticipated error.
Quick and dirty programs are not worth writing tedious error handling code for, and so such
utilities tend to be like using a table saw with no blade guards.
What’s needed is an error handling philosophy and methodology such that:

• It is standardized - consistent usage makes it more useful.

• The result is reasonable even if the programmer fails to check for errors.
• Old code can be reused with new code without having to modify the old code to be compatible
with new error types.
• No errors get inadvertently ignored.
• ‘Quick and dirty’ utilities can be written that still correctly handle errors.
• It is easy to make the error handling source code look good.

26.2 The D Error Handling Solution

Let’s first make some observations and assumptions about errors:

• Errors are not part of the normal flow of a program. Errors are exceptional, unusual, and
unexpected.
• Because errors are unusual, execution of error handling code is not performance critical.
• The normal flow of program logic is performance critical.
• All errors must be dealt with in some way, either by code explicitly written to handle them,
or by some system default handling.
• The code that detects an error knows more about the error than the code that must recover
from the error.

The solution is to use exception handling to report errors. All errors are objects derived from
abstract class Error. Error has a pure virtual function called toString() which produces a char[]
with a human readable description of the error.
26.2. THE D ERROR HANDLING SOLUTION 425

If code detects an error like "out of memory," then an Error is thrown with a message saying
"Out of memory". The function call stack is unwound, looking for a handler for the Error. Finally
blocks are executed as the stack is unwound. If an error handler is found, execution resumes there.
If not, the default Error handler is run, which displays the message and terminates the program.
How does this meet our criteria?

It is standardized - consistent usage makes it more useful. This is the D way, and is used
consistently in the D runtime library and examples.

The result is reasonable result even if the programmer fails to check for errors. If no
catch handlers are there for the errors, then the program gracefully exits through the default
error handler with an appropriate message.

Old code can be reused with new code without having to modify the old code to be
compatible with new error types. Old code can decide to catch all errors, or only specific
ones, propagating the rest upwards. In any case, there is no more need to correlate error
numbers with messages, the correct message is always supplied.

No errors get inadvertently ignored. Error exceptions get handled one way or another. There
is nothing like a NULL pointer return indicating an error, followed by trying to use that NULL
pointer.

’Quick and dirty’ utilities can be written that still correctly handle errors. Quick and
dirty code need not write any error handling code at all, and don’t need to check for errors.
The errors will be caught, an appropriate message displayed, and the program gracefully shut
down all by default.

It is easy to make the error handling source code look good. The try/catch/finally
statements look a lot nicer than endless if (error) goto errorhandler; statements.

How does this meet our assumptions about errors?

Errors are not part of the normal flow of a program. Errors are exceptional, unusual,
and unexpected. D exception handling fits right in with that.

Because errors are unusual, execution of error handling code is not performance
critical. Exception handling stack unwinding is a relatively slow process.

The normal flow of program logic is performance critical. Since the normal flow code
does not have to check every function call for error returns, it can be realistically faster to use
exception handling for the errors.
426 CHAPTER 26. ERROR HANDLING

All errors must be dealt with in some way, either by code explicitly written to handle
them, or by some system default handling. If there’s no handler for a particular error,
it is handled by the runtime library default handler. If an error is ignored, it is because
the programmer specifically added code to ignore an error, which presumably means it was
intentional.

The code that detects an error knows more about the error than the code that must
recover from the error. There is no more need to translate error codes into human readable
strings, the correct string is generated by the error detection code, not the error recovery code.
This also leads to consistent error messages for the same error between applications.

Using exceptions to handle errors leads to another issue - how to write exception safe programs.
Here’s how.
Chapter 27

Unit Tests

UnitTest:
unittest BlockStatement

Unit tests are a series of test cases applied to a module to determine if it is working properly.
Ideally, unit tests should be run every time a program is compiled.
Unit tests are a special function defined like:
unittest
{
...test code...
}
There can be any number of unit test functions in a module, including within struct, union and
class declarations. They are executed in lexical order. The order in which the modules are called to
run their unit tests is implementation defined. Stylistically, a unit test for a function should appear
immediately following it.
A compiler switch, such as -unittest for dmd, will cause the unittest test code to be compiled
and incorporated into the resulting executable. The unittest code gets run after static initialization
is run and before the main() function is called.
UnitTests must be grammatically correct even if -unittest is not used.
For example, given a class Sum that is used to add two values, a unit test can be given:
class Sum
{
int add(int x, int y) { return x + y; }

unittest
{

427
428 CHAPTER 27. UNIT TESTS

Sum sum = new Sum;

assert(sum.add(3,4) == 7);
assert(sum.add(-2,0) == -2);
}
}

Attributed Unittests
A unittest may be attributed with any of the global function attributes. Such unittests are useful
in verifying the given attribute(s) on a template function:
void myFunc(T)(T[] data)
{
if (data.length > 2)
data[0] = data[1];
}

@safe nothrow unittest

{
auto arr = [1,2,3];
myFunc(arr);
assert(arr == [2,2,3]);
}
This unittest verifies that myFunc contains only @safe, nothrow code. Although this can also be
accomplished by attaching these attributes to myFunc itself, that would prevent myFunc from being
instantiated with types T that have @system or throwing code in their opAssign method, or other
methods that myFunc may call. The above idiom allows myFunc to be instantiated with such types,
yet at the same time verify that the @system and throwing behaviour is not introduced by the code
within myFunc itself.

Documented Unittests
Documented unittests allow the developer to deliver code examples to the user, while at the same
time automatically verifying that the examples are valid. This avoids the frequent problem of having
outdated documentation for some piece of code.
If a declaration is followed by a documented unittest, the code in the unittest will be inserted
in the example section of the declaration:
/// Math class
class Math
{
 429

/// add function

static int add(int x, int y) { return x + y; }

///
unittest
{
assert(add(2, 2) == 4);
}
}

///
unittest
{
auto math = new Math();
auto result = math.add(2, 2);
}
The above will generate the following documentation:
<dl><dt><big><a name="Math"></a>class <u>Math</u>;
</big></dt> <dd><u>Math</u> class<br><br> <b>Example:</b><pre
class="d_code"><font color=blue>auto</font> math = <font color=blue>new</font>
<u>Math</u>; <font color=blue>auto</font> result = math.add(2, 2); </pre><br>
<dl><dt><big><a name="Math.add"></a>int <u>add</u>(int <i>x</i>, int
<i>y</i>); </big></dt> <dd><u>add</u> function<br><br> <b>Example:</b><pre
class="d_code"><font color=blue>assert</font>(<u>add</u>(2, 2) == 4); </pre> </dd>
</dl> </dd> </dl>
A unittest which is not documented, or is marked as private will not be used to generate code
samples.
There can be multiple documented unittests and they can appear in any order. They will be
attached to the last non-unittest declaration:
/// add function
int add(int x, int y) { return x + y; }

/// code sample generated

unittest
{
assert(add(1, 1) == 2);
}

/// code sample not generated because the unittest is private

430 CHAPTER 27. UNIT TESTS

private unittest
{
assert(add(2, 2) == 4);
}

unittest
{
/// code sample not generated because the unittest isn’t documented
assert(add(3, 3) == 6);
}

/// code sample generated, even if it only includes comments (or is empty)
unittest
{
/** assert(add(4, 4) == 8); */
}
The above will generate the following documentation:
<dl><dt><big><a name="add"></a>int <u>add</u>(int <i>x</i>, int <i>y</i>);
</big></dt> <dd><u>add</u> function<br><br> <b>Examples:</b><br> code sam-
ple generated <pre class="d_code"> <font color=blue>assert</font>(<u>add</u>(1, 1) ==
2); </pre> <br><br><b>Examples:</b><br> code sample generated, even if it is empty or
only includes comments
<pre class="d_code"> <font color=green>/** assert(add(4, 4) == 8); */</font> </pre>
<br><br> </dd> </dl>

Versioning
The version identifier unittest is predefined if the compilation is done with unit tests enabled.
Chapter 28

Garbage Collection

D is a systems programming language with support for garbage collection. Usually it is not necessary
to free memory explicitly. Just allocate as needed, and the garbage collector will periodically return
all unused memory to the pool of available memory.
D also provides the mechanisms to write code where the garbage collector is not involved.
More information is provided below.
C and C++ programmers accustomed to explicitly managing memory allocation and dealloca-
tion will likely be skeptical of the benefits and efficacy of garbage collection. Experience both with
new projects written with garbage collection in mind, and converting existing projects to garbage
collection shows that:

• Garbage collected programs are often faster. This is counterintuitive, but the reasons are:
– Reference counting is a common solution to solve explicit memory allocation problems.
The code to implement the increment and decrement operations whenever assignments
are made is one source of slowdown. Hiding it behind smart pointer classes doesn’t help
the speed. (Reference counting methods are not a general solution anyway, as circular
references never get deleted.)
– Destructors are used to deallocate resources acquired by an object. For most classes, this
resource is allocated memory. With garbage collection, most destructors then become
empty and can be discarded entirely.
– All those destructors freeing memory can become significant when objects are allocated
on the stack. For each one, some mechanism must be established so that if an exception
happens, the destructors all get called in each frame to release any memory they hold.
If the destructors become irrelevant, then there’s no need to set up special stack frames
to handle exceptions, and the code runs faster.
– Garbage collection kicks in only when memory gets tight. When memory is not tight,
the program runs at full speed and does not spend any time tracing and freeing memory.

431
432 CHAPTER 28. GARBAGE COLLECTION

– Garbage collected programs do not suffer from gradual deterioration due to an accumu-
lation of memory leaks.

• Garbage collectors reclaim unused memory, therefore they do not suffer from "memory leaks"
which can cause long running applications to gradually consume more and more memory until
they bring down the system. GC programs have longer term stability.
• Garbage collected programs have fewer hard-to-find pointer bugs. This is because there are
no dangling references to freed memory. There is no code to explicitly manage memory, hence
no bugs in such code.
• Garbage collected programs are faster to develop and debug, because there’s no need for
developing, debugging, testing, or maintaining the explicit deallocation code.

Garbage collection is not a panacea. There are some downsides:

• It is not always obvious when the GC allocates memory, which in turn can trigger a collection,
so the program can pause unexpectedly.
• The time it takes for a collection to complete is not bounded. While in practice it is very
quick, this cannot normally be guaranteed.
• Normally, all threads other than the collector thread must be halted while the collection is in
progress.
• Garbage collectors can keep around some memory that an explicit deallocator would not.
• Garbage collection should be implemented as a basic operating system kernel service. But
since it is not, garbage collecting programs must carry around with them the garbage collection
implementation. While this can be a shared library, it is still there.

These constraints are addressed by techniques outlined in Memory Management, including the
mechanisms provided by D to control allocations outside the GC heap.
There is currently work in progress to make the runtime library free of GC heap allocations, to
allow its use in scenarios where the use of GC infrastructure is not possible.

28.1 How Garbage Collection Works

The GC works by:

1. Stopping all other threads than the thread currently trying to allocate GC memory.
2. ‘Hijacking’ the current thread for GC work.
3. Scanning all ‘root’ memory ranges for pointers into GC allocated memory.
4. Recursively scanning all allocated memory pointed to by roots looking for more pointers into
GC allocated memory.
28.2. INTERFACING GARBAGE COLLECTED OBJECTS WITH FOREIGN CODE 433

5. Freeing all GC allocated memory that has no active pointers to it and do not need destructors
to run.
6. Queueing all unreachable memory that needs destructors to run.
7. Resuming all other threads.
8. Running destructors for all queued memory.
9. Freeing any remaining unreachable memory.
10. Returning the current thread to whatever work it was doing.

28.2 Interfacing Garbage Collected Objects With Foreign Code

The garbage collector looks for roots in:

1. the static data segment

2. the stacks and register contents of each thread
3. the TLS (thread-local storage) areas of each thread
4. any roots added by core.memory.GC.addRoot() or core.memory.GC.addRange()

If the only pointer to an object is held outside of these areas, then the collector will miss it and
free the memory.
To avoid this from happening, either

• maintain a pointer to the object in an area the collector does scan for pointers;
• add a root where a pointer to the object is stored using core.memory.GC.addRoot() or
core.memory.GC.addRange().
• reallocate and copy the object using the foreign code’s storage allocator or using the C runtime
library’s malloc/free.

28.3 Pointers and the Garbage Collector

Pointers in D can be broadly divided into two categories: Those that point to garbage collected
memory, and those that do not. Examples of the latter are pointers created by calls to C’s malloc(),
pointers received from C library routines, pointers to static data, pointers to objects on the stack,
etc. For those pointers, anything that is legal in C can be done with them.
For garbage collected pointers and references, however, there are some restrictions. These re-
strictions are minor, but they are intended to enable the maximum flexibility in garbage collector
design.
Undefined behavior:

• Do not xor pointers with other values, like the xor pointer linked list trick used in C.
434 CHAPTER 28. GARBAGE COLLECTION

• Do not use the xor trick to swap two pointer values.

• Do not store pointers into non-pointer variables using casts and other tricks.
void* p;
...
int x = cast(int)p; // error: undefined behavior
The garbage collector does not scan non-pointer fields for GC pointers.
• Do not take advantage of alignment of pointers to store bit flags in the low order bits:
p = cast(void*)(cast(int)p | 1); // error: undefined behavior
• Do not store into pointers values that may point into the garbage collected heap:
p = cast(void*)12345678; // error: undefined behavior
A copying garbage collector may change this value.
• Do not store magic values into pointers, other than null.
• Do not write pointer values out to disk and read them back in again.
• Do not use pointer values to compute a hash function. A copying garbage collector can
arbitrarily move objects around in memory, thus invalidating the computed hash value.
• Do not depend on the ordering of pointers:
if (p1 < p2) // error: undefined behavior
...
since, again, the garbage collector can move objects around in memory.
• Do not add or subtract an offset to a pointer such that the result points outside of the bounds
of the garbage collected object originally allocated.
char* p = new char[10];
char* q = p + 6; // ok
q = p + 11; // error: undefined behavior
q = p - 1; // error: undefined behavior
• Do not misalign pointers if those pointers may point into the GC heap, such as:
struct Foo
{
align (1):
byte b;
char* p; // misaligned pointer
}
Misaligned pointers may be used if the underlying hardware supports them and the pointer
is never used to point into the GC heap.
28.4. WORKING WITH THE GARBAGE COLLECTOR 435

• Do not use byte-by-byte memory copies to copy pointer values. This may result in intermediate
conditions where there is not a valid pointer, and if the gc pauses the thread in such a
condition, it can corrupt memory. Most implementations of memcpy() will work since the
internal implementation of it does the copy in aligned chunks greater than or equal to the
pointer size, but since this kind of implementation is not guaranteed by the C standard, use
memcpy() only with extreme caution.
• Do not have pointers in a struct instance that point back to the same instance. The trouble
with this is if the instance gets moved in memory, the pointer will point back to where it came
from, with likely disastrous results.

Things that are reliable and can be done:

• Use a union to share storage with a pointer:

union U { void* ptr; int value }
• A pointer to the start of a garbage collected object need not be maintained if a pointer to the
interior of the object exists.
char[] p = new char[10];
char[] q = p[3..6];
// q is enough to hold on to the object, don’t need to keep
// p as well.

One can avoid using pointers anyway for most tasks. D provides features rendering most explicit
pointer uses obsolete, such as reference objects, dynamic arrays, and garbage collection. Pointers
are provided in order to interface successfully with C APIs and for some low level work.

28.4 Working with the Garbage Collector

Garbage collection doesn’t solve every memory deallocation problem. For example, if a pointer to
a large data structure is kept, the garbage collector cannot reclaim it, even if it is never referred to
again. To eliminate this problem, it is good practice to set a reference or pointer to an object to
null when no longer needed.
This advice applies only to static references or references embedded inside other objects. There
is not much point for such stored on the stack to be nulled because new stack frames are initialized
anyway.

28.5 Object Pinning and a Moving Garbage Collector

Although D does not currently use a moving garbage collector, by following the rules listed above
one can be implemented. No special action is required to pin objects. A moving collector will
436 CHAPTER 28. GARBAGE COLLECTION

only move objects for which there are no ambiguous references, and for which it can update those
references. All other objects will be automatically pinned.

28.6 D Operations That Involve the Garbage Collector

Some sections of code may need to avoid using the garbage collector. The following constructs may
allocate memory using the garbage collector:

• NewExpression
• Array appending
• Array concatenation
• Array literals (except when used to initialize static data)
• Associative array literals
• Any insertion, removal, or lookups in an associative array
• Extracting keys or values from an associative array
• Taking the address of (i.e. making a delegate to) a nested function that accesses variables in
an outer scope
• A function literal that accesses variables in an outer scope
• An AssertExpression that fails its condition

28.7 Configuring the Garbage Collector

Since version 2.067, The garbage collector can now be configured through the command line, the
environment or by options embedded into the executable.
By default, GC options can only be passed on the command line of the program to run, e.g.
app "--DRT-gcopt=profile:1␣minPoolSize:16" arguments to app
Available GC options are:

• disable:0|1 - start disabled

• profile:0|1 - enable profiling with summary when terminating program
• initReserve:N - initial memory to reserve in MB
• minPoolSize:N - initial and minimum pool size in MB
• maxPoolSize:N - maximum pool size in MB
• incPoolSize:N - pool size increment MB
• heapSizeFactor:N - targeted heap size to used memory ratio

In addition, –DRT-gcopt=help will show the list of options and their current settings.
28.8. REFERENCES 437

Command line options starting with "–DRT-" are filtered out before calling main, so the program
will not see them. They are still available via rt_args.
Configuration via the command line can be disabled by declaring a variable for the linker to
pick up before using it’s default from the runtime:
extern(C) __gshared bool rt_cmdline_enabled = false;
Likewise, declare a boolean rt_envvars_enabled to enable configuration via the environment
variable DRT_GCOPT:
extern(C) __gshared bool rt_envvars_enabled = true;
Setting default configuration properties in the executable can be done by specifying an array of
options named rt_options:
extern(C) __gshared string[] rt_options = [ "gcopt=initReserve:100␣profile:1" ];
Evaluation order of options is rt_options, then environment variables, then command line
arguments, i.e. if command line arguments are not disabled, they can override options specified
through the environment or embedded in the executable.

28.8 References
• Wikipedia
• GC FAQ
• Uniprocessor Garbage Collector Techniques
• Garbage Collection: Algorithms for Automatic Dynamic Memory Management
Chapter 29

Floating Point

Floating Point Intermediate Values

On many computers, greater precision operations do not take any longer than lesser precision oper-
ations, so it makes numerical sense to use the greatest precision available for internal temporaries.
The philosophy is not to dumb down the language to the lowest common hardware denominator,
but to enable the exploitation of the best capabilities of target hardware.
For floating point operations and expression intermediate values, a greater precision can be used
than the type of the expression. Only the minimum precision is set by the types of the operands, not
the maximum. Implementation Note: On Intel x86 machines, for example, it is expected (but
not required) that the intermediate calculations be done to the full 80 bits of precision implemented
by the hardware.
It’s possible that, due to greater use of temporaries and common subexpressions, optimized code
may produce a more accurate answer than unoptimized code.
Algorithms should be written to work based on the minimum precision of the calculation. They
should not degrade or fail if the actual precision is greater. Float or double types, as opposed to
the real (extended) type, should only be used for:

• reducing memory consumption for large arrays

• when speed is more important than accuracy
• data and function argument compatibility with C

Floating Point Constant Folding

Regardless of the type of the operands, floating point constant folding is done in real or greater
precision. It is always done following IEEE 754 rules and round-to-nearest is used.
Floating point constants are internally represented in the implementation in at least real pre-
cision, regardless of the constant’s type. The extra precision is available for constant folding.

439
440 CHAPTER 29. FLOATING POINT

Committing to the precision of the result is done as late as possible in the compilation process. For
example:

const float f = 0.2f;

writeln(f - 0.2);

will print 0. A non-const static variable’s value cannot be propagated at compile time, so:

static float f = 0.2f;

writeln(f - 0.2);

will print 2.98023e-09. Hex floating point constants can also be used when specific floating point
bit patterns are needed that are unaffected by rounding. To find the hex value of 0.2f:

import std.stdio;

void main()
{
writefln("%a", 0.2f);
}

which is 0x1.99999ap-3. Using the hex constant:

const float f = 0x1.99999ap-3f;

writeln(f - 0.2);

prints 2.98023e-09.
Different compiler settings, optimization settings, and inlining settings can affect opportunities
for constant folding, therefore the results of floating point calculations may differ depending on
those settings.

Rounding Control
IEEE 754 floating point arithmetic includes the ability to set 4 different rounding modes. These
are accessible via the functions in core.stdc.fenv.
If the floating-point rounding mode is changed within a function, it must be restored before the
function exits. If this rule is violated (for example, by the use of inline asm), the rounding mode
used for subsequent calculations is undefined.

Exception Flags
IEEE 754 floating point arithmetic can set several flags based on what happened with a computation:
 441

FE_INVALID
FE_DENORMAL
FE_DIVBYZERO
FE_OVERFLOW
FE_UNDERFLOW
FE_INEXACT
These flags can be set/reset via the functions in core.stdc.fenv.

Floating Point Transformations

An implementation may perform transformations on floating point computations in order to reduce
their strength, i.e. their runtime computation time. Because floating point math does not precisely
follow mathematical rules, some transformations are not valid, even though some other programming
languages still allow them.
The following transformations of floating point expressions are not allowed because under IEEE
rules they could produce different results.

Disallowed Floating Point Transformations

transformation comments
x +0→x not valid if x is -0
x -0→x not valid if x is ±0 and rounding is towards -∝
-x ↔ 0 - x not valid if x is +0
x -x →0 not valid if x is NaN or ±∝
x - y ↔ -(y - x ) not valid because (1-1=+0) whereas -(1-1)=-0
x *0→0 not valid if x is NaN or ±∝
x / c ↔ x * (1/c) valid if (1/c) yields an ex act result
x != x → false not valid if x is a NaN
x == x → true not valid if x is a NaN
x !op y ↔ !(x op y) not valid if x or y is a NaN

Of course, transformations that would alter side effects are also invalid.
Chapter 30

D x86 Inline Assembler

D, being a systems programming language, provides an inline assembler. The inline assembler is
standardized for D implementations across the same CPU family, for example, the Intel Pentium
inline assembler for a Win32 D compiler will be syntax compatible with the inline assembler for
Linux running on an Intel Pentium.
Implementations of D on different architectures, however, are free to innovate upon the memory
model, function call/return conventions, argument passing conventions, etc.
This document describes the x86 and x86_64 implementations of the inline assembler. The
inline assembler platform support that a compiler provides is indicated by the D_InlineAsm_X86
and D_InlineAsm_X86_64 version identifiers, respectively.

AsmInstruction:
Identifier : AsmInstruction
align IntegerExpression
even
naked
db Operands
ds Operands
di Operands
dl Operands
df Operands
dd Operands
de Operands
Opcode
Opcode Operands

Operands:
Operand

443
444 CHAPTER 30. D X86 INLINE ASSEMBLER

Operand , Operands

30.1 Labels
Assembler instructions can be labeled just like other statements. They can be the target of goto
statements. For example:
void *pc;
asm
{
call L1 ;
L1: ;
pop EBX ;
mov pc[EBP],EBX ; // pc now points to code at L1
}

30.2 align IntegerExpression

IntegerExpression:
IntegerLiteral
Identifier

Causes the assembler to emit NOP instructions to align the next assembler instruction on an
IntegerExpression boundary. IntegerExpression must evaluate at compile time to an integer that is
a power of 2.
Aligning the start of a loop body can sometimes have a dramatic effect on the execution speed.

30.3 even
Causes the assembler to emit NOP instructions to align the next assembler instruction on an even
boundary.

30.4 naked
Causes the compiler to not generate the function prolog and epilog sequences. This means such is
the responsibility of inline assembly programmer, and is normally used when the entire function is
to be written in assembler.
30.5. DB, DS, DI, DL, DF, DD, DE 445

30.5 db, ds, di, dl, df, dd, de

These pseudo ops are for inserting raw data directly into the code. db is for bytes, ds is for 16 bit
words, di is for 32 bit words, dl is for 64 bit words, df is for 32 bit floats, dd is for 64 bit doubles,
and de is for 80 bit extended reals. Each can have multiple operands. If an operand is a string
literal, it is as if there were length operands, where length is the number of characters in the string.
One character is used per operand. For example:
asm
{
db 5,6,0x83; // insert bytes 0x05, 0x06, and 0x83 into code
ds 0x1234; // insert bytes 0x34, 0x12
di 0x1234; // insert bytes 0x34, 0x12, 0x00, 0x00
dl 0x1234; // insert bytes 0x34, 0x12, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
df 1.234; // insert float 1.234
dd 1.234; // insert double 1.234
de 1.234; // insert real 1.234
db "abc"; // insert bytes 0x61, 0x62, and 0x63
ds "abc"; // insert bytes 0x61, 0x00, 0x62, 0x00, 0x63, 0x00
}

30.6 Opcodes
A list of supported opcodes is at the end.
The following registers are supported. Register names are always in upper case.

Register:
AL AH AX EAX
BL BH BX EBX
CL CH CX ECX
DL DH DX EDX
BP EBP
SP ESP
DI EDI
SI ESI
ES CS SS DS GS FS
CR0 CR2 CR3 CR4
DR0 DR1 DR2 DR3 DR6 DR7
TR3 TR4 TR5 TR6 TR7
ST
446 CHAPTER 30. D X86 INLINE ASSEMBLER

ST(0) ST(1) ST(2) ST(3) ST(4) ST(5) ST(6) ST(7)

MM0 MM1 MM2 MM3 MM4 MM5 MM6 MM7
XMM0 XMM1 XMM2 XMM3 XMM4 XMM5 XMM6 XMM7

x86_64 adds these additional registers.

Register64:
RAX RBX RCX RDX
BPL RBP
SPL RSP
DIL RDI
SIL RSI
R8B R8W R8D R8
R9B R9W R9D R9
R10B R10W R10D R10
R11B R11W R11D R11
R12B R12W R12D R12
R13B R13W R13D R13
R14B R14W R14D R14
R15B R15W R15D R15
XMM8 XMM9 XMM10 XMM11 XMM12 XMM13 XMM14 XMM15
YMM0 YMM1 YMM2 YMM3 YMM4 YMM5 YMM6 YMM7
YMM8 YMM9 YMM10 YMM11 YMM12 YMM13 YMM14 YMM15

Special Cases
lock, rep, repe, repne, repnz, repz These prefix instructions do not appear in the same statement
as the instructions they prefix; they appear in their own statement. For example:
asm
{
rep ;
movsb ;
}

pause This opcode is not supported by the assembler, instead use

asm
{
30.7. OPERANDS 447

rep ;
nop ;
}

which produces the same result.

floating point ops Use the two operand form of the instruction format;
fdiv ST(1); // wrong
fmul ST; // wrong
fdiv ST,ST(1); // right
fmul ST,ST(0); // right

30.7 Operands
Operand:
AsmExp

AsmExp:
AsmLogOrExp
AsmLogOrExp ? AsmExp : AsmExp

AsmLogOrExp:
AsmLogAndExp
AsmLogOrExp || AsmLogAndExp

AsmLogAndExp:
AsmOrExp
AsmLogAndExp && AsmOrExp

AsmOrExp:
AsmXorExp
AsmOrExp | AsmXorExp

AsmXorExp:
AsmAndExp
AsmXorExp ^ AsmAndExp

AsmAndExp:
AsmEqualExp
448 CHAPTER 30. D X86 INLINE ASSEMBLER

AsmAndExp & AsmEqualExp

AsmEqualExp:
AsmRelExp
AsmEqualExp == AsmRelExp
AsmEqualExp != AsmRelExp

AsmRelExp:
AsmShiftExp
AsmRelExp < AsmShiftExp
AsmRelExp <= AsmShiftExp
AsmRelExp > AsmShiftExp
AsmRelExp >= AsmShiftExp

AsmShiftExp:
AsmAddExp
AsmShiftExp << AsmAddExp
AsmShiftExp >> AsmAddExp
AsmShiftExp >>> AsmAddExp

AsmAddExp:
AsmMulExp
AsmAddExp + AsmMulExp
AsmAddExp - AsmMulExp

AsmMulExp:
AsmBrExp
AsmMulExp * AsmBrExp
AsmMulExp / AsmBrExp
AsmMulExp % AsmBrExp

AsmBrExp:
AsmUnaExp
AsmBrExp [ AsmExp ]

AsmUnaExp:
AsmTypePrefix AsmExp
offsetof AsmExp
seg AsmExp
+ AsmUnaExp
30.7. OPERANDS 449

- AsmUnaExp
! AsmUnaExp
~ AsmUnaExp
AsmPrimaryExp

AsmPrimaryExp:
IntegerLiteral
FloatLiteral
__LOCAL_SIZE
$
Register
Register : AsmExp
Register64
Register64 : AsmExp
DotIdentifier
this

DotIdentifier:
Identifier
Identifier . DotIdentifier

The operand syntax more or less follows the Intel CPU documentation conventions. In partic-
ular, the convention is that for two operand instructions the source is the right operand and the
destination is the left operand. The syntax differs from that of Intel’s in order to be compatible
with the D language tokenizer and to simplify parsing.
The seg means load the segment number that the symbol is in. This is not relevant for flat
model code. Instead, do a move from the relevant segment register.

Operand Types
AsmTypePrefix:
near ptr
far ptr
byte ptr
short ptr
int ptr
word ptr
dword ptr
qword ptr
450 CHAPTER 30. D X86 INLINE ASSEMBLER

float ptr
double ptr
real ptr

In cases where the operand size is ambiguous, as in:

add [EAX],3 ;
it can be disambiguated by using an AsmTypePrefix :
add byte ptr [EAX],3 ;
add int ptr [EAX],7 ;
far ptr is not relevant for flat model code.

Struct/Union/Class Member Offsets

To access members of an aggregate, given a pointer to the aggregate is in a register, use the
.offsetof property of the qualified name of the member:
struct Foo { int a,b,c; }
int bar(Foo *f)
{
asm
{
mov EBX,f ;
mov EAX,Foo.b.offsetof[EBX] ;
}
}
void main()
{
Foo f = Foo(0, 2, 0);
assert(bar(&f) == 2);
}
Alternatively, inside the scope of an aggregate, only the member name is needed:
struct Foo // or class
{
int a,b,c;
int bar()
{
asm
30.8. OPCODES SUPPORTED 451

{
mov EBX, this ;
mov EAX, b[EBX] ;
}
}
}
void main()
{
Foo f = Foo(0, 2, 0);
assert(f.bar() == 2);
}

Stack Variables
Stack variables (variables local to a function and allocated on the stack) are accessed via the name
of the variable indexed by EBP:
int foo(int x)
{
asm
{
mov EAX,x[EBP] ; // loads value of parameter x into EAX
mov EAX,x ; // does the same thing
}
}
If the [EBP] is omitted, it is assumed for local variables. If naked is used, this no longer holds.

Special Symbols
$ Represents the program counter of the start of the next instruction. So,
jmp $ ;

branches to the instruction following the jmp instruction. The $ can only appear as the target
of a jmp or call instruction.
__LOCAL_SIZE This gets replaced by the number of local bytes in the local stack frame. It is most
handy when the naked is invoked and a custom stack frame is programmed.

30.8 Opcodes Supported

452 CHAPTER 30. D X86 INLINE ASSEMBLER

Table 30.1: Opcodes

aaa aad aam aas adc

add addpd addps addsd addss
and andnpd andnps andpd andps
arpl bound bsf bsr bswap
bt btc btr bts call
cbw cdq clc cld clflush
cli clts cmc cmova cmovae
cmovb cmovbe cmovc cmove cmovg
cmovge cmovl cmovle cmovna cmovnae
cmovnb cmovnbe cmovnc cmovne cmovng
cmovnge cmovnl cmovnle cmovno cmovnp
cmovns cmovnz cmovo cmovp cmovpe
cmovpo cmovs cmovz cmp cmppd
cmpps cmps cmpsb cmpsd cmpss
cmpsw cmpxch8b cmpxchg comisd comiss
cpuid cvtdq2pd cvtdq2ps cvtpd2dq cvtpd2pi
cvtpd2ps cvtpi2pd cvtpi2ps cvtps2dq cvtps2pd
cvtps2pi cvtsd2si cvtsd2ss cvtsi2sd cvtsi2ss
cvtss2sd cvtss2si cvttpd2dq cvttpd2pi cvttps2dq
cvttps2pi cvttsd2si cvttss2si cwd cwde
da daa das db dd
de dec df di div
divpd divps divsd divss dl
dq ds dt dw emms
enter f2xm1 fabs fadd faddp
fbld fbstp fchs fclex fcmovb
fcmovbe fcmove fcmovnb fcmovnbe fcmovne
fcmovnu fcmovu fcom fcomi fcomip
fcomp fcompp fcos fdecstp fdisi
fdiv fdivp fdivr fdivrp feni
ffree fiadd ficom ficomp fidiv
fidivr fild fimul fincstp finit
fist fistp fisub fisubr fld
fld1 fldcw fldenv fldl2e fldl2t
fldlg2 fldln2 fldpi fldz fmul
fmulp fnclex fndisi fneni fninit
fnop fnsave fnstcw fnstenv fnstsw
↩
30.8. OPCODES SUPPORTED 453

(continued)
fpatan fprem fprem1 fptan frndint
frstor fsave fscale fsetpm fsin
fsincos fsqrt fst fstcw fstenv
fstp fstsw fsub fsubp fsubr
fsubrp ftst fucom fucomi fucomip
fucomp fucompp fwait fxam fxch
fxrstor fxsave fxtract fyl2x fyl2xp1
hlt idiv imul in inc
ins insb insd insw int
into invd invlpg iret iretd
ja jae jb jbe jc
jcxz je jecxz jg jge
jl jle jmp jna jnae
jnb jnbe jnc jne jng
jnge jnl jnle jno jnp
jns jnz jo jp jpe
jpo js jz lahf lar
ldmxcsr lds lea leave les
lfence lfs lgdt lgs lidt
lldt lmsw lock lods lodsb
lodsd lodsw loop loope loopne
loopnz loopz lsl lss ltr
maskmovdqu maskmovq maxpd maxps maxsd
maxss mfence minpd minps minsd
minss mov movapd movaps movd
movdq2q movdqa movdqu movhlps movhpd
movhps movlhps movlpd movlps movmskpd
movmskps movntdq movnti movntpd movntps
movntq movq movq2dq movs movsb
movsd movss movsw movsx movupd
movups movzx mul mulpd mulps
mulsd mulss neg nop not
or orpd orps out outs
outsb outsd outsw packssdw packsswb
packuswb paddb paddd paddq paddsb
paddsw paddusb paddusw paddw pand
pandn pavgb pavgw pcmpeqb pcmpeqd
pcmpeqw pcmpgtb pcmpgtd pcmpgtw pextrw
↩
454 CHAPTER 30. D X86 INLINE ASSEMBLER

(continued)
pinsrw pmaddwd pmaxsw pmaxub pminsw
pminub pmovmskb pmulhuw pmulhw pmullw
pmuludq pop popa popad popf
popfd por prefetchnta prefetcht0 prefetcht1
prefetcht2 psadbw pshufd pshufhw pshuflw
pshufw pslld pslldq psllq psllw
psrad psraw psrld psrldq psrlq
psrlw psubb psubd psubq psubsb
psubsw psubusb psubusw psubw punpckhbw
punpckhdq punpckhqdq punpckhwd punpcklbw punpckldq
punpcklqdq punpcklwd push pusha pushad
pushf pushfd pxor rcl rcpps
rcpss rcr rdmsr rdpmc rdtsc
rep repe repne repnz repz
ret retf rol ror rsm
rsqrtps rsqrtss sahf sal sar
sbb scas scasb scasd scasw
seta setae setb setbe setc
sete setg setge setl setle
setna setnae setnb setnbe setnc
setne setng setnge setnl setnle
setno setnp setns setnz seto
setp setpe setpo sets setz
sfence sgdt shl shld shr
shrd shufpd shufps sidt sldt
smsw sqrtpd sqrtps sqrtsd sqrtss
stc std sti stmxcsr stos
stosb stosd stosw str sub
subpd subps subsd subss sysenter
sysexit test ucomisd ucomiss ud2
unpckhpd unpckhps unpcklpd unpcklps verr
verw wait wbinvd wrmsr xadd
xchg xlat xlatb xor xorpd
xorps
30.8. OPCODES SUPPORTED 455

Pentium 4 (Prescott) Opcodes Supported

Table 30.2: Pentium 4 Opcodes

addsubpd addsubps fisttp haddpd haddps

hsubpd hsubps lddqu monitor movddup
movshdup movsldup mwait

AMD Opcodes Supported

Table 30.3: AMD Opcodes

pavgusb pf2id pfacc pfadd pfcmpeq

pfcmpge pfcmpgt pfmax pfmin pfmul
pfnacc pfpnacc pfrcp pfrcpit1 pfrcpit2
pfrsqit1 pfrsqrt pfsub pfsubr pi2fd
pmulhrw pswapd

SIMD
SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4.2 and AVX are supported.
Chapter 31

Embedded Documentation

The D programming language enables embedding both contracts and test code along side the actual
code, which helps to keep them all consistent with each other. One thing lacking is the documen-
tation, as ordinary comments are usually unsuitable for automated extraction and formatting into
manual pages. Embedding the user documentation into the source code has important advantages,
such as not having to write the documentation twice, and the likelihood of the documentation
staying consistent with the code.
Some existing approaches to this are:

• Doxygen which already has some support for D

• Java’s Javadoc, probably the most well-known
• C#’s embedded XML
• Other documentation tools

D’s goals for embedded documentation are:

1. It looks good as embedded documentation, not just after it is extracted and processed.
2. It’s easy and natural to write, i.e. minimal reliance on <tags> and other clumsy forms one
would never see in a finished document.
3. It does not repeat information that the compiler already knows from parsing the code.
4. It doesn’t rely on embedded HTML, as such will impede extraction and formatting for other
purposes.
5. It’s based on existing D comment forms, so it is completely independent of parsers only
interested in D code.
6. It should look and feel different from code, so it won’t be visually confused with code.
7. It should be possible for the user to use Doxygen or other documentation extractor if desired.

457
458 CHAPTER 31. EMBEDDED DOCUMENTATION

31.1 Specification
The specification for the form of embedded documentation comments only specifies how information
is to be presented to the compiler. It is implementation-defined how that information is used and
the form of the final presentation. Whether the final presentation form is an HTML web page, a
man page, a PDF file, etc. is not specified as part of the D Programming Language.

Phases of Processing
Embedded documentation comments are processed in a series of phases:

1. Lexical - documentation comments are identified and attached to tokens.

2. Parsing - documentation comments are associated with specific declarations and combined.
3. Sections - each documentation comment is divided up into a sequence of sections.
4. Special sections are processed.
5. Highlighting of non-special sections is done.
6. All sections for the module are combined.
7. Macro and Escape text substitution is performed to produce the final result.

Lexical
Embedded documentation comments are one of the following forms:

1. /** ... */ The two *’s after the opening /

2. /++ ... +/ The two +’s after the opening /
3. /// The three slashes

The following are all embedded documentation comments:

/// This is a one line documentation comment.

/** So is this. */

/++ And this. +/

/**
This is a brief documentation comment.
*/

/**
* The leading * on this line is not part of the documentation comment.
31.1. SPECIFICATION 459

*/

/*********************************
The extra *’s immediately following the /** are not
part of the documentation comment.
*/

/++
This is a brief documentation comment.
+/

/++
+ The leading + on this line is not part of the documentation comment.
+/

/+++++++++++++++++++++++++++++++++
The extra +’s␣immediately␣following␣the␣/␣++␣are␣not
␣␣␣part␣of␣the␣documentation␣comment.
␣+/

/****************␣Closing␣*’s are not part *****************/

The extra *’s and +’s on the comment opening, closing and left margin are ignored and are
not part of the embedded documentation. Comments not following one of those forms are not
documentation comments.

Parsing
Each documentation comment is associated with a declaration. If the documentation comment is
on a line by itself or with only whitespace to the left, it refers to the next declaration. Multi-
ple documentation comments applying to the same declaration are concatenated. Documentation
comments not associated with a declaration are ignored. Documentation comments preceding the
ModuleDeclaration apply to the entire module. If the documentation comment appears on the same
line to the right of a declaration, it applies to that.
If a documentation comment for a declaration consists only of the identifier ditto then the
documentation comment for the previous declaration at the same declaration scope is applied to
this declaration as well.
If there is no documentation comment for a declaration, that declaration may not appear in the
output. To ensure it does appear in the output, put an empty declaration comment for it.
int a; /// documentation for a; b has no documentation
460 CHAPTER 31. EMBEDDED DOCUMENTATION

int b;

/** documentation for c and d */

/** more documentation for c and d */
int c;
/** ditto */
int d;

/** documentation for e and f */ int e;

int f; /// ditto

/** documentation for g */

int g; /// more documentation for g

/// documentation for C and D

class C
{
int x; /// documentation for C.x

/** documentation for C.y and C.z */

int y;
int z; /// ditto
}

/// ditto
class D { }

Sections
The document comment is a series of Sections. A Section is a name that is the first non-blank
character on a line immediately followed by a ’:’. This name forms the section name. The section
name is not case sensitive.

Summary

The first section is the Summary, and does not have a section name. It is first paragraph, up to a
blank line or a section name. While the summary can be any length, try to keep it to one line. The
Summary section is optional.
31.1. SPECIFICATION 461

Description
The next unnamed section is the Description. It consists of all the paragraphs following the Sum-
mary until a section name is encountered or the end of the comment.
While the Description section is optional, there cannot be a Description without a Summary
section.
/***********************************
* Brief summary of what
* myfunc does, forming the summary section.
*
* First paragraph of synopsis description.
*
* Second paragraph of
* synopsis description.
*/

void myfunc() { }
Named sections follow the Summary and Description unnamed sections.

Standard Sections
For consistency and predictability, there are several standard sections. None of these are required
to be present.

Authors: Lists the author(s) of the declaration.

/**
* Authors: Melvin D. Nerd, [email protected]
*/

Bugs: Lists any known bugs.

/**
* Bugs: Doesn’t work for negative values.
*/

Date: Specifies the date of the current revision. The date should be in a form parseable by
std.date.
/**
* Date: March 14, 2003
*/
462 CHAPTER 31. EMBEDDED DOCUMENTATION

Deprecated: Provides an explanation for and corrective action to take if the associated decla-
ration is marked as deprecated.
/**
* Deprecated: superseded by function bar().
*/

deprecated void foo() { ... }

Examples: Any usage examples

/**
* Examples:
* --------------------
* writeln("3"); // writes ’3’ to stdout
* --------------------
*/

History: Revision history.

/**
* History:
* V1 is initial version
*
* V2 added feature X
*/

License: Any license information for copyrighted code.

/**
* License: use freely for any purpose
*/

void bar() { ... }

Returns: Explains the return value of the function. If the function returns void, don’t redun-
dantly document it.
/**
* Read the file.
* Returns: The contents of the file.
*/
31.1. SPECIFICATION 463

void[] readFile(char[] filename) { ... }

See_Also: List of other symbols and URL’s to related items.

/**
* See_Also:
* foo, bar, http://www.digitalmars.com/d/phobos/index.html
*/

Standards: If this declaration is compliant with any particular standard, the description of it
goes here.
/**
* Standards: Conforms to DSPEC-1234
*/

Throws: Lists exceptions thrown and under what circumstances they are thrown.
/**
* Write the file.
* Throws: WriteException on failure.
*/

void writeFile(char[] filename) { ... }

Version: Specifies the current version of the declaration.

/**
* Version: 1.6a
*/

Special Sections
Some sections have specialized meanings and syntax.

Copyright: This contains the copyright notice. The macro COPYRIGHT is set to the contents
of the section when it documents the module declaration. The copyright section only gets
this special treatment when it is for the module declaration.
/** Copyright: Public Domain */

module foo;
464 CHAPTER 31. EMBEDDED DOCUMENTATION

Params: Function parameters can be documented by listing them in a params section. Each
line that starts with an identifier followed by an ’=’ starts a new parameter description. A
description can span multiple lines.
/***********************************
* foo does this.
* Params:
* x = is for this
* and not for that
* y = is for that
*/

void foo(int x, int y)

{
}

Macros: The macros section follows the same syntax as the Params: section. It’s a series of
NAME =value pairs. The NAME is the macro name, and value is the replacement text.
/**
* Macros:
* FOO = now is the time for
* all good men
* BAR = bar
* MAGENTA = <font color=magenta>\$(DOLLAR)0</font>
*/

Escapes= The escapes section is a series of substitutions which replace special characters with a
string. It’s useful when the output format requires escaping of certain characters, for example
in HTML & should be escaped with &amp;. The syntax is /c/string/, where c is either
a single character, or multiple characters separated by whitespace or commas, and string is
the replacement text.
/**
* ESCAPES = /&/AddressOf!/
* /!/Exclamation/
* /?/QuestionMark/
* /,/Comma/
* /{ }/Parens/
* /<,>/Arrows/
*/
31.2. HIGHLIGHTING 465

31.2 Highlighting
Embedded Comments
The documentation comments can themselves be commented using the $(DDOC_COMMENT ⤦
Ç comment text) syntax. These comments do not nest.

Embedded Code
D code can be embedded using lines beginning with at least three hyphens (ignoring whitespace)
to delineate the code section:
/++
+ Our function.
+
+ Example:
+ ---
+ import std.stdio;
+
+ void foo()
+ {
+ writeln("foo!"); /* print the string */
+ }
+ ---
+/
Note that the documentation comment uses the /++ ... +/ form so that /* ... */ can be used
inside the code section.

Inline Code
Inline code can be written between backtick characters (‘), similarly to the syntax used on GitHub,
Reddit, Stack Overflow, and other websites. Both the opening and closing ‘ character must appear
on the same line to trigger this behavior.
Text inside these sections will be escaped according to the rules described above, then wrapped
in a \$(DDOC_BACKQUOTED) macro. By default, this macro expands to be displayed as an inline text
span, formatted as code.
A literal backtick character can be output either as a non-paired ‘ on a single line or by using
the ‘ macro.
/// Returns ‘true‘ if ‘a == b‘.
void foo() {}
466 CHAPTER 31. EMBEDDED DOCUMENTATION

/// Backquoted ‘<html>‘ will be displayed to the user instead

/// of passed through as embedded HTML (see below).
void bar() {}

Embedded HTML
HTML can be embedded into the documentation comments, and it will be passed through to the
HTML output unchanged. However, since it is not necessarily true that HTML will be the desired
output format of the embedded documentation comment extractor, it is best to avoid using it where
practical.
/**
* Example of embedded HTML:
*
* <ol>
* <li><a href="http://www.digitalmars.com">Digital Mars</a></li>
* <li><a href="http://www.classicempire.com">Empire</a></li>
* </ol>
*/

Emphasis
Identifiers in documentation comments that are function parameters or are names that are in scope
at the associated declaration are emphasized in the output. This emphasis can take the form of
italics, boldface, a hyperlink, etc. How it is emphasized depends on what it is - a function parameter,
type, D keyword, etc. To prevent unintended emphasis of an identifier, it can be preceded by an
underscore (_). The underscore will be stripped from the output.

Character Entities
Some characters have special meaning to the documentation processor, to avoid confusion it can be
best to replace them with their corresponding character entities:

Characters and Entities

Character Entity
< &lt;
> &gt;
& &amp;

It is not necessary to do this inside a code section, or if the special character is not immediately
followed by a # or a letter.
31.3. MACROS 467

No Documentation
No documentation is generated for the following constructs, even if they have a documentation
comment:

• Invariants
• Postblits
• Destructors
• Static constructors and static destructors
• Class info, type info, and module info

31.3 Macros
The documentation comment processor includes a simple macro text preprocessor. When a
$(NAME ) appears in section text it is replaced with NAME ’s corresponding replacement text.
For example:
/**
Macros:
PARAM = <u>\$1</u>
MATH_DOCS = <a href="http://dlang.org/phobos/std_math.html">Math Docs</a>
*/
module math;

/**
* This function returns the sum of \$(PARAM a) and \$(PARAM b).
* See also the \$(MATH_DOCS).
*/
int sum(int a, int b) { return a + b; }
The above would generate the following output:
<h1>test</h1>
<dl><dt><big><a name="sum"></a>int <u>sum</u>(int <i>a</i>, int <i>b</i>);
</big></dt>
<dd>This function returns the <u>sum</u> of <u><i>a</i></u> and <u><i>b</i></u>.
See also the <a href="http://dlang.org/phobos/std_math.html">Math Docs</a>.
</dd>
</dl>
The replacement text is recursively scanned for more macros. If a macro is recursively encoun-
tered, with no argument or with the same argument text as the enclosing macro, it is replaced with
468 CHAPTER 31. EMBEDDED DOCUMENTATION

no text. Macro invocations that cut across replacement text boundaries are not expanded. If the
macro name is undefined, the replacement text has no characters in it. If a $(NAME) is desired to
exist in the output without being macro expanded, the $ should be replaced with &#36;.
Macros can have arguments. Any text from the end of the identifier to the closing ‘)’ is the $0
argument. A $0 in the replacement text is replaced with the argument text. If there are commas
in the argument text, $1 will represent the argument text up to the first comma, $2 from the
first comma to the second comma, etc., up to $9. $+ represents the text from the first comma to
the closing ‘)’. The argument text can contain nested parentheses, "" or ” strings, <!-- ... -->
comments, or tags. If stray, unnested parentheses are used, they can be replaced with the entity
&#40; for ( and &#41; for ).
Macro definitions come from the following sources, in the specified order:

1. Predefined macros.
2. Definitions from file specified by sc.ini’s or dmd.conf DDOCFILE setting.
3. Definitions from *.ddoc files specified on the command line.
4. Runtime definitions generated by Ddoc.
5. Definitions from any Macros: sections.

Macro redefinitions replace previous definitions of the same name. This means that the sequence
of macro definitions from the various sources forms a hierarchy.
Macro names beginning with "D_" and "DDOC_" are reserved.

Predefined Macros
These are hardwired into Ddoc, and represent the minimal definitions needed by Ddoc to format
and highlight the presentation. The definitions are for simple HTML.
B = <b>\$0</b>
I = <i>\$0</i>
U = <u>\$0</u>
P = <p>\$0</p>
DL = <dl>\$0</dl>
DT = <dt>\$0</dt>
DD = <dd>\$0</dd>
TABLE = <table>\$0</table>
TR = <tr>\$0</tr>
TH = <th>\$0</th>
TD = <td>\$0</td>
OL = <ol>\$0</ol>
UL = <ul>\$0</ul>
LI = <li>\$0</li>
31.3. MACROS 469

BIG = <big>\$0</big>
SMALL = <small>\$0</small>
BR = <br>
LINK = <a href="\$0">\$0</a>
LINK2 = <a href="\$1">\$+</a>
LPAREN = (
RPAREN = )
BACKTICK = ‘
DOLLAR = \$
DEPRECATED = \$0

RED = <font color=red>\$0</font>

BLUE = <font color=blue>\$0</font>
GREEN = <font color=green>\$0</font>
YELLOW = <font color=yellow>\$0</font>
BLACK = <font color=black>\$0</font>
WHITE = <font color=white>\$0</font>

D_CODE = <pre class="d_code">\$0</pre>

D_INLINECODE = <pre style="display:inline;" class="d_inline_code">\$0</pre>
D_COMMENT = \$(GREEN \$0)
D_STRING = \$(RED \$0)
D_KEYWORD = \$(BLUE \$0)
D_PSYMBOL = \$(U \$0)
D_PARAM = \$(I \$0)

DDOC = <html><head>
<META http-equiv="content-type" content="text/html;␣charset=utf-8">
<title>\$(TITLE)</title>
</head><body>
<h1>\$(TITLE)</h1>
\$(BODY)
<hr>\$(SMALL Page generated by \$(LINK2 http://dlang.org/ddoc.html, ⤦
Ç Ddoc). \$(COPYRIGHT))
</body></html>

DDOC_COMMENT = <!-- \$0 -->

DDOC_DECL = \$(DT \$(BIG \$0))
DDOC_DECL_DD = \$(DD \$0)
DDOC_DITTO = \$(BR)\$0
470 CHAPTER 31. EMBEDDED DOCUMENTATION

DDOC_SECTIONS = \$0
DDOC_SUMMARY = \$0\$(BR)\$(BR)
DDOC_DESCRIPTION = \$0\$(BR)\$(BR)
DDOC_AUTHORS = \$(B Authors:)\$(BR)\$0\$(BR)\$(BR)
DDOC_BUGS = \$(RED BUGS:)\$(BR)\$0\$(BR)\$(BR)
DDOC_COPYRIGHT = \$(B Copyright:)\$(BR)\$0\$(BR)\$(BR)
DDOC_DATE = \$(B Date:)\$(BR)\$0\$(BR)\$(BR)
DDOC_DEPRECATED = \$(RED Deprecated:)\$(BR)\$0\$(BR)\$(BR)
DDOC_EXAMPLES = \$(B Examples:)\$(BR)\$0\$(BR)\$(BR)
DDOC_HISTORY = \$(B History:)\$(BR)\$0\$(BR)\$(BR)
DDOC_LICENSE = \$(B License:)\$(BR)\$0\$(BR)\$(BR)
DDOC_RETURNS = \$(B Returns:)\$(BR)\$0\$(BR)\$(BR)
DDOC_SEE_ALSO = \$(B See Also:)\$(BR)\$0\$(BR)\$(BR)
DDOC_STANDARDS = \$(B Standards:)\$(BR)\$0\$(BR)\$(BR)
DDOC_THROWS = \$(B Throws:)\$(BR)\$0\$(BR)\$(BR)
DDOC_VERSION = \$(B Version:)\$(BR)\$0\$(BR)\$(BR)
DDOC_SECTION_H = \$(B \$0)\$(BR)\$(BR)
DDOC_SECTION = \$0\$(BR)\$(BR)
DDOC_MEMBERS = \$(DL \$0)
DDOC_MODULE_MEMBERS = \$(DDOC_MEMBERS \$0)
DDOC_CLASS_MEMBERS = \$(DDOC_MEMBERS \$0)
DDOC_STRUCT_MEMBERS = \$(DDOC_MEMBERS \$0)
DDOC_ENUM_MEMBERS = \$(DDOC_MEMBERS \$0)
DDOC_TEMPLATE_MEMBERS = \$(DDOC_MEMBERS \$0)
DDOC_ENUM_BASETYPE = \$0
DDOC_PARAMS = \$(B Params:)\$(BR)\n\$(TABLE \$0)\$(BR)
DDOC_PARAM_ROW = \$(TR \$0)
DDOC_PARAM_ID = \$(TD \$0)
DDOC_PARAM_DESC = \$(TD \$0)
DDOC_BLANKLINE = \$(BR)\$(BR)

DDOC_ANCHOR = <a name="\$1"></a>

DDOC_PSYMBOL = \$(U \$0)
DDOC_PSUPER_SYMBOL = \$(U \$0)
DDOC_KEYWORD = \$(B \$0)
DDOC_PARAM = \$(I \$0)
DDOC_BACKQUOTED = \$(D_INLINECODE \$0)

ESCAPES = /</\&lt;/
/>/\&gt;/
31.3. MACROS 471

/\&/\&amp;/
Ddoc does not generate HTML code. It formats into the basic formatting macros, which (in
their predefined form) are then expanded into HTML. If output other than HTML is desired, then
these macros need to be redefined.

Table 31.1: Basic Formatting Macros

Name Description
B boldface the argument
I italicize the argument
U underline the argument
P argument is a paragraph
DL argument is a definition list
DT argument is a definition in a definition list
DD argument is a description of a definition
TABLE argument is a table
TR argument is a row in a table
TH argument is a header entry in a row
TD argument is a data entry in a row
OL argument is an ordered list
UL argument is an unordered list
LI argument is an item in a list
BIG argument is one font size bigger
SMALL argument is one font size smaller
BR start new line
LINK generate clickable link on argument
LINK2 generate clickable link, first arg is address
RED argument is set to be red
BLUE argument is set to be blue
GREEN argument is set to be green
YELLOW argument is set to be yellow
BLACK argument is set to be black
WHITE argument is set to be white
D_CODE argument is D code
D_INLINECODE argument is inline D code
DDOC overall template for output
472 CHAPTER 31. EMBEDDED DOCUMENTATION

DDOC is special in that it specifies the boilerplate into which the entire generated text is
inserted (represented by the Ddoc generated macro BODY). For example, in order to use a style
sheet, DDOC would be redefined as:
DDOC = <!DOCTYPE HTML PUBLIC "-//W3C//DTD␣HTML␣4.01//EN" ⤦
Ç "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<META http-equiv="content-type" content="text/html;␣charset=utf-8">
<title>\$(TITLE)</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head><body>
<h1>\$(TITLE)</h1>
\$(BODY)
</body></html>
DDOC_COMMENT is used to insert comments into the output file.
Highlighting of D code is performed by the following macros:

Table 31.2: D Code Formatting Macros

Name Description
D_COMMENT Highlighting of comments
D_STRING Highlighting of string literals
D_KEYWORD Highlighting of D keywords
D_PSYMBOL Highlighting of current declaration name
D_PARAM Highlighting of current function declaration parameters

The highlighting macros start with DDOC_. They control the formatting of individual parts of
the presentation.

Table 31.3: Ddoc Section Formatting Macros

Name Description
DDOC_COMMENT Inserts a HTML comment.
DDOC_DECL Highlighting of the declaration.
DDOC_DECL_DD Highlighting of the description of a declaration.
DDOC_DITTO Highlighting of ditto declarations.
DDOC_SECTIONS Highlighting of all the sections.
↩
31.3. MACROS 473

(continued)
Name Description
DDOC_SUMMARY Highlighting of the summary section.
DDOC_DESCRIPTION Highlighting of the description section.
DDOC_AUTHORS Highlighting of the authors section.
DDOC_BUGS Highlighting of the bugs section.
DDOC_COPYRIGHT Highlighting of the copyright section.
DDOC_DATE Highlighting of the date section.
DDOC_DEPRECATED Highlighting of the deprecated section.
DDOC_EXAMPLES Highlighting of the examples section.
DDOC_HISTORY Highlighting of the history section.
DDOC_LICENSE Highlighting of the license section.
DDOC_RETURNS Highlighting of the returns section.
DDOC_SEE_ALSO Highlighting of the see-also section.
DDOC_STANDARDS Highlighting of the standards section.
DDOC_THROWS Highlighting of the throws section.
DDOC_VERSION Highlighting of the version section.
DDOC_SECTION_H Highlighting of the section name of a non-standard sec-
tion.
DDOC_SECTION Highlighting of the contents of a non-standard section.
DDOC_MEMBERS Default highlighting of all the members of a class,
struct, etc.
DDOC_MODULE_MEMBERS Highlighting of all the members of a module.
DDOC_CLASS_MEMBERS Highlighting of all the members of a class.
DDOC_STRUCT_MEMBERS Highlighting of all the members of a struct.
DDOC_ENUM_MEMBERS Highlighting of all the members of an enum.
DDOC_TEMPLATE_MEMBERS Highlighting of all the members of a template.
DDOC_ENUM_BASETYPE Highlighting of the type an enum is based upon
DDOC_PARAMS Highlighting of a function parameter section.
DDOC_PARAM_ROW Highlighting of a name=value function parameter.
DDOC_PARAM_ID Highlighting of the parameter name.
DDOC_PARAM_DESC Highlighting of the parameter value.
DDOC_BLANKLINE Inserts a blank line.
DDOC_ANCHOR Expands to a named anchor used for hyperlinking to
a particular declaration section. Argument $1 expands
to the qualified declaration name.
DDOC_PSYMBOL Highlighting of declaration name to which a particular
section is referring.
↩
474 CHAPTER 31. EMBEDDED DOCUMENTATION

(continued)
Name Description
DDOC_PSUPER_SYMBOL Highlighting of the base type of a class.
DDOC_KEYWORD Highlighting of D keywords.
DDOC_PARAM Highlighting of function parameters.
DDOC_BACKQUOTED Inserts inline code.

For example, one could redefine DDOC_SUMMARY:

DDOC_SUMMARY = \$(GREEN \$0)
And all the summary sections will now be green.

Macro Definitions from sc.ini’s DDOCFILE

A text file of macro definitions can be created, and specified in sc.ini:
DDOCFILE=myproject.ddoc

Macro Definitions from .ddoc Files on the Command Line

File names on the DMD command line with the extension .ddoc are text files that are read and
processed in order.

Macro Definitions Generated by Ddoc

Table 31.4: Generated Macro Definitions

Macro Name Content
BODY Set to the generated document text.
TITLE Set to the module name.
DATETIME Set to the current date and time.
YEAR Set to the current year.
COPYRIGHT Set to the contents of any Copyright: section that is part
of the module comment.
DOCFILENAME Set to the name of the generated output file.
SRCFILENAME Set to the name of the source file the documentation is being
generated from.
31.4. USING DDOC TO GENERATE EXAMPLES FROM UNIT TESTS 475

31.4 Using Ddoc to generate examples from unit tests

Ddoc can automatically generate usage examples for declarations using unit tests. If a declaration
is followed by a documented unit test, the code from the test will be inserted into the example
section of the declaration. This avoids the frequent problem of having outdated documentation for
pieces of code.
To create a documented unit test just add three forward slashes before the unittest block, like
this:
///
unittest
{
...
}
For more information please see the full section on documented unit tests.

31.5 Using Ddoc for other Documentation

Ddoc is primarily designed for use in producing documentation from embedded comments. It can
also, however, be used for processing other general documentation. The reason for doing this would
be to take advantage of the macro capability of Ddoc and the D code syntax highlighting capability.
If the .d source file starts with the string "Ddoc" then it is treated as general purpose docu-
mentation, not as a D code source file. From immediately after the "Ddoc" string to the end of the
file or any "Macros:" section forms the document. No automatic highlighting is done to that text,
other than highlighting of D code embedded between lines delineated with — lines. Only macro
processing is done.
Much of the D documentation itself is generated this way, including this page. Such documen-
tation is marked at the bottom as being generated by Ddoc.

31.6 Links to D documentation generators

A list of current D documentation generators which use Ddoc can be found on our wiki page.
Chapter 32

Interfacing to C

D is designed to fit comfortably with a C compiler for the target system. D makes up for not having
its own VM by relying on the target environment’s C runtime library. It would be senseless to
attempt to port to D or write D wrappers for the vast array of C APIs available. How much easier
it is to just call them directly.
This is done by matching the C compiler’s data types, layouts, and function call/return se-
quences.

32.1 Calling C Functions

C functions can be called directly from D. There is no need for wrapper functions, argument
swizzling, and the C functions do not need to be put into a separate DLL.
The C function must be declared and given a calling convention, most likely the "C" calling
convention, for example:
extern (C) int strcmp(char* string1, char* string2);
and then it can be called within D code in the obvious way:
import std.string;
int myDfunction(char[] s)
{
return strcmp(std.string.toStringz(s), "foo");
}
There are several things going on here:

• D understands how C function names are "mangled" and the correct C function call/return
sequence.
• C functions cannot be overloaded with another C function with the same name.

477
478 CHAPTER 32. INTERFACING TO C

• There are no __cdecl, __far, __stdcall, __declspec, or other such C extended type modi-
fiers in D. These are handled by linkage attributes, such as extern (C).
• There is no volatile type modifier in D. To declare a C function that uses volatile, just drop
the keyword from the declaration.
• Strings are not 0 terminated in D. See "Data Type Compatibility" for more information about
this. However, string literals in D are 0 terminated.

C code can correspondingly call D functions, if the D functions use an attribute that is compat-
ible with the C compiler, most likely the extern (C):
// myfunc() can be called from any C function
extern (C)
{
void myfunc(int a, int b)
{
...
}
}

32.2 Storage Allocation

C code explicitly manages memory with calls to malloc() and free(). D allocates memory using the
D garbage collector, so no explicit free’s are necessary.
D can still explicitly allocate memory using core.stdc.stdlib.malloc() and core.stdc.stdlib.free(),
these are useful for connecting to C functions that expect malloc’d buffers, etc.
If pointers to D garbage collector allocated memory are passed to C functions, it’s critical to
ensure that that memory will not be collected by the garbage collector before the C function is done
with it. This is accomplished by:

• Making a copy of the data using core.stdc.stdlib.malloc() and passing the copy instead.
• Leaving a pointer to it on the stack (as a parameter or automatic variable), as the garbage
collector will scan the stack.
• Leaving a pointer to it in the static data segment, as the garbage collector will scan the static
data segment.
• Registering the pointer with the garbage collector with the
std.gc.addRoot() or
std.gc.addRange() calls.

An interior pointer to the allocated memory block is sufficient to let the GC know the object is
in use; i.e. it is not necessary to maintain a pointer to the beginning of the allocated memory.
32.2. STORAGE ALLOCATION 479

The garbage collector does not scan the stacks of threads not created by the D Thread interface.
Nor does it scan the data segments of other DLL’s, etc.
480 CHAPTER 32. INTERFACING TO C

32.3 Data Type Compatibility

D And C Type Equivalence

C
D
32 bit 64 bit
void void
byte signed char
ubyte unsigned char
char char (chars are unsigned in D)
wchar wchar_t (when sizeof(wchar_t) is 2)
dchar wchar_t (when sizeof(wchar_t) is 4)
short short
ushort unsigned short
int int
uint unsigned
ulong unsigned long long unsigned long
core.stdc.config.c_long long long
core.stdc.config.c_ulong unsigned long unsigned long
long long long long (or long long)
ulong unsigned long long unsigned long (or unsigned long long)
float float
double double
real long double
cdouble double _Complex
creal long double _Complex
struct struct
union union
enum enum
class no equivalent
type * type *
type[dim] type[dim]
type[dim]* type(*)[dim]
type[] no equivalent
type1[type2] no equivalent
type function(params) type(*)(params)
type delegate(params) no equivalent
size_t size_t
ptrdiff_t ptrdiff_t
32.4. PASSING D ARRAY ARGUMENTS TO C FUNCTIONS 481

These equivalents hold for most C compilers. The C standard does not pin down the sizes of
the types, so some care is needed.

32.4 Passing D Array Arguments to C Functions

In C, arrays are passed to functions as pointers even if the function prototype says its an array.
In D, static arrays are passed by value, not by reference. Thus, the function prototype must be
adjusted to match what C expects.

D And C Function Prototype Equivalence

D type C type
T* T []
ref T [dim] T [dim]

For example:
void foo(int a[3]) { ... } // C code

extern (C)
{
void foo(ref int[3] a); // D prototype
}

32.5 Calling printf()

This mostly means checking that the printf format specifier matches the corresponding D data type.
Although printf is designed to handle 0 terminated strings, not D dynamic arrays of chars, it turns
out that since D dynamic arrays are a length followed by a pointer to the data, the %.*s format
works:
void foo(char[] string)
{
printf("my␣string␣is:␣%.*s\n", string.length, string.ptr);
}
The printf format string literal in the example doesn’t end with ’\0’. This is because string
literals, when they are not part of an initializer to a larger data structure, have a ’\0’ character
helpfully stored after the end of them.
An improved D function for formatted output is std.stdio.writef().
482 CHAPTER 32. INTERFACING TO C

32.6 Structs and Unions

D structs and unions are analogous to C’s.
C code often adjusts the alignment and packing of struct members with a command line switch
or with various implementation specific #pragma’s. D supports explicit alignment attributes that
correspond to the C compiler’s rules. Check what alignment the C code is using, and explicitly set
it for the D struct declaration.
D does not support bit fields. If needed, they can be emulated with shift and mask operations,
or use the std.bitmanip.bitfields library type. htod will convert bit fields to inline functions that do
the right shift and masks.
D does not support declaring variables of anonymous struct types. In such a case you can define
a named struct in D and make it private:
union Info // C code
{
struct
{
char *name;
} file;
};

union Info // D code

{
private struct File
{
char* name;
}
File file;
}

32.7 Callbacks
D can easily call C callbacks (function pointers), and C can call callbacks provided by D code if
the callback is an extern(C) function, or some other linkage that both sides have agreed to (e.g.
extern(Windows)).
Here’s an example of C code providing a callback to D code:
void someFunc(void *arg) { printf("Called␣someFunc!\n"); } // C code
typedef void (*Callback)(void *);
extern "C" Callback getCallback(void)
{
32.8. USING EXISTING C LIBRARIES 483

return someFunc;
}

extern(C) alias Callback = int function(int, int); // D code

extern(C) Callback getCallback();
void main()
{
Callback cb = getCallback();
cb(); // invokes the callback
}
And an example of D code providing a callback to C code:
extern "C" void printer(int (*callback)(int, int)) // C code
{
printf("calling␣callback␣with␣2␣and␣4␣returns:␣%d\n", callback(2, 4));
}

extern(C) alias Callback = int function(int, int); // D code

extern(C) void printer(Callback callback);
extern(C) int sum(int x, int y) { return x + y; }
void main()
{
printer(&sum);
}
For more info about callbacks read the closures section.

32.8 Using Existing C Libraries

Since D can call C code directly, it can also call any C library functions, giving D access to the
smorgasbord of existing C libraries. To do so, however, one needs to write a D interface (.di) file,
which is a translation of the C .h header file for the C library into D.
For popular C libraries, the first place to look for the corresponding D interface file is the Deimos
Project. If it isn’t there already, and you write one, please contribute it to the Deimos Project.

32.9 Accessing C Globals

C globals can be accessed directly from D. C globals have the C naming convention, and so must
be in an extern (C) block. Use the extern storage class to indicate that the global is allocated
in the C code, not the D code. C globals default to being in global, not thread local, storage. To
reference global storage from D, use the __gshared storage class.
484 CHAPTER 32. INTERFACING TO C

extern (C) extern __gshared int x;

Chapter 33

Interfacing to C++

While D is fully capable of interfacing to C, its ability to interface to C++ is much more limited.
There are three ways to do it:

1. Use C++’s ability to create a C interface, and then use D’s ability to interface with C to
access that interface.
2. Use C++’s ability to create a COM interface, and then use D’s ability to interface with COM
to access that interface.
3. Use the limited ability described here to connect directly to C++ functions and classes.

33.1 The General Idea

Being 100a fully functional C++ compiler front end to D. Anecdotal evidence suggests that writing
such is a minimum of a 10 man-year project, essentially making a D compiler with such capability
unimplementable. Other languages looking to hook up to C++ face the same problem, and the
solutions have been:

1. Support the COM interface (but that only works for Windows).
2. Laboriously construct a C wrapper around the C++ code.
3. Use an automated tool such as SWIG to construct a C wrapper.
4. Reimplement the C++ code in the other language.
5. Give up.

D takes a pragmatic approach that assumes a couple modest accommodations can solve a sig-
nificant chunk of the problem:

• matching C++ name mangling conventions

485
486 CHAPTER 33. INTERFACING TO C++

• matching C++ function calling conventions

• matching C++ virtual function table layout for single inheritance

33.2 Calling C++ Global Functions From D

Given a C++ function in a C++ source file:
#include <iostream>

using namespace std;

int foo(int i, int j, int k)

{
cout << "i␣=␣" << i << endl;
cout << "j␣=␣" << j << endl;
cout << "k␣=␣" << k << endl;

return 7;
}
In the corresponding D code, foo is declared as having C++ linkage and function calling con-
ventions:
extern (C++) int foo(int i, int j, int k);
and then it can be called within the D code:
extern (C++) int foo(int i, int j, int k);

void main()
{
foo(1,2,3);
}
Compiling the two files, the first with a C++ compiler, the second with a D compiler, linking
them together, and then running it yields:
i = 1 j = 2 k = 3
There are several things going on here:

• D understands how C++ function names are "mangled" and the correct C++ function cal-
l/return sequence.
• Because modules are not part of C++, each function with C++ linkage must be globally
unique within the program.
33.3. CALLING GLOBAL D FUNCTIONS FROM C++ 487

• There are no __cdecl, __far, __stdcall, __declspec, or other such nonstandard C++
extensions in D.
• There are no volatile type modifiers in D.
• Strings are not 0 terminated in D. See "Data Type Compatibility" for more information about
this. However, string literals in D are 0 terminated.

C++ Namespaces
C++ functions that reside in namespaces can be directly called from D. A namespace can be added
to the extern (C++) LinkageAttribute:
extern (C++, N) int foo(int i, int j, int k);

void main()
{
N.foo(1,2,3); // foo is in C++ namespace ’N’
}

33.3 Calling Global D Functions From C++

To make a D function accessible from C++, give it C++ linkage:
import std.stdio;

extern (C++) int foo(int i, int j, int k)

{
writefln("i␣=␣%s", i);
writefln("j␣=␣%s", j);
writefln("k␣=␣%s", k);
return 1;
}

extern (C++) void bar();

void main()
{
bar();
}
The C++ end looks like:
488 CHAPTER 33. INTERFACING TO C++

int foo(int i, int j, int k);

void bar()
{
foo(6, 7, 8);
}
Compiling, linking, and running produces the output:
i = 6 j = 7 k = 8

33.4 Classes
D classes are singly rooted by Object, and have an incompatible layout from C++ classes. D
interfaces, however, are very similar to C++ single inheritance class heirarchies. So, a D interface
with the attribute of extern (C++) will have a virtual function pointer table (vtbl[]) that exactly
matches C++’s. A regular D interface has a vtbl[] that differs in that the first entry in the vtbl[] is
a pointer to D’s RTTI info, whereas in C++ the first entry points to the first virtual function.

33.5 Calling C++ Virtual Functions From D

Given C++ source code defining a class like:
#include <iostream>

using namespace std;

class D
{
public:
virtual int bar(int i, int j, int k)
{
cout << "i␣=␣" << i << endl;
cout << "j␣=␣" << j << endl;
cout << "k␣=␣" << k << endl;
return 8;
}
};

D *getD()
{
33.6. CALLING D VIRTUAL FUNCTIONS FROM C++ 489

D *d = new D();
return d;
}
We can get at it from D code like:
extern (C++)
{
interface D
{
int bar(int i, int j, int k);
}

D getD();
}

void main()
{
D d = getD();
d.bar(9,10,11);
}

33.6 Calling D Virtual Functions From C++

Given D code like:
extern (C++) int callE(E);

extern (C++) interface E

{
int bar(int i, int j, int k);
}

class F : E
{
extern (C++) int bar(int i, int j, int k)
{
writefln("i␣=␣%s", i);
writefln("j␣=␣%s", j);
writefln("k␣=␣%s", k);
return 8;
490 CHAPTER 33. INTERFACING TO C++

}
}

void main()
{
F f = new F();
callE(f);
}
The C++ code to access it looks like:
class E
{
public:
virtual int bar(int i, int j, int k);
};

int callE(E *e)

{
return e->bar(11,12,13);
}
Note:

• non-virtual functions, and static member functions, cannot be accessed.

• class fields can only be accessed via virtual getter and setter methods.

33.7 Function Overloading

C++ and D follow different rules for function overloading. D source code, even when calling
extern (C++) functions, will still follow D overloading rules.

33.8 Storage Allocation

C++ code explicitly manages memory with calls to ::operator new() and ::operator delete().
D allocates memory using the D garbage collector, so no explicit delete’s are necessary. D’s new
and delete are not compatible with C++’s ::operator new and ::operator delete. Attempting
to allocate memory with C++ ::operator new and deallocate it with D’s delete, or vice versa,
will result in miserable failure.
33.8. STORAGE ALLOCATION 491

D can still explicitly allocate memory using core.stdc.stdlib.malloc() and core.stdc.stdlib.free(),

these are useful for connecting to C++ functions that expect malloc’d buffers, etc.

If pointers to D garbage collector allocated memory are passed to C++ functions, it’s critical
to ensure that that memory will not be collected by the garbage collector before the C++ function
is done with it. This is accomplished by:

• Making a copy of the data using core.stdc.stdlib.malloc() and passing the copy instead.
• Leaving a pointer to it on the stack (as a parameter or automatic variable), as the garbage
collector will scan the stack.
• Leaving a pointer to it in the static data segment, as the garbage collector will scan the static
data segment.
• Registering the pointer with the garbage collector with the std.gc.addRoot() or
std.gc.addRange() calls.

An interior pointer to the allocated memory block is sufficient to let the GC know the object is
in use; i.e. it is not necessary to maintain a pointer to the beginning of the allocated memory.

The garbage collector does not scan the stacks of threads not created by the D Thread interface.
Nor does it scan the data segments of other DLL’s, etc.
492 CHAPTER 33. INTERFACING TO C++

33.9 Data Type Compatibility

D And C Type Equivalence
D type C type
void void
byte signed char
ubyte unsigned char
char char (chars are unsigned in D)
wchar wchar_t (when sizeof(wchar_t) is 2)
dchar wchar_t (when sizeof(wchar_t) is 4)
short short
ushort unsigned short
int int
uint unsigned
long long long
ulong unsigned long long
float float
double double
real long double
ifloat no equivalent
idouble no equivalent
ireal no equivalent
cfloat no equivalent
cdouble no equivalent
creal no equivalent
struct struct
union union
enum enum
class no equivalent
type* type *
no equivalent type &
type[dim] type[dim]
type[dim]* type(*)[dim]
type[] no equivalent
type[type] no equivalent
type function(parameters) type(*)(parameters)
type delegate(parameters) no equivalent

These equivalents hold for most 32 bit C++ compilers. The C++ standard does not pin down
33.10. STRUCTS AND UNIONS 493

the sizes of the types, so some care is needed.

33.10 Structs and Unions

D structs and unions are analogous to C’s.
C code often adjusts the alignment and packing of struct members with a command line switch
or with various implementation specific #pragma’s. D supports explicit alignment attributes that
correspond to the C compiler’s rules. Check what alignment the C code is using, and explicitly set
it for the D struct declaration.
D does not support bit fields. If needed, they can be emulated with shift and mask operations.
htod will convert bit fields to inline functions that do the right shift and masks.

33.11 Object Construction and Destruction

Similarly to storage allocation and deallocation, objects constructed in D code should be destructed
in D, and objects constructed in C++ should be destructed in C++ code.

33.12 Special Member Functions

D cannot call C++ special member functions, and vice versa. These include constructors, destruc-
tors, conversion operators, operator overloading, and allocators.

33.13 Runtime Type Identification

D runtime type identification uses completely different techniques than C++. The two are incom-
patible.

33.14 C++ Class Objects by Value

D can access POD (Plain Old Data) C++ structs, and it can access C++ class virtual functions
by reference. It cannot access C++ classes by value.

33.15 C++ Templates

D templates have little in common with C++ templates, and it is very unlikely that any sort of
reasonable method could be found to express C++ templates in a link-compatible way with D.
This means that the C++ STL, and C++ Boost, likely will never be accessible from D.
494 CHAPTER 33. INTERFACING TO C++

33.16 Exception Handling

D and C++ exception handling are completely different. Throwing exceptions across the boundaries
between D and C++ code will likely not work.
33.16. EXCEPTION HANDLING 495
496 CHAPTER 33. INTERFACING TO C++

33.17 Comparing D Immutable and Const with C++ Const

Const, Immutable Comparison
Feature D C++98
const keyword Yes Yes
immutable keyword Yes No
// Functional: // Postfix:
const notation //ptr to const ptr to const int //ptr to const ptr to const int
const(int*)* p; const int *const *p;
// Yes: // No:
transitive const //const ptr to const ptr to const int // const ptr to ptr to int
const int** p; int** const p;
**p = 3; // error **p = 3; // ok
// Yes: // Yes:
cast away const // ptr to const int // ptr to const int
const(int)* p; const int* p;
int* q = cast(int*)p; // ok int* q = const_cast&lt;int*&gt;p; //ok
// No: // Yes:
// ptr to const int // ptr to const int
cast+mutate const(int)* p; const int* p;
int* q = cast(int*)p; int* q = const_cast&lt;int*&gt;p;
*q = 3; // undefined behavior *q = 3; // ok
// Yes: // No:
overloading void foo(int x); void foo(int x);
void foo(const int x); //ok void foo(const int x); //error
// Yes: // Yes:
void foo(const int* x, int* y) void foo(const int* x, int* y)
{ {
bar(*x); // bar(3) bar(*x); // bar(3)
const/mutable *y = 4; *y = 4;
aliasing bar(*x); // bar(4) bar(*x); // bar(4)
} }
... ...
int i = 3; int i = 3;
foo(&i, &i); foo(&i, &i);
// No:
void foo(immutable int* x, int* y)
{
bar(*x); // bar(3)
immutable/mutable *y = 4; // undefined behavior No immutables
aliasing bar(*x); // bar(??)
}
...
int i = 3;
foo(cast(immutable)&i, &i);
type of string literal immutable(char)[] const char*
33.18. FUTURE DEVELOPMENTS 497

33.18 Future Developments

How the upcoming C++1y standard will affect this is not known.
Over time, more aspects of the C++ ABI may be accessible directly from D.
Chapter 34

Interfacing to Objective-C

D has limited support for interfacing with Objective-C. It supports external classes and calling
instance methods. It is only available on OS X, compiling for 64bit.
Fully working example is available at the bottom.

34.1 Declaring an External Class

extern (Objective-C)
interface NSString
{
const(char)* UTF8String() @selector("UTF8String");
}

Currently all Objective-C classes need to be declared as interfaces in D. All Objective-C classes
that should be accessible from within D need to be declared with the Objective-C linkage.
The @selector attribute indicates which Objective-C selector should be used when calling this
method from D. This attribute needs to be attached to all methods.
34.2 Calling an Instance Method
Calling an Objective-C instance method uses the same syntax as calling regular D methods:

const(char)* result = object.UTF8String();

When the compiler sees a call to a method with Objective-C linkage it will generate a call similar
to how an Objective-C compiler would call the method.

499
500 CHAPTER 34. INTERFACING TO OBJECTIVE-C

34.3 The @selector Attribute

The @selector attribute is a compiler recognized UDA. It is used to tell the compiler which selector
to use when calling an Objective-C method.
Selectors in Objective-C can contain characters that are not valid in D identifiers, :. D supports
method overloading while Objective-C achieves something similar by using different selectors. For
these two reasons it is better to be able to specify the selectors manually in D, instead of trying to
infer it. This allows to have a more natural names for the methods in D. Example:
extern (Objective-C)
interface NSString
{
NSString initWith(in char*) @selector("initWithUTF8String:");
NSString initWith(NSString) @selector("initWithString:");
}

Here the method initWith is overloaded with two versions, one accepting in char*, the
other one NSString. These two methods are mapped to two different Objective-C selectors,
initWithUTF8String: and initWithString:.
The attribute is defined in druntime in core.attribute and aliased in object, meaning it will
be implicitly imported. The attribute is only defined when the version identifier D_ObjectiveC is
enabled.

Compiler Checks
The compiler performs the following checks to enforce the correct usage of the @selector attribue:

• The attribue can only be attached to methods with Objective-C linkage

• The attribue can only be attached once to a method
• The attribue cannot be attached to a template method
• The number of colons in the selector needs to match the number of parameters the method
is declared with

If any of the checks fail, a compile error will occur.

34.4 The D_ObjectiveC Version Identifier

The D_ObjectiveC version identifier is a predefined version identifier. It is enabled if Objective-C
support is available for the target.
34.5. OBJECTIVE-C LINKAGE 501

34.5 Objective-C Linkage

Objective-C linkage is achieved by attaching the extern (Objective-C) attribute to an interface.
Example:
extern (Objective-C)
interface NSObject
{
NSObject init() @selector("init");
}

All methods inside an interface declared as extern (Objective-C) will get implicit Objective-C
linkage.
The linkage is recognized on all platforms but will issue a compile error if it is used on a platform
where Objective-C support is not available. This allows to easily hide Objective-C declarations from
platforms where it is not available using the version statement, without resorting to string mixins
or other workarounds.

34.6 Memory Management

The preferred way to do memory management in Objective-C is to use Automatic Reference Count-
ing, ARC. This is not supported in D, therefore manual memory management is required to be used
instead. This is achieved by calling release on an Objective-C instance, like in the old days of
Objective-C.

34.7 Frameworks
Most Objective-C code is bundled in something called a "Framework". This is basically a regular
directory, with the .framework extension and a specific directory layout. A framework contains a
dynamic library, all public header files and any resources (images, sounds and so on) required by
the framework.
These directories are recognized by some tools, like the Objective-C compiler and linker, to be
frameworks. To link with a framework from DMD, use the following flags:
-L-framework -L<Framework>

Where <Framework> is the name of the framework to link with, without the .framework exten-
sion. The two -L flags are required because the linker expects a space between the -framework flag
and the name of the framework. DMD cannot handle this and will instead interpet the name of the
framework as a separate flag.
502 CHAPTER 34. INTERFACING TO OBJECTIVE-C

Framework Paths
Using the above flag, the linker will search in the standard framework paths. The standard search
paths for frameworks are:

• /System/Library/Frameworks
• /Library/Frameworks

The following flag from DMD can be used to add a new path in which to search for frameworks:
-L-F<framework_path>
For more information see the reference documentation and the ld man page.

34.8 Full Usage Example

Since the only parts of Objective-C that is currently supported is calling instance methods, this
example demonstrates how the Objective-C runtime can be used to achieve a running example.
This example will create an Objective-C string, NSString, and log the message using NSLog to
stderr.
extern (Objective-C)
interface Class
{
NSString alloc() @selector("alloc");
}
This interface is used to emulate the Class type available in the Objective-C runtime. The
instance method alloc will be used to emulate a class method in NSObject, alloc.
extern (Objective-C)
interface NSString
{
NSString initWithUTF8String(in char* str) @selector("initWithUTF8String:");
void release() @selector("release");
}
This is a simplified declaration of the NSString class. The initWithUTF8String: method will
be used to convert a C string in UTF-8 to an Objective-C string, NSString. The release method
is used to release an deallocate the string. Since D doesn’t support ARC it’s needed to manually
release Objective-C instances.
extern (C) Class objc_lookUpClass(in char* name)
34.8. FULL USAGE EXAMPLE 503

The objc_lookUpClass function is used to get the class definition of the class with the given
name.
extern (C) void NSLog(NSString, ...);
This NSLog function prints a message to the System Log facility, i.e. to stderr and Console.
auto cls = objc_lookUpClass("NSString");
Get the class definition of NSString.
auto str = cls.alloc();
Allocate an instance of the class, NSString.
str = str.initWithUTF8String("Hello␣World!")
Initialize the Objective-C string using a C string.
NSLog(str);
Log the string to stderr, this will print something like this in the terminal:
2015-07-18 13:14:27.978 main[11045:2934950] Hello World!

str.release();
Release and deallocate the string.
All steps combined look like this:
module main;

extern (Objective-C)
interface Class
{
NSString alloc() @selector("alloc");
}

extern (Objective-C)
interface NSString
{
NSString initWithUTF8String(in char* str) @selector("initWithUTF8String:");
void release() @selector("release");
}

extern (C) void NSLog(NSString, ...);

extern (C) Class objc_lookUpClass(in char* name);
504 CHAPTER 34. INTERFACING TO OBJECTIVE-C

void main()
{
auto cls = objc_lookUpClass("NSString");
auto str = cls.alloc().initWithUTF8String("Hello␣World!");
NSLog(str);
str.release();
}
When compiling the application remember to link with the required libraries, in this case the
Foundation framework. Example:
dmd -L-framework -LFoundation main.d
Chapter 35

Portability Guide

It’s good software engineering practice to minimize gratuitous portability problems in the code.
Techniques to minimize potential portability problems are:

• The integral and floating type sizes should be considered as minimums. Algorithms should
be designed to continue to work properly if the type size increases.
• Floating point computations can be carried out at a higher precision than the size of the
floating point variable can hold. Floating point algorithms should continue to work properly
if precision is arbitrarily increased.
• Avoid depending on the order of side effects in a computation that may get reordered by the
compiler. For example:
a + b + c
can be evaluated as (a + b) + c, a + (b + c), (a + c) + b, (c + b) + a, etc. Parentheses
control operator precedence, parentheses do not control order of evaluation.
If the operands of an associative operator + or * are floating point values, the expression is
not reordered.
• Avoid dependence on byte order; i.e. whether the CPU is big-endian or little-endian.
• Avoid dependence on the size of a pointer or reference being the same size as a particular
integral type.
• If size dependencies are inevitable, put a static assert in the code to verify it:
static assert(int.sizeof == (int*).sizeof);

35.1 32 to 64 Bit Portability

64 bit processors and operating systems are here. With that in mind:

505
506 CHAPTER 35. PORTABILITY GUIDE

• Integral types will remain the same sizes between 32 and 64 bit code.
• Pointers and object references will increase in size from 4 bytes to 8 bytes going from 32 to
64 bit code.
• Use size_t as an alias for an unsigned integral type that can span the address space. Array
indices should be of type size_t.
• Use ptrdiff_t as an alias for a signed integral type that can span the address space. A type
representing the difference between two pointers should be of type ptrdiff_t.
• The .length, .size, .sizeof, .offsetof and .alignof properties will be of type size_t.

35.2 Endianness
Endianness refers to the order in which multibyte types are stored. The two main orders are big
endian and little endian. The compiler predefines the version identifier BigEndian or LittleEndian
depending on the order of the target system. The x86 systems are all little endian.
The times when endianness matters are:

• When reading data from an external source (like a file) written in a different endian format.
• When reading or writing individual bytes of a multibyte type like longs or doubles.

35.3 OS Specific Code

System specific code is handled by isolating the differences into separate modules. At compile time,
the correct system specific module is imported.
Minor differences can be handled by constant defined in a system specific import, and then using
that constant in an IfStatement or StaticIfStatement.
Chapter 36

Named Character Entities

NamedCharacterEntity:
& Identifier ;

D supports the full list of named character entities from HTML 5. However, dmd does not yet
support named entities which contain multiple code points. Below is a partial list of the named
character entities. See the HTML 5 Spec for the full list.
Note: Not all will display properly in the Symbol column in all browsers.

Table 36.1: Named Character Entities

Name Value Symbol
quot 34 "
amp 38 &
lt 60 <
gt 62 >
OElig 338 Œ
oelig 339 œ
Scaron 352 Š
scaron 353 š
Yuml 376 ÿ
circ 710 ^
tilde 732 ~
ensp 8194
emsp 8195
thinsp 8201
↩
507
508 CHAPTER 36. NAMED CHARACTER ENTITIES

(continued)
Name Value Symbol
zwnj 8204
zwj 8205
lrm 8206
rlm 8207
ndash 8211 –
mdash 8212 —
lsquo 8216 ‘
rsquo 8217 ’
sbquo 8218
ldquo 8220 “
rdquo 8221 ”
bdquo 8222 "
dagger 8224 †
Dagger 8225 ‡
permil 8240 ‰
lsaquo 8249 ‹
rsaquo 8250 ›
euro 8364 €

Table 36.2: Latin-1 (ISO-8859-1) Entities

Name Value Symbol

nbsp 160
iexcl 161 ¡
cent 162 ¢
pound 163 £
curren 164 ¤
yen 165 ¥
brvbar 166 ¦
sect 167 §
uml 168 ¨
copy 169 ©
ordf 170 ª
laquo 171 «
not 172 ¬
shy 173
↩
 509

(continued)
Name Value Symbol
reg 174 ®
macr 175 ¯
deg 176 °
plusmn 177 ±
sup2 178 ²
sup3 179 ³
acute 180 ´
micro 181 µ
para 182 ¶
middot 183 ·
cedil 184 ¸
sup1 185 ¹
ordm 186 º
raquo 187 »
frac14 188 ¼
frac12 189 ½
frac34 190 ¾
iquest 191 ¿
Agrave 192 À
Aacute 193 Á
Acirc 194 Â
Atilde 195 Ã
Auml 196 Ä
Aring 197 Å
AElig 198 Æ
Ccedil 199 Ç
Egrave 200 È
Eacute 201 É
Ecirc 202 Ê
Euml 203 Ë
Igrave 204 Ì
Iacute 205 Í
Icirc 206 Î
Iuml 207 Ï
ETH 208 Ð
Ntilde 209 Ñ
↩
510 CHAPTER 36. NAMED CHARACTER ENTITIES

(continued)
Name Value Symbol
Ograve 210 Ò
Oacute 211 Ó
Ocirc 212 Ô
Otilde 213 Õ
Ouml 214 Ö
times 215 ×
Oslash 216 Ø
Ugrave 217 Ù
Uacute 218 Ú
Ucirc 219 Û
Uuml 220 Ü
Yacute 221 Ý
THORN 222 Þ
szlig 223 ß
agrave 224 à
aacute 225 á
acirc 226 â
atilde 227 ã
auml 228 ä
aring 229 å
aelig 230 æ
ccedil 231 ç
egrave 232 è
eacute 233 é
ecirc 234 ê
euml 235 ë
igrave 236 ì
iacute 237 í
icirc 238 î
iuml 239 ï
eth 240 ð
ntilde 241 ñ
ograve 242 ò
oacute 243 ó
ocirc 244 ô
otilde 245 õ
↩
 511

(continued)
Name Value Symbol
ouml 246 ö
divide 247 ÷
oslash 248 ø
ugrave 249 ù
uacute 250 ú
ucirc 251 û
uuml 252 ü
yacute 253 ý
thorn 254 þ
yuml 255 ÿ

Table 36.3: Symbols and Greek letter entities

Name Value Symbol

fnof 402 f
Alpha 913 A
Beta 914 B
Gamma 915 Γ
Delta 916 ∆
Epsilon 917 E
Zeta 918 Z
Eta 919 H
Theta 920 Θ
Iota 921 I
Kappa 922 K
Lambda 923 Λ
Mu 924 M
Nu 925 N
Xi 926 Ξ
Omicron 927 O
Pi 928 Π
Rho 929 P
Sigma 931 Σ
Tau 932 T
Upsilon 933 Υ
Phi 934 Φ
↩
512 CHAPTER 36. NAMED CHARACTER ENTITIES

(continued)
Name Value Symbol
Chi 935 X
Psi 936 Ψ
Omega 937 Ω
alpha 945 α
beta 946 β
gamma 947 γ
delta 948 δ
epsilon 949 
zeta 950 ζ
eta 951 η
theta 952 θ
iota 953 ι
kappa 954 κ
lambda 955 λ
mu 956 µ
nu 957 ν
xi 958 ξ
omicron 959 o
pi 960 π
rho 961 ρ
sigmaf 962 ς
sigma 963 σ
tau 964 τ
upsilon 965 υ
phi 966 φ
chi 967 χ
psi 968 ψ
omega 969 ω
thetasym 977 ϑ
upsih 978 Υ
piv 982 $
bull 8226 •
hellip 8230 ...
prime 8242 ′
Prime 8243 ′′
oline 8254
↩
 513

(continued)
Name Value Symbol
frasl 8260 /
weierp 8472 ℘
image 8465 I
real 8476 R
trade 8482 ™
alefsym 8501 ℵ
larr 8592 ←
uarr 8593 ↑
rarr 8594 →
darr 8595 ↓
harr 8596 ↔
crarr 8629 ↩
lArr 8656 ⇐
uArr 8657 ⇑
rArr 8658 ⇒
dArr 8659 ⇓
hArr 8660 ⇔
forall 8704 ∀
part 8706 ∂
exist 8707 ∃
empty 8709 ∅
nabla 8711 ∇
isin 8712 ∈
notin 8713 ∉
ni 8715 ∋
prod 8719 ∏
sum 8721 ∑
minus 8722 -
lowast 8727 ∗
√
radic 8730
prop 8733 ∝
infin 8734 ∝
ang 8736 ∠
and 8743 ∧
or 8744 ∨
cap 8745 ∩
↩
514 CHAPTER 36. NAMED CHARACTER ENTITIES

(continued)
Name Value Symbol
cup 8746 ∪
int 8747 ∫
there4 8756 ∴
sim 8764 ∼
cong 8773 ≅
asymp 8776 ≍
ne 8800 ≠
equiv 8801 ≡
le 8804 ≤
ge 8805 ≥
sub 8834 ⊂
sup 8835 ⊃
nsub 8836 ⊂/
sube 8838 ⊆
supe 8839 ⊇
oplus 8853 ⊕
otimes 8855 ⊗
perp 8869 ⊥
sdot 8901 ⋅
lceil 8968 ⌈
rceil 8969 ⌉
lfloor 8970 ⌊
rfloor 8971 ⌋
loz 9674 ◇
spades 9824 ♠
clubs 9827 ♣
hearts 9829 ♡
diams 9830 ♢
lang 10216 ⟨
rang 10217 ⟩
Chapter 37

Memory Safety

Memory Safety for a program is defined as it being impossible for the program to corrupt memory.
Therefore, the safe subset of D consists only of programming language features that are guaranteed
to never result in memory corruption. See this article for a rationale.
Memory-safe code cannot use certain language features, such as:

• Casts that break the type system.

• Modification of pointer values.
• Taking the address of a local variable or function parameter.

Usage
Memory safety can be enabled on a per-function basis using the @safe attribute. This can be
inferred when the compiler has the function body available. The @trusted attribute can be used
when a function has a safe interface, but uses unsafe code internally. These functions can be called
from @safe code.
Array bounds checks are necessary to enforce memory safety, so these are enabled (by default)
for @safe code even in -release mode.

Limitations
Memory safety does not imply that code is portable, uses only sound programming practices, is free
of byte order dependencies, or other bugs. It is focussed only on eliminating memory corruption
possibilities.

515
Chapter 38

Application Binary Interface

A D implementation that conforms to the D ABI (Application Binary Interface) will be able to
generate libraries, DLL’s, etc., that can interoperate with D binaries built by other implementations.

C ABI

The C ABI referred to in this specification means the C Application Binary Interface of the target
system. C and D code should be freely linkable together, in particular, D code shall have access to
the entire C ABI runtime library.

Endianness

The endianness (byte order) of the layout of the data will conform to the endianness of the target
machine. The Intel x86 CPUs are little endian meaning that the value 0x0A0B0C0D is stored in
memory as: 0D 0C 0B 0A.

517
518 CHAPTER 38. APPLICATION BINARY INTERFACE

Basic Types
bool 8 bit byte with the values 0 for false and 1 for true
byte 8 bit signed value
ubyte 8 bit unsigned value
short 16 bit signed value
ushort 16 bit unsigned value
int 32 bit signed value
uint 32 bit unsigned value
long 64 bit signed value
ulong 64 bit unsigned value
cent 128 bit signed value
ucent 128 bit unsigned value
float 32 bit IEEE 754 floating point value
double 64 bit IEEE 754 floating point value
real implementation defined floating point value, for x86 it is 80 bit IEEE 754 extended real

Delegates
Delegates are fat pointers with two parts:

Delegate Layout
offset property contents
0 .ptr context pointer
ptrsize .funcptr pointer to function

The context pointer can be a class this reference, a struct this pointer, a pointer to a closure
(nested functions) or a pointer to an enclosing function’s stack frame (nested functions).

Structs
Conforms to the target’s C ABI struct layout.

Classes
An object consists of:
 519

Class Object Layout

size property contents
ptrsize .__vptr pointer to vtable
ptrsize .__monitor monitor
... ... super’s non-static fields and super’s interface vptrs, from least to most
derived
... named fields non-static fields
ptrsize... vptr’s for any interfaces implemented by this class in left to right, most to
least derived, order

The vtable consists of:

Virtual Function Pointer Table Layout

size contents
ptrsize pointer to instance of TypeInfo
ptrsize... pointers to virtual member functions

Casting a class object to an interface consists of adding the offset of the interface’s corresponding
vptr to the address of the base of the object. Casting an interface ptr back to the class type it
came from involves getting the correct offset to subtract from it from the object.Interface entry at
vtbl[0]. Adjustor thunks are created and pointers to them stored in the method entries in the vtbl[]
in order to set the this pointer to the start of the object instance corresponding to the implementing
method.
An adjustor thunk looks like:
ADD EAX,offset
JMP method
The leftmost side of the inheritance graph of the interfaces all share their vptrs, this is the single
inheritance model. Every time the inheritance graph forks (for multiple inheritance) a new vptr is
created and stored in the class’ instance. Every time a virtual method is overridden, a new vtbl[]
must be created with the updated method pointers in it.
The class definition:
class XXXX
{
....
};
Generates the following:

• An instance of Class called ClassXXXX.

520 CHAPTER 38. APPLICATION BINARY INTERFACE

• A type called StaticClassXXXX which defines all the static members.

• An instance of StaticClassXXXX called StaticXXXX for the static members.

Interfaces
An interface is a pointer to a pointer to a vtbl[]. The vtbl[0] entry is a pointer to the corresponding
instance of the object.Interface class. The rest of the vtbl[1..$] entries are pointers to the virtual
functions implemented by that interface, in the order that they were declared.
A COM interface differs from a regular interface in that there is no object.Interface entry in
vtbl[0]; the entries vtbl[0..$] are all the virtual function pointers, in the order that they were
declared. This matches the COM object layout used by Windows.
A C++ interface differs from a regular interface in that it matches the layout of a C++ class
using single inheritance on the target machine.

Arrays
A dynamic array consists of:

Dynamic Array Layout

offset property contents
0 .length array dimension
size_t .ptr pointer to array data

A dynamic array is declared as:

type[] array;
whereas a static array is declared as:
type[dimension] array;
Thus, a static array always has the dimension statically available as part of the type, and so it
is implemented like in C. Static array’s and Dynamic arrays can be easily converted back and forth
to each other.

Associative Arrays
Associative arrays consist of a pointer to an opaque, implementation defined type.
The current implementation is contained in and defined by rt/aaA.d.

Reference Types
D has reference types, but they are implicit. For example, classes are always referred to by reference;
this means that class instances can never reside on the stack or be passed as function parameters.
 521

Name Mangling
D accomplishes typesafe linking by mangling a D identifier to include scope and type information.

MangledName:
_D QualifiedName Type
_D QualifiedName M Type

QualifiedName:
SymbolName
SymbolName QualifiedName

SymbolName:
LName
TemplateInstanceName

The M means that the symbol is a function that requires a this pointer.
Template Instance Names have the types and values of its parameters encoded into it:

TemplateInstanceName:
Number __T LName TemplateArgs Z

TemplateArgs:
TemplateArg
TemplateArg TemplateArgs

TemplateArg:
TemplateArgX
H TemplateArgX

TemplateArgX:
T Type
V Type Value
S LName

Value:
n
Number
i Number
N Number
522 CHAPTER 38. APPLICATION BINARY INTERFACE

e HexFloat
c HexFloat c HexFloat
CharWidth Number _ HexDigits
A Number Value...
S Number Value...

HexFloat:
NAN
INF
NINF
N HexDigits P Exponent
HexDigits P Exponent

Exponent:
N Number
Number

HexDigits:
HexDigit
HexDigit HexDigits

HexDigit:
Digit
A
B
C
D
E
F

CharWidth:
a
w
d

n is for null arguments.

Number is for positive numeric literals (including character literals).

N Number is for negative numeric literals.

 523

e HexFloat is for real and imaginary floating point literals.

c HexFloat c HexFloat is for complex floating point literals.

CharWidth Number _ HexDigits CharWidth is whether the characters are 1 byte (a), 2 bytes
(w) or 4 bytes (d) in size. Number is the number of characters in the string. The HexDigits
are the hex data for the string.

A Number Value... An array or asssociative array literal. Number is the length of the array.
Value is repeated Number times for a normal array, and 2 * Number times for an associative
array.

S Number Value... A struct literal. Value is repeated Number times.

Name:
Namestart
Namestart Namechars

Namestart:
_
Alpha

Namechar:
Namestart
Digit

Namechars:
Namechar
Namechar Namechars

A Name is a standard D identifier.

LName:
Number Name

Number:
Digit
Digit Number

Digit:
0
524 CHAPTER 38. APPLICATION BINARY INTERFACE

1
2
3
4
5
6
7
8
9

An LName is a name preceded by a Number giving the number of characters in the Name.

Type Mangling
Types are mangled using a simple linear scheme:

Type:
TypeModifiers opt TypeX

TypeX:
TypeArray
TypeStaticArray
TypeAssocArray
TypePointer
TypeFunction
TypeIdent
TypeClass
TypeStruct
TypeEnum
TypeTypedef
TypeDelegate
TypeVoid
TypeByte
TypeUbyte
TypeShort
TypeUshort
TypeInt
TypeUint
TypeLong
 525

TypeUlong
TypeFloat
TypeDouble
TypeReal
TypeIfloat
TypeIdouble
TypeIreal
TypeCfloat
TypeCdouble
TypeCreal
TypeBool
TypeChar
TypeWchar
TypeDchar
TypeNull
TypeTuple
TypeVector
Internal

TypeModifiers
Const
Wild
Wild Const
Shared
Shared Const
Shared Wild
Shared Wild Const
Immutable

Shared:
O

Const:
x

Immutable:
y

Wild:
Ng
526 CHAPTER 38. APPLICATION BINARY INTERFACE

TypeArray:
A Type

TypeStaticArray:
G Number Type

TypeAssocArray:
H Type Type

TypePointer:
P Type

TypeVector:
Nh Type

TypeFunction:
CallConvention FuncAttrs Parameters ParamClose Type

CallConvention:
F // D
U // C
W // Windows
V // Pascal
R // C++

FuncAttrs:
FuncAttr
FuncAttr FuncAttrs

FuncAttr:
empty
FuncAttrPure
FuncAttrNothrow
FuncAttrProperty
FuncAttrRef
FuncAttrTrusted
FuncAttrSafe
FuncAttrNogc
 527

FuncAttrPure:
Na

FuncAttrNothrow:
Nb

FuncAttrRef:
Nc

FuncAttrProperty:
Nd

FuncAttrTrusted:
Ne

FuncAttrSafe:
Nf

FuncAttrNogc:
Ni

Parameters:
Parameter
Parameter Parameters

Parameter:
Parameter2
M Parameter2 // scope

Parameter2:
Type
J Type // out
K Type // ref
L Type // lazy

ParamClose
X // variadic T t...) style
Y // variadic T t,...) style
Z // not variadic
528 CHAPTER 38. APPLICATION BINARY INTERFACE

TypeIdent:
I QualifiedName

TypeClass:
C QualifiedName

TypeStruct:
S QualifiedName

TypeEnum:
E QualifiedName

TypeTypedef:
T QualifiedName

TypeDelegate:
D TypeModifiers opt TypeFunction

TypeVoid:
v

TypeByte:
g

TypeUbyte:
h

TypeShort:
s

TypeUshort:
t

TypeInt:
i

TypeUint:
k

TypeLong:
 529

TypeUlong:
m

TypeFloat:
f

TypeDouble:
d

TypeReal:
e

TypeIfloat:
o

TypeIdouble:
p

TypeIreal:
j

TypeCfloat:
q

TypeCdouble:
r

TypeCreal:
c

TypeBool:
b

TypeChar:
a

TypeWchar:
u
530 CHAPTER 38. APPLICATION BINARY INTERFACE

TypeDchar:
w

TypeNull:
n

TypeTuple:
B Number Parameters

Internal:
Z

Function Calling Conventions

The extern (C) and extern (D) calling convention matches the C calling convention used by
the supported C compiler on the host system. Except that the extern (D) calling convention for
Windows x86 is described here.

Register Conventions
• EAX, ECX, EDX are scratch registers and can be destroyed by a function.
• EBX, ESI, EDI, EBP must be preserved across function calls.
• EFLAGS is assumed destroyed across function calls, except for the direction flag which must
be forward.
• The FPU stack must be empty when calling a function.
• The FPU control word must be preserved across function calls.
• Floating point return values are returned on the FPU stack. These must be cleaned off by
the caller, even if they are not used.

Return Value
• The types bool, byte, ubyte, short, ushort, int, uint, pointer, Object, and interfaces are
returned in EAX.
• long and ulong are returned in EDX,EAX, where EDX gets the most significant half.
• float, double, real, ifloat, idouble, ireal are returned in ST0.
• cfloat, cdouble, creal are returned in ST1,ST0 where ST1 is the real part and ST0 is the
imaginary part.
• Dynamic arrays are returned with the pointer in EDX and the length in EAX.
 531

• Associative arrays are returned in EAX.

• References are returned as pointers in EAX.
• Delegates are returned with the pointer to the function in EDX and the context pointer in
EAX.
• 1, 2 and 4 byte structs and static arrays are returned in EAX.
• 8 byte structs and static arrays are returned in EDX,EAX, where EDX gets the most significant
half.
• For other sized structs and static arrays, the return value is stored through a hidden pointer
passed as an argument to the function.
• Constructors return the this pointer in EAX.

Parameters
The parameters to the non-variadic function:
foo(a1, a2, ..., an);
are passed as follows:
a1
a2
...
an
hidden
this
where hidden is present if needed to return a struct value, and this is present if needed as the
this pointer for a member function or the context pointer for a nested function.
The last parameter is passed in EAX rather than being pushed on the stack if the following
conditions are met:

• It fits in EAX.
• It is not a 3 byte struct.
• It is not a floating point type.

Parameters are always pushed as multiples of 4 bytes, rounding upwards, so the stack is always
aligned on 4 byte boundaries. They are pushed most significant first. out and ref are passed as
pointers. Static arrays are passed as pointers to their first element. On Windows, a real is pushed
as a 10 byte quantity, a creal is pushed as a 20 byte quantity. On Linux, a real is pushed as a 12
byte quantity, a creal is pushed as two 12 byte quantities. The extra two bytes of pad occupy the
‘most significant’ position.
The callee cleans the stack.
The parameters to the variadic function:
532 CHAPTER 38. APPLICATION BINARY INTERFACE

void foo(int p1, int p2, int[] p3...)

foo(a1, a2, ..., an);

are passed as follows:

p1
p2
a3
hidden
this
The variadic part is converted to a dynamic array and the rest is the same as for non-variadic
functions.
The parameters to the variadic function:

void foo(int p1, int p2, ...)

foo(a1, a2, a3, ..., an);

are passed as follows:

an
...
a3
a2
a1
_arguments
hidden
this
The caller is expected to clean the stack. _argptr is not passed, it is computed by the callee.

Exception Handling
Windows

Conforms to the Microsoft Windows Structured Exception Handling conventions.

Linux, FreeBSD and OS X

Uses static address range/handler tables. It is not compatible with the ELF/Mach-O exception
handling tables. The stack is walked assuming it uses the EBP/RBP stack frame convention.
The EBP/RBP convention must be used for every function that has an associated EH (Exception
Handler) table.
For each function that has exception handlers, an EH table entry is generated.
 533

EH Table Entry
field description
void* pointer to start of function
DHandlerTable* pointer to corresponding EH data
uint size in bytes of the function

The EH table entries are placed into the following special segments, which are concatenated by
the linker.

EH Table Segment
Operating System Segment Name
Windows FI
Linux .deh_eh
FreeBSD .deh_eh
OS X __deh_eh, __DATA

The rest of the EH data can be placed anywhere, it is immutable.

DHandlerTable
field description
void* pointer to start of function
uint offset of ESP/RSP from EBP/RBP
uint offset from start of function to return code
uint number of entries in DHandlerInfo[]
DHandlerInfo[] array of handler information

DHandlerInfo
field description
uint offset from function address to start of guarded section
uint offset of end of guarded section
int previous table index
uint if != 0 offset to DCatchInfo data from start of table
void* if not null, pointer to finally code to execute

DCatchInfo
field description
uint number of entries in DCatchBlock[]
DCatchBlock[] array of catch information
534 CHAPTER 38. APPLICATION BINARY INTERFACE

DCatchBlock
field description
ClassInfo catch type
uint offset from EBP/RBP to catch variable
void*, catch handler code

Garbage Collection
The interface to this is found in phobos/internal/gc.

Runtime Helper Functions

These are found in phobos/internal.

Module Initialization and Termination

All the static constructors for a module are aggregated into a single function, and a pointer to that
function is inserted into the ctor member of the ModuleInfo instance for that module.
All the static denstructors for a module are aggregated into a single function, and a pointer to
that function is inserted into the dtor member of the ModuleInfo instance for that module.

Unit Testing
All the unit tests for a module are aggregated into a single function, and a pointer to that function
is inserted into the unitTest member of the ModuleInfo instance for that module.

38.1 Symbolic Debugging

D has types that are not represented in existing C or C++ debuggers. These are dynamic arrays,
associative arrays, and delegates. Representing these types as structs causes problems because
function calling conventions for structs are often different than that for these types, which causes
C/C++ debuggers to misrepresent things. For these debuggers, they are represented as a C type
which does match the calling conventions for the type. The dmd compiler will generate only C
symbolic type info with the -gc compiler switch.
38.1. SYMBOLIC DEBUGGING 535

Types for C Debuggers

D type C representation
dynamic array unsigned long long
associative array void*
delegate long long
dchar unsigned long

For debuggers that can be modified to accept new types, the following extensions help them
fully support the types.

Codeview Debugger Extensions

The D dchar type is represented by the special primitive type 0x78.
D makes use of the Codeview OEM generic type record indicated by LF_OEM (0x0015). The
format is:

Codeview OEM Extensions for D

field size 2 2 2 2 2 2
D Type Leaf Index OEM Identifier recOEM num indices type index type index
dynamic array LF_OEM OEM 1 2 @index @element
associative array LF_OEM OEM 2 2 @key @element
delegate LF_OEM OEM 3 2 @this @function

Where:

OEM 0x42
index type index of array index
key type index of key
element type index of array element
this type index of context pointer
function type index of function

These extensions can be pretty-printed by obj2asm.

The Ddbg debugger supports them.
Chapter 39

Vector Extensions

Modern CPUs often support specialized vector types and vector operations, sometimes called "media
instructions". Vector types are a fixed array of floating or integer types, and vector operations
operate simultaneously on them, thus achieving great speed-ups.
When the compiler takes advantage of these instructions with standard D code to speed up loops
over arithmetic data, this is called auto-vectorization. Auto-vectorization, however, has had only
limited success and has not been able to really take advantage of the richness (and often quirkiness)
of the native vector instructions.
D has the array operation notation, such as:
int[] a,b;
...
a[] += b[];
which can be vectorized by the compiler, but again success is limited for the same reason auto-
vectorization is.
The difficulties with trying to use vector instructions on regular arrays are:

1. The vector types have stringent alignment requirements that are not and cannot be met by
conventional arrays.
2. C ABI’s often have vector extensions and have special name mangling for them, call/return
conventions, and symbolic debug support.
3. The only way to get at the full vector instruction set would be to use inline assembler - but the
compiler cannot do register allocation across inline assembler blocks (or other optimizations),
leading to poor code performance.
4. Interleaving conventional array code with vector operations on the same data can unwittingly
lead to extremely poor runtime performance.

These issues are cleared up by using special vector types.

537
538 CHAPTER 39. VECTOR EXTENSIONS

39.1 core.simd
Vector types and operations are introduced to D code by importing core.simd:
import core.simd;

These types and operations will be the ones defined for the architecture the compiler is targeting.
If a particular CPU family has varying support for vector types, an additional runtime check may
be necessary. The compiler does not emit runtime checks; those must be done by the programmer.
Depending on the architecture, compiler flags may be required to activate support for SIMD
types.
The types defined will all follow the naming convention:

typeNN

where type is the vector element type and NN is the number of those elements in the vector type.
The type names will not be keywords.

Properties
Vector types have the property:

Vector Type Properties

Property Description
.array Returns static array representation

All the properties of the static array representation also work.

Conversions
Vector types of the same size can be implicitly converted among each other. Vector types can be
cast to the static array representation.
Integers and floating point values can be implicitly converted to their vector equivalents:
int4 v = 7;
v = 3 + v; // add 3 to each element in v
39.2. X86 AND X86_64 VECTOR EXTENSION IMPLEMENTATION 539

Accessing Individual Vector Elements

They cannot be accessed directly, but can be when converted to an array type:
int4 v;
(cast(int*)&v)[3] = 2; // set 3rd element of the 4 int vector
(cast(int[4])v)[3] = 2; // set 3rd element of the 4 int vector
v.array[3] = 2; // set 3rd element of the 4 int vector
v.ptr[3] = 2; // set 3rd element of the 4 int vector

Conditional Compilation
If vector extensions are implemented, the version identifier D_SIMD is set.
Whether a type exists or not can be tested at compile time with an IsExpression:
static if (is(typeNN))
... yes, it is supported ...
else
... nope, use workaround ...
Whether a particular operation on a type is supported can be tested at compile time with:
float4 a,b;
static if (__traits(compiles, a+b))
... yes, it is supported ...
else
... nope, use workaround ...
For runtime testing to see if certain vector instructions are available, see the functions in
core.cpuid.
A typical workaround would be to use array vector operations instead:
float4 a,b;
static if (__traits(compiles, a/b))
c = a / b;
else
c[] = a[] / b[];

39.2 X86 And X86_64 Vector Extension Implementation

The rest of this document describes the specific implementation of the vector types for the X86 and
X86_64 architectures.
540 CHAPTER 39. VECTOR EXTENSIONS

The vector extensions are currently implemented for the OS X 32 bit target, and all 64 bit
targets.
core.simd defines the following types:

Vector Types
Type Name Description gcc Equivalent
void16 16 bytes of untyped data no equivalent
byte16 16 byte’s signed char __attribute__((vector_size(16)))
ubyte16 16 ubyte’s unsigned char __attribute__((vector_size(16)))
short8 8 short’s short __attribute__((vector_size(16)))
ushort8 8 ushort’s ushort __attribute__((vector_size(16)))
int4 4 int’s int __attribute__((vector_size(16)))
uint4 4 uint’s unsigned __attribute__((vector_size(16)))
long2 2 long’s long __attribute__((vector_size(16)))
ulong2 2 ulong’s unsigned long __attribute__((vector_size(16)))
float4 4 float’s float __attribute__((vector_size(16)))
double2 2 double’s double __attribute__((vector_size(16)))
void32 32 bytes of untyped data no equivalent
byte32 32 byte’s signed char __attribute__((vector_size(32)))
ubyte32 32 ubyte’s unsigned char __attribute__((vector_size(32)))
short16 16 short’s short __attribute__((vector_size(32)))
ushort16 16 ushort’s ushort __attribute__((vector_size(32)))
int8 8 int’s int __attribute__((vector_size(32)))
uint8 8 uint’s unsigned __attribute__((vector_size(32)))
long4 4 long’s long __attribute__((vector_size(32)))
ulong4 4 ulong’s unsigned long __attribute__((vector_size(32)))
float8 8 float’s float __attribute__((vector_size(32)))
double4 4 double’s double __attribute__((vector_size(32)))

Note: for 32 bit gcc, it’s long long instead of long.

39.2. X86 AND X86_64 VECTOR EXTENSION IMPLEMENTATION 541

Supported 128-bit Vector Operators

Operator void16 byte16 ubyte16 short8 ushort8 int4 uint4 long2 ulong2 float4 double2
= × × × × × × × × × × ×
+ – × × × × × × × × × ×
- – × × × × × × × × × ×
* – – – × × – – – – × ×
/ – – – – – – – – – × ×
& – × × × × × × × × – –
| – × × × × × × × × – –
^ – × × × × × × × × – –
+= – × × × × × × × × × ×
-= – × × × × × × × × × ×
*= – – – × × – – – – × ×
/= – – – – – – – – – × ×
&= – × × × × × × × × – –
|= – × × × × × × × × – –
^= – × × × × × × × × – –
unary~ – × × × × × × × × – –
unary+ – × × × × × × × × × ×
unary- – × × × × × × × × × ×
542 CHAPTER 39. VECTOR EXTENSIONS

Supported 256-bit Vector Operators

Operator void32 byte32 ubyte32 short16 ushort16 int8 uint8 long4 ulong4 float8 double4
= × × × × × × × × × × ×
+ – × × × × × × × × × ×
- – × × × × × × × × × ×
* – – – – – – – – – × ×
/ – – – – – – – – – × ×
& – × × × × × × × × – –
| – × × × × × × × × – –
^ – × × × × × × × × – –
+= – × × × × × × × × × ×
-= – × × × × × × × × × ×
*= – – – – – – – – – × ×
/= – – – – – – – – – × ×
&= – × × × × × × × × – –
|= – × × × × × × × × – –
^= – × × × × × × × × – –
unary~ – × × × × × × × × – –
unary+ – × × × × × × × × × ×
unary- – × × × × × × × × × ×

Operators not listed are not supported at all.

Vector Operation Intrinsics

See core.simd for the supported intrinsics.