Programming in D – Tutorial and Reference
Ali Çehreli

Other D Resources

Immutability

Concepts are represented by the variables of a program. Interactions of concepts are commonly achieved by expressions that change the values of variables that represent those concepts. For example, the following code changes some variables that represent a purchase: 

    totalPrice = calculateAmount(itemPrices);
    moneyInWallet -= totalPrice;
    moneyAtMerchant += totalPrice;

Changing the value of a variable is called modifying or mutating that variable. Disallowing mutation of a variable is called immutability.

As mutation is essential for most tasks, deliberately disallowing it can be counter-intuitive but is a powerful and useful feature. The concept of immutability is based on experience gained by the programming community in general: Immutability helps with correctness and maintainability of programs. This idea is so powerful that some functional programming languages disallow mutation altogether.

Some benefits of immutability are the following:

Immutability is so common in programming in general and widely adopted by D programmers that the following curiosities are accepted as consequences:

Immutable variables

There are three ways of defining variables that cannot 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 with more complex expressions as well, including return values of functions: 

int totalLines() {
    return 42;
}

int totalColumns() {
    return 7;
}

string name() {
    return "list";
}

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

The D feature that enables such initialization is compile time function execution (CTFE), which we will see in a later chapter.

As expected, the 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 with compile-time values.

An enum constant is a manifest constant, meaning that the program is compiled as if every mention of that constant had 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;
    writeln(i);
    foo(i);

The code above is the exact equivalent of the one below, where every use of i is replaced with its value of 42: 

    writeln(42);
    foo(42);

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

    enum a = [ 42, 100 ];
    writeln(a);
    foo(a);

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 makes more sense to define arrays and associative arrays as immutable variables if they are going to be mentioned more than once in the program.

const variables

Like enum, this keyword specifies that the value of a variable will never change. Unlike enum, a const variable is an actual variable with a memory address and const variables are commonly initialized during the execution of the program.

The compiler does not allow mutating a const variable: 

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

The following program uses both enum and const. The program asks 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 an enum. Still, since the randomly picked value must never be changed after having been decided, it is suitable to specify that variable as const.

The program takes advantage of the readInt() function that was defined in the previous chapter: 

import std.stdio;
import std.random;

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

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

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

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

    auto isCorrect = false;
    while (!isCorrect) {
        const guess = readInt("What is your guess");
        isCorrect = (guess == number);
    }

    writeln("Correct!");
}

Observations:

Although it is not necessary to write the type fully, const normally takes the actual type within parentheses, e.g. const(int). 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() {
    const      inferredType = 0;
    const int  explicitType = 1;
    const(int) fullType     = 2;

    writeln(typeof(inferredType).stringof);
    writeln(typeof(explicitType).stringof);
    writeln(typeof(fullType).stringof);
}

The actual name of the type includes const: 

const(int)
const(int)
const(int)

The use of parentheses has significance, and specifies which parts of the type are immutable. We will see this below when discussing the immutability of an entire slice vs. its elements.

immutable variables

When defining variables the immutable keyword has the same effect as const. immutable variables cannot be modified: 

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

Unless other parts of the program require a variable to be immutable, immutable variables can either be defined as const or immutable. When a function requires specifically that a parameter must be immutable, then a variable corresponding to that parameter must be defined as immutable. We will see this below.

Parameters

As we will see in the next two chapters, functions can mutate their parameters. For example, they can mutate the elements of slices that are passed as arguments to those functions.

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 provides 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 slice variable. (Only the slice variable is copied, not the elements.) 

import std.stdio;

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

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 parameter
  2. The slice named numbers that halve() receives as its argument, which provides access to the same elements as slice

Since both slices refer to the same elements and that we use the ref keyword in the foreach loop, the values of the elements get halved: 

[5, 10, 15, 20]

It is indeed useful for functions to be able to modify the elements of the slices that are passed as arguments. As we have seen in this example, some functions exist just for that purpose.

The compiler does not allow passing const variables as arguments to such functions: 

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

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

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

It is important and natural that const variables be prevented from being passed to functions like halve() that modify their arguments. However, it would be a limitation if they could not be passed to functions that do not intend to modify them like the print() function below: 

import std.stdio;

void main() {
    const(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 const. The proper way of dealing with this situation is using const parameters. This is called making the function const-correct. (This is the self-fulfilling prophecy mentioned above that forces functions to observe immutability.)

The const keyword specifies that a variable is not modified through that particular reference (e.g. a slice) of that variable. Specifying a parameter as const guarantees that the elements of the slice are not 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 of non-mutation provides flexibility because it allows passing mutable, const, and immutable variables as arguments: 

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

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

    immutable int[] immSlice = [ 1, 2 ];
    print(immSlice);        // compiles

Conversely, failing to define a parameter as const when that parameter is not modified in the function reduces the applicability of that function. Such functions are not const-correct.

Another benefit of const parameters is providing useful information to the programmer: Knowing that a variable will not be modified when passed to a function makes the code easier to understand.

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

in parameters

As we will see in the next chapter, in implies const and is more useful with the ‑preview=in command line switch. For that reason, I recommend in parameters over const parameters.

immutable parameters

const parameters can be seen as welcoming because they accept mutable, const, and immutable variables as arguments.

In contrast, immutable parameters are selective because they bring a strong requirement: The argument must be immutable. While a const parameter communicates "I will not mutate", an immutable parameter adds "and you should not mutate either".

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 actually 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 the next chapter. 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?

Note: As in implies const, this section is about in as well.

The 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 of whether the original variable was mutable, const, 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, the intermediate function foo() below cannot pass its const parameter to bar() even though the actual variable that is passed through the functions is defined as immutable to begin with in main: 

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

/* 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 requires an immutable slice. */
void bar(immutable int[] slice) {
    // ...
}

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

Note: It is clear to an observer in the code above that the original variable in main() is immutable. However, the compiler compiles functions individually, without regard to every place that function is called from. To the compiler, the slice parameter of foo() may refer 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) {
    bar(slice.idup);
}

Although that would make the code compile, it does incur into the cost of copying the slice and its contents, which would be wasteful in the case where the original variable was immutable to begin with.

After this analysis, it should be clear that always declaring parameters as const is not the best approach in every situation. After all, if foo()'s parameter had been defined as immutable there would be no 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 was not immutable to begin with: 

    foo(mutableSlice.idup);

Templates can 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 with mutable, const, and immutable variables. The parameter would be copied only if the original variable was mutable; no copying would take place if it were immutable: 

import std.conv;
// ...

/* Because it is a template, foo() can be called with both 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));
}
Initialization

Disallowing mutations can be seen as a limitation when initial values of variables depend on non-trivial expressions. For example, the contents of the fruits array below depend on the value of addCitrus but the code fails to compile because the variable is const: 

    const fruits = [ "apple", "pear" ];

    if (addCitrus) {
        fruits ~= [ "orange" ];    // ← compilation ERROR
    }

Although making the variable mutable e.g. by defining it with auto would allow the code to compile, it is still possible to define it as const by moving the initialization code to a function: 

bool addCitrus;

string[] makeFruits() {
    auto result = [ "apple", "pear" ];

    if (addCitrus) {
        result ~= [ "orange" ];
    }

    return result;
}

void main() {
    const fruits = makeFruits();
}

Note how the local result array is mutable but the fruits is still const (presumably as desired by the programmer). When it is impossible or cumbersome to move the code to a named function, a lambda can be used instead: 

    const fruits = {
      // Exactly the same code as 'makeFruits()'.
      auto result = [ "apple", "pear" ];

      if (addCitrus) {
          result ~= [ "orange" ];
      }

      return result;
    }();

The lambda is defined by the highlighted curly braces and is executed by the parenteses at the end. Again, the fruits variable ends up being const as desired.

D allows assigning to const and immutable variables in special initialization blocks called shared static this() (and static this()). These blocks are for initializing variables defined at module scope (outside of any function). It is possible to mutate const and immutable variables in shared static this() blocks: 

immutable int[] i;

shared static this() {
    // It is possible to mutate 'const' and 'immutable' module
    // variables in this block:
    i ~= 43;

    // The variables are still 'const' and 'immutable' for the
    // rest of the program.
}

shared static this() blocks are executed before the program starts running the body of the main() function.

Immutability of the slice versus the elements

We have seen above that the type of a const slice has been printed as const(int[]). As the parentheses after const indicate, it is the entire slice that is const. 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: 

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

    const int[] otherSlice = [ 10, 11 ];
    slice = otherSlice;       // ← compilation ERROR

Taking immutability to that extreme may not be suitable in every case. In most cases, what is important is the immutability of the elements themselves. Since a slice is just a tool to access the elements, it should not matter if we make changes to the slice itself as long as the elements are not modified. This is especially true in the cases we have seen so far, where the function receives a copy of the slice itself.

To specify that only the elements are immutable we use the const keyword with parentheses that enclose just the element type. Modifying the code accordingly, now only the elements are immutable, not the slice itself: 

    const(int)[] slice = [ 1, 2 ];
    slice ~= 3;               // can add elements
    slice[0] = 3;             // ← compilation ERROR
    slice.length = 1;         // can drop elements

    const int[] otherSlice = [ 10, 11 ];
    slice = otherSlice;       /* can provide access to
                               * other elements */

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

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

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

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

This distinction has 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.

const and immutable are transitive

As mentioned in the code comments of slices a and b above, both those slices and their elements are immutable.

This is true for structs and classes as well, both of which will be covered in later chapters. For example, all members of a const struct variable are const and all members of an immutable struct variable are immutable. (Likewise for classes.)

.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 mutability:

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
Summary