Programming in D – Tutorial and Reference
Ali Çehreli

Other D Resources


We have seen that variables represent concepts in programs. The interactions of these concepts are achieved by expressions that change the values of those variables:

    // Pay the bill
    totalPrice = calculateAmount(itemPrices);
    moneyInWallet -= totalPrice;
    moneyAtMerchant += totalPrice;

Modifying a variable is called mutating that variable. The concept of mutability is essential for most tasks. However, there are some cases where mutability is not suitable:

The concept of immutability helps with understanding parts of programs by guaranteeing that certain operations do not change certain variables. It also reduces the risk of certain types of program errors.

The immutability concept of D is represented by the const and immutable keywords. Although the two words themselves are close in meaning, their responsibilities in programs are different and they are sometimes incompatible.

Immutable variables

Both of the terms "immutable variable" and "constant variable" are nonsensical when the word "variable" is taken literally to mean something that changes. The word "variable" means any concept of a program which may be mutable of immutable.

There are three ways of defining variables that can never be mutated.

enum constants

We have seen earlier in the enum chapter that enum defines named constant values:

    enum fileName = "list.txt";

As long as their values can be determined at compile time, enum variables can be initialized by return values of functions as well:

int totalLines()
    return 42;

int totalColumns()
    return 7;

string name()
    return "list";

void main()
    enum fileName = name() ~ ".txt";
    enum totalSquares = totalLines() * totalColumns();

As expected, values of enum constants cannot be modified:

    ++totalSquares;    // ← compilation ERROR

Although it is a very effective way of representing immutable values, enum can only be used for compile-time values.

An enum constant is a manifest constant, meaning that the program is compiled as if it has been replaced by its value. As an example, let's consider the following enum definition and the two expressions that make use of it:

    enum i = 42;

The code above would be the same as replacing i with its value 42:


Although that replacement makes sense for simple types like int and makes no difference in the program, enum constants bring a hidden cost when they are used for arrays or associative arrays:

    enum a = [ 42, 100 ];

After replacing a with its value, the equivalent code that the compiler would be compiling is the following:

    writeln([ 42, 100 ]);    // an array is created at run time
    foo([ 42, 100 ]);        // another array is created at run time

The hidden cost here is that there would be two separate arrays created for the two expressions above. For that reason, it may make more sense to define arrays and associative arrays as immutable variables if they are going to be used more than once in the program.

immutable variables

Like enum, this keyword specifies that the value of a variable will never change. Its difference from enum is that the values of immutable variables can be calculated during the execution of the program.

The following program compares the uses of enum and immutable. The program waits for the user to guess a number that has been picked randomly. Since the random number cannot be determined at compile time, it cannot be defined as enum. Still, since the randomly picked value must never be changed after having being decided, it is suitable to specify that variable as immutable.

The program takes advantage of the read_int() function that has been defined in the previous chapter:

import std.stdio;
import std.random;

int read_int(string message)
    int result;
    write(message, "? ");
    readf(" %s", &result);
    return result;

void main()
    enum min = 1;
    enum max = 10;

    immutable number = uniform(min, max + 1);

    writefln("I am thinking of a number between %s and %s.",
             min, max);

    auto isCorrect = false;
    while (!isCorrect) {
        immutable guess = read_int("What is your guess");
        isCorrect = (guess == number);



Although it is not necessary to write the type fully as e.g. immutable(int), immutable normally takes the actual type within parentheses. The output of the following program demonstrates that the full names of the types of the three variables are in fact the same:

import std.stdio;

void main()
    immutable      inferredType = 0;
    immutable int  explicitType = 1;
    immutable(int) wholeType    = 2;


The actual name of the type includes immutable:


The type that is specified within the parentheses has significance. We will see this below when discussing the immutability of the whole slice vs. its elements.

const variables

This keyword has the same effect as immutable on variables. const variables cannot be modified:

    const half = total / 2;
    half = 10;    // ← compilation ERROR

I recommend that you prefer immutable over const when defining variables. The reason is that immutable variables can be passed to functions as their immutable parameters. We will see this below.

Immutable parameters

It is possible for functions to promise that they do not modify certain parameters that they take. The compiler guarantees that this promise is enforced. Before seeing how this is achieved, let's first see that functions can indeed modify the elements of slices that are passed as arguments to those function.

As you would remember from the Slices and Other Array Features chapter, slices do not own elements but provide access to them. There may be more than one slice at a given time that provide access to the same elements.

Although the examples in this section focus only on slices, this topic is applicable to associative arrays and classes as well because they too are reference types.

A slice that is passed as a function argument is not the slice that the function is called with. The argument is a copy of the actual slice:

import std.stdio;

void main()
    int[] slice = [ 10, 20, 30, 40 ];  // 1

void halve(int[] numbers)              // 2
    foreach (ref number; numbers) {
        number /= 2;

When program execution enters the halve() function, there are two slices that provide access to the same four elements:

  1. The slice named slice that is defined in main(), which is passed to halve() as its argument
  2. The slice named numbers that halve() receives as its argument, which provides access to the same elements as slice

Also due to the ref keyword in the foreach loop, the values of the original (and the only) elements get halved:

[5, 10, 15, 20]

It is useful for functions to be able to modify the elements of the slices that are passed as arguments. Some functions exist just for that purpose as has been seen in this example.

The compiler does not allow passing immutable variables as arguments to such functions, because it is impossible to modify an immutable variable:

    immutable int[] slice = [ 10, 20, 30, 40 ];
    halve(slice);    // ← compilation ERROR

The compilation error indicates that a variable of type immutable(int[]) cannot be used as an argument of type int[]:

Error: function deneme.halve (int[] numbers) is not callable
using argument types (immutable(int[]))
const parameters

It is important and natural that immutable variables be prevented from being passed to functions like halve(), which modify their arguments. However, it would be a limitation if they could not be passed to functions that do not modify their arguments in any way:

import std.stdio;

void main()
    immutable int[] slice = [ 10, 20, 30, 40 ];
    print(slice);    // ← compilation ERROR

void print(int[] slice)
    writefln("%s elements: ", slice.length);

    foreach (i, element; slice) {
        writefln("%s: %s", i, element);

It does not make sense above that a slice is prevented from being printed just because it is immutable. The proper way of dealing with this situation is const parameters.

The const keyword specifies that a variable would not be modified through that particular reference (e.g. a slice) of that variable. Specifying a parameter as const guarantees that the elements of the slice would not be modified inside the function. Once print() provides this guarantee, the program can now be compiled:

    print(slice);    // now compiles
// ...
void print(const int[] slice)

This guarantee allows passing both mutable and immutable variables as arguments:

    immutable int[] slice = [ 10, 20, 30, 40 ];
    print(slice);           // compiles

    int[] mutableSlice = [ 7, 8 ];
    print(mutableSlice);    // compiles

A parameter that is not modified in a function but is not specified as const reduces the usability of that function. Additionally, const parameters provide useful information to the programmer. Knowing that a variable will not be modified when passed to a function makes the code easier to understand. It also prevents potential errors because the compiler prevents modifications to const parameters:

void print(const int[] slice)
    slice[0] = 42;    // ← compilation ERROR

The programmer would either realize the mistake in the function or would rethink the design and perhaps remove the const specifier.

The fact that const parameters can accept both mutable and immutable variables has an interesting consequence. This is explained in the "Should a parameter be const or immutable?" section below.

immutable parameters

As we have seen above, both mutable and immutable variables can be passed to functions as their const parameters. In a way, const parameters are welcoming.

In contrast, immutable parameters bring a strong requirement: Only immutable variables can be passed to functions as their immutable parameters:

void func(immutable int[] slice)
    /* ... */

void main()
    immutable int[] immSlice = [ 1, 2 ];
              int[]    slice = [ 8, 9 ];

    func(immSlice);      // compiles
    func(slice);         // ← compilation ERROR

For that reason, the immutable specifier should be used only when this requirement is necessary. We have indeed been using the immutable specifier indirectly through certain string types. This will be covered below.

We have seen that the parameters that are specified as const or immutable promise not to modify the actual variable that is passed as an argument. This is relevant only for reference types because only then there is the actual variable to talk about the immutability of.

Reference types and value types will be covered in later chapters. Among the types that we have seen so far, only slices and associative arrays are reference types; the others are value types.

Should a parameter be const or immutable?

The two sections above may give the impression that being more flexible, const parameters should be preferred over immutable parameters. This is not always true.

const erases the information about whether the original variable is mutable or immutable. This information is hidden even from the compiler.

A consequence of this fact is that const parameters cannot be passed as arguments to functions that take immutable parameters. For example, foo() below cannot pass its const parameter to bar():

void main()
    /* The original variable is immutable */
    immutable int[] slice = [ 10, 20, 30, 40 ];

/* A function that takes its parameter as const, in order to
 * be more useful. */
void foo(const int[] slice)
    bar(slice);    // ← compilation ERROR

/* A function that takes its parameter as immutable for a
 * plausible reason. */
void bar(immutable int[] slice)
    /* ... */

bar() requires that the parameter is immutable. However, it is not known whether the original variable that foo()'s const parameter references is immutable or not.

Note: It is clear in the code above that the original variable in main() is immutable. However, the compiler compiles functions individually without regard to all of the places that function is called from. To the compiler, the slice parameter of foo() may be referring to a mutable variable or an immutable one.

A solution would be to call bar() with an immutable copy of the parameter:

void foo(const int[] slice)

Although that is a sensible solution, it does have the cost of copying, which would be wasteful in the case where the original variable has been immutable to begin with.

After this analysis, it should be clear that taking parameters always as const does not seem to be the best approach in every situation. After all, if foo()'s parameter has been defined as immutable, there would not be any need to copy it before calling bar():

void foo(immutable int[] slice) // This time immutable
    bar(slice);    // Copying is not needed anymore

Although the code compiles, defining the parameter as immutable has a similar cost: This time an immutable copy of the original variable is needed when calling foo(), if that variable were not immutable to begin with:


Templates can provide help. (We will see templates in later chapters.) Although I don't expect you to fully understand the following function at this point in the book, I will present it as a solution to this problem. The following function template foo() can be called both by mutable and by immutable variables. The parameter would be copied only if the original variable has been mutable; no copying would take place if it has been immutable:

import std.conv;
// ...

/* Because it is a template, foo() can be called by mutable
 * and immutable variables. */
void foo(T)(T[] slice)
    /* 'to()' does not make a copy if the original variable is
     * already immutable. */
    bar(to!(immutable T[])(slice));
Immutability of the slice versus the elements

We have seen above that the type of an immutable slice has been printed as immutable(int[]). As the parentheses after immutable indicate, it is the entire slice that is immutable. Such a slice cannot be modified in any way: elements may not be added or removed, their values may not be modified, and the slice may not start providing access to a different set of elements:

    immutable int[] immSlice = [ 1, 2 ];
    immSlice ~= 3;               // ← compilation ERROR
    immSlice[0] = 3;             // ← compilation ERROR
    immSlice.length = 1;         // ← compilation ERROR

    immutable int[] immOtherSlice = [ 10, 11 ];
    immSlice = immOtherSlice;    // ← compilation ERROR

Taking immutability to that extreme may not be suitable in every case. In most cases, what is important is the immutability of just the elements. Since a slice is just an access tool to elements, it should not matter to make changes to the slice itself as long as the elements are not modified.

To specify that only the elements are immutable, only the element type is written within parentheses. When the code is modified accordingly, now only the elements are immutable, not the slice itself:

    immutable(int)[] immSlice = [ 1, 2 ];
    immSlice ~= 3;               // can add elements
    immSlice[0] = 3;             // ← compilation ERROR
    immSlice.length = 1;         // can lose elements

    immutable int[] immOtherSlice = [ 10, 11 ];
    immSlice = immOtherSlice;    // can provide access to other elements

Although the two syntaxes are very similar, they have different meanings. To summarize:

    immutable int[]  a = [1]; /* Neither the elements nor the
                               * slice can be modified */

    immutable(int[]) b = [1]; /* The same meaning as above */

    immutable(int)[] c = [1]; /* The elements cannot be
                               * modified but the slice can be */

This distinction have been in effect in some of the programs that we have written so far. As you may remember, the three string aliases involve immutability:

Likewise, string literals are immutable as well:

According to these definitions, D strings are normally arrays of immutable characters.

.dup and .idup

There may be mismatches in immutability when strings are passed to functions as parameters. The .dup and .idup properties make copies of arrays with the desired immutability:

For example, a function that insists on the immutability of a parameter may have to be called with an immutable copy of a mutable string:

void foo(string s)
    // ...

void main()
    char[] salutation;
    foo(salutation);                // ← compilation ERROR
    foo(salutation.idup);           // ← this compiles
How to use