D Programming Language 2.0

Final, Const, and Invariant

Being able to specify what parts of variables data can change, and under what conditions, can add greatly to the understandability of interfaces, being able to analyse code for correctness, and improve code generation.

With invariant, const and final, the programmer can carefully control these attributes.

Invariant Storage Class

An invariant declaration cannot change, ever, and any data that can be referenced through the invariant cannot ever change. Initializers for invariant declarations can be placed into ROM (Read Only Memory).

	invariant int x = 3;	// x is set to 3
	invariant int y;	// y is set to int.init, which is 0
	x = 4;			// error, x is invariant
	y = 5;			// error, y is invariant

The initializer for an invariant declaration must be evaluatable at compile time:

	int foo(int f) { return f * 3; }
	int i = 5;
	invariant int x = 3 * 4;	// ok, 12
	invariant int y = i + 1;	// error, cannot evaluate at compile time
	invariant int z = foo(2) + 1;	// ok, foo(2) can be evaluated at compile time, 7

Data referred to by an invariant is also invariant:

	invariant char[] s = "foo";
	s[0] = 'a';		// error, invariant

An implementation is allowed to replace an instance of an invariant declaration with the initializer for that declaration. Therefore, it is not legal to take the address of an invariant:

	invariant int i = 3;
	invariant* p = &i;	// error, cannot take address of invariant

Invariant members of a class or struct do not take up any space in instances of those objects:

	struct S
	{   int x;
	    invariant int y;
	}

	writefln(S.sizeof);	// prints 4, not 8

The type of an invariant declaration is itself invariant.

Const Storage Class

A const declaration is exactly like an invariant 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.

Final Storage Class

A final declaration is one that, once initialized, can never change its value.

	final int x = 3;
	x = 4;		// error, x is final

Final declarations can be initialized either by an initializer, or by a constructor:

	final int x;
	static this()
	{
	    x = 4;	// ok, can initialize final x inside constructor
	    x = 5;	// still ok, because still in constructor
	}
	...
	x = 6;		// error, x is final

	class C
	{
	    final int s;
	    this()
	    {	s = 3;	// ok, can initialize in constructor
	    }
	}

Final declarations are stored and do take up space, therefore their address can be taken.

Taking the address of a final variable of type T results in a type that's const(T)*.

	final int x = 3;
	auto p = &x;		// p is const(int)*
	*p = 4;			// error, *p is const

Final declarations are themselves neither invariant nor const.

	int x = 4;
	final int* p = &x;
	p = null;		// error, p is final
	*p = 3;			// ok, x is now 3

Invariant Type

Data that will never change its value can be typed as invariant. The invariant keyword can be used as a type constructor:

	invariant(char)[] s = "hello";

The invariant 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 invariant
	s = null;	// ok, s itself is not invariant

Invariantness is transitive, meaning it applies to anything that can be referenced from the invariant type:

	invariant(char*)** p = ...;
	p = ...;	// ok, p is not final
	*p = ...;	// *p is not invariant
	**p = ...;	// error, **p is invariant
	***p = ...;	// error, ***p is invariant

The invariantness also only applies to what is referred to, not the declaration itself:

	invariant(char*) p = ...;
	p = ...;	// ok, invariant doesn't apply to p itself
	*p = ...;	// error, invariant applies to what p refers to

Creating Invariant Data

The first way is to use a literal that is already invariant, such as string literals. String literals are always invariant.

	auto s = "hello";   // s is invariant(char)[5]
	char[] p = "world"; // error, cannot implicitly convert invariant
			    // to mutable

The second way is to cast data to invariant. When doing so, it is up to the programmer to ensure that no other mutable references to the same data exist.

	char[] s = ...;
	invariant(char)[] p = cast(invariant)s;     // undefined behavior
	invariant(char)[] p = cast(invariant)s.dup; // ok, unique reference

The .idup property is a convenient way to create an invariant copy of an array:

	auto p = s.idup;
	p[0] = ...;	  // error, p[] is invariant

Removing Invariant With A Cast

The invariant type can be removed with a cast:

	invariant 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 invariant-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 invariant-correctness, one must assume the responsibility to ensure the invariantness of the data, as the compiler will no longer be able to statically do so.

Invariant Doesn't Apply To Declared Symbols

Consider the struct:

	struct S
	{
	    int x;
	    int* p;
	}

In order to be able to use structs as user-defined wrappers for builtin types, it must be possible to declare a struct instance as having its members be mutable, but what it refers to to not be mutable. But all that's syntactically available is:

	invariant(S) s;

Therefore, the invariant qualifier doesn't apply to the symbol itself being declared. It only applies to anything indirectly referenced by the symbol. Hence,

	s.x = 3;   // ok
	*s.p = 3;  // error, it's invariant

For consistency's sake, then this must apply generally:

	int x;
	invariant(int*) p;
	p = cast(invariant)&x;    // ok
	*p = 3;    // error, invariant

	invariant(int) y;
	y = 3;        // ok
	auto q = cast(invariant)&y;  // q's type is invariant(int)*
	*q = 4;       // error, invariant

A similar situation applies to classes. Given:

	class C
	{
	    int x;
	    int* p;
	}

	invariant(C) c;
	c = new C;      // (1) ok
	c.x = 3;        // (2) error, invariant
	*c.p = 4;       // (3) error, invariant

Note that the c.x is an error, while the s.x is not. The reason is that c is already a reference type - so the invariant does not apply to c itself (1), but it does apply to what c refers to (2) and anything transitively referred to (3).

Invariant Member Functions

Invariant member functions are guaranteed that the object and anything referred to by the this reference is invariant. They are declared as:

	struct S
	{   int x;

	    invariant void foo()
	    {
		x = 4;	// error, x is invariant
		this.x = 4;   // error, x is invariant
	    }
	}

Const Type

Const types are like invariant types, except that const forms a read-only view of data. Other aliases to that same data may change it at any time.

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.

Implicit Conversions

Mutable and invariant types can be implicitly converted to const. Mutable types cannot be implicitly converted to invariant, and vice versa.

Comparing D Invariant, Const and Final with C++ Const

// ptr to const ptr to const int
const(int*)* p;

// ptr to const ptr to const int
const int *const *p;

const int** p;  // const ptr to const ptr to const int
**p = 3;    // error

int** const p; // const ptr to ptr to int
**p = 3;    // ok

const(int)* p;   // ptr to const int
int* q = cast(int*)p; // ok

const int* p;   // ptr to const int
int* q = const_cast<int*>p; // ok

const(int)* p;   // ptr to const int
int* q = cast(int*)p;
*q = 3;   // undefined behavior

const int* p;   // ptr to const int
int* q = const_cast<int*>p;
*q = 3;   // ok

void foo(int x);
void foo(const int x);  // error

void foo(int x);
void foo(const int x);  // error

void foo(const int* x, int* y)
{
   bar(*x); // bar(3)
   *y = 4;
   bar(*x); // bar(4)
}
...
int i = 3;
foo(&i, &i);

void foo(const int* x, int* y)
{
   bar(*x); // bar(3)
   *y = 4;
   bar(*x); // bar(4)
}
...
int i = 3;
foo(&i, &i);

void foo(invariant int* x, int* y)
{
   bar(*x); // bar(3)
   *y = 4;  // undefined behavior
   bar(*x); // bar(??)
}
...
int i = 3;
foo(cast(invariant)&i, &i);