Programming in D - Immutability

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:

Some concepts are immutable by definition. For example, there are always seven days in a week, the math constant pi (π) never changes, the list of natural languages supported by a program may be fixed (e.g. only English and Turkish), etc.
Even if they don't represent immutable concepts, some variables are not intended to be mutated after they are initialized; so it may be a programmer error to do so. For example, totalPrice in the code above likely should not be mutated after being assigned its initial value.
By defining only some of its parameters as mutable, a function can dictate which of those parameters will be used as-is as its inputs and which parameters will be modified as side effects.

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

As evidenced by the programs we have been writing so far, immutability is not absolutely necessary.
The immutability concept is expressed in D by the const (short for "constant") and immutable keywords. Although the two words have the same meaning in English, their responsibilities in programs are different and they are sometimes incompatible. (Like inout and shared, const and immutable are type qualifiers.)
Both of the terms "immutable variable" and "constant variable" are nonsensical when the word "variable" is taken literally to mean something that changes. In a broader sense, the word "variable" is often understood to mean any concept of a program, either mutable or immutable.
As an example of self-fulfilling prophecy, functions are forced to observe immutability (forced to be const-correct) and become more useful as a consequence. (This forced observance of const-correctness is sometimes described as being similar to a viral disease.)

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:

min and max are integral parts of the behavior of this program and their values are known at compile time. For that reason they are defined as enum constants.
number is specified as const because it would not be appropriate to modify it after its initialization at run time. Likewise for each user guess: once read, the guess should not be modified.
The types of those variables are not specified explicitly. As with the uses of auto, enum, etc.; the type of a const variable can be inferred from the expression on the right hand side.

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:

The slice named slice that is defined in main(), which is passed to halve() as its parameter
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:

string is an alias for immutable(char)[]
wstring is an alias for immutable(wchar)[]
dstring is an alias for immutable(dchar)[]

Likewise, string literals are immutable as well:

The type of literal "hello"c is string
The type of literal "hello"w is wstring
The type of literal "hello"d is dstring

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:

.dup makes a mutable copy of the array ("dup" stands for "do duplicate")
.idup makes an immutable copy of the array

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

As a general rule, prefer immutable variables over mutable ones.
Define constant values as enum if their values can be calculated at compile time. For example, the constant value of seconds per minute can be an enum:
```
 enum int secondsPerMinute = 60;
```
There is no need to specify the type explicitly if it can be inferred from the right hand side:
```
 enum secondsPerMinute = 60;
```
Consider the hidden cost of enum arrays and enum associative arrays. Define them as immutable variables if they are used more than once in the program.
Specify variables as const if their values will never change but cannot be known at compile time. Again, the type can be inferred:
```
 const guess = readInt("What is your guess");
```

If a function does not modify a parameter, specify that parameter as in. This would express programmer's intent and allow both mutable and immutable variables to be passed as arguments:

void foo(in char[] s) {
 // ...
}
void main() {
 char[] mutableString;
 string immutableString;
 foo(mutableString); // ← compiles
 foo(immutableString); // ← compiles
}

Unlike most examples throughout this book, always specify what part of a parameter should be immutable:

// Only the elements may not be mutated (the slice can be)
void print_1(const(int)[] slice) {
 // ...
}
// Neither the slice variable nor the elements can be mutated
void print_2(const(int[]) slice) {
 // ...
}
// Same as print_2() (Unlike most examples in this book, avoid this style)
void print_3(const int[] slice) {
 // ...
}

Consider that const parameters cannot be passed to functions taking immutable. See the section "Should a parameter be const or immutable?" above.

If the function modifies a parameter, leave that parameter as mutable (in, const, or immutable would not allow modifications anyway):

import std.stdio;
void reverse(dchar[] s) {
 foreach (i; 0 .. s.length / 2) {
 immutable temp = s[i];
 s[i] = s[$ - 1 - i];
 s[$ - 1 - i] = temp;
 }
}
void main() {
 dchar[] salutation = "hello"d.dup;
 reverse(salutation);
 writeln(salutation);
}

The output:

olleh

Summary

enum variables represent immutable concepts that are known at compile time.
enum arrays and associative arrays have the cost of creating a new array at every mention of that enum constant. Prefer immutable for arrays and associative arrays instead.
Prefer in parameters over const parameters.
const and immutable variables represent immutable concepts that can be known at run time (or somewhat obscurely, that must have some memory location that we can refer to).
const parameters are the ones that functions do not modify. Mutable, const, and immutable variables can be passed as arguments of const parameters.
immutable parameters are the ones that functions specifically require them to be so. Only immutable variables can be passed as arguments of immutable parameters.
const(int[]) specifies that neither the slice nor its elements can be modified.
const(int)[] specifies that only the elements cannot be modified.

[ ↢ Prev ] [ Next ↣ ]

Programming in D - Immutability

Immutability

Immutable variables

enum constants

const variables

immutable variables