Proposal: immutable fields and properties

[stefanloerwald]

Rationale

Programmers make implicit assumptions about the state of objects. For example, the implicit assumption about a function to calculate the total of a list of integers, is that neither the list, nor the values in the list, will be changed by that function:

static int Total1(List<int> values)
{
	int sum = 0;
	foreach (var value in values)
	{
		sum += value;
	}
	return sum;
}

However, by the method signature alone, we cannot infer either property. A non-intuitive implementation might modify elements, add, or remove entries:

static int Total2(List<int> values)
{
	while (values.Count() > 1)
	{
		values[0] += values.Last();
		values.Remove(values.Last());
	}
	return values.Any() ? values.First() : 0;
}
static int Total2a(List<int> values)
{
	int sum = 0;
	while (values.Any())
	{
		sum += values.Last();
		values.Remove(values.Last());
	}
	return sum;
}

These implementations are equally valid in terms of the returned value, but will modify the list. Given the standard C# libraries, we can use IReadOnlyList<T> to avoid the modification of the list itself, but we still lack one crucial thing, which is the prevention of modification of values. In case of integers, this is already sufficient by IReadOnlyList<int>[int index] as a get-only property, however for more even slightly more complex IReadOnlyList<T>, this is not guaranteed:

public class IntWrapper
{
	public int Value {get; set;}
}
static int Total3(IReadOnlyList<IntWrapper> values)
{
	int sum = 0;
	for (int i = 0; i < values.Count; ++i)
	{
		sum += values[i].Value;
		values[i].Value = 0; // developer thinks it’s clever to mark as handled.
	}
	return sum;
}

What we actually want is something like static int Total(IReadOnlyList<IReadOnlyInt> values), however, that is not possible without writing a lot of boilerplate code. This proposal is to add two new keywords immutable and mutable. The method declaration then becomes static int Total(immutable List<immutable int> values) and int Total(immutable List<immutable IntWrapper> values).
Total2 fails to compile at values[0] += values.Last(), as modification of values[0] is not permitted (as the += operator on int is not immutable:

static int Total2(immutable List<immutable int> values)
{
	while (values.Count() > 1) // legal
	{
		values[0] += values.Last(); // illegal, modification of immutable value (values[0] returns immutable int)
		values.Remove(values.Last()); // illegal, values is immutable
	}
	return values.Any() ? values.First() : 0; // legal
}

Total2a fails to compile at values.Remove(values.Last()), as modification of values is not permitted (as Remove is not declared immutable:

static int Total2a(immutable List<immutable int> values)
{
	int sum = 0;
	while (values.Any()) // legal
	{
		sum += values.Last(); // legal
		values.Remove(values.Last()); // illegal
	}
	return sum;
}

Total3 fails to compile at values[i].Value = 0, as modification of values[0].Value is not permitted (as the = operator on int is not immutable:

static int Total3(immutable List<immutable IntWrapper> values)
{
	int sum = 0;
	for (int i = 0; i < values.Count; ++i) // legal
	{
		sum += values[i].Value; // legal
		values[i].Value = 0; // illegal, values[i] is immutable IntWrapper, therefore values[i].Value is immutable int
	}
	return sum;
}

Changes to the language

The keywords immutable and its antonym mutable can be used in several contexts.
The effects are on compile time only.

immutable and mutable fields and properties

Immutability is all about preservation of logical state, therefore, in an immutable context, all modifications to fields and auto-properties are disallowed, i.e. fields are implicitly immutable, and immutable applies transitively. Some fields are used to track internal state, but not observable logical state. Such fields (e.g. a version property such as in CoreLib's System.Collections.Generic.List<T>) can be marked mutable.

public class Foo
{
	
	public int Property { get; set; }
	private mutable int version;
	private mutable int bar;
	public int Bar 
	{
		get { return bar; }
		set { bar = value; ++version; }
	}
}
immutable var foo = new Foo();
foo.Property = 0; // illegal
foo.Bar = 0; // legal

immutable parameter

A parameter can be declared immutable. The effects are that the body of the function may not modify the state of the parameter in any way. It is equivalent to replacing the type of the immutable parameter with one, that only implements the non-modifying methods (property setters are therefore also excluded, unless they don’t modify any field), and has all fields declared by their respective immutable types.

static void Modify(Bar bar)
{
	Bar.Content = “”;
}
static void Observe(immutable Bar bar)
{
	Assert(bar.Content.Length >= 0);
}
static void Test(immutable Foo foo)
{
	Modify(foo.Bar);	// illegal, as Modify expects a mutable Bar
	Observe(foo.Bar);	// legal, as Observe satisfies the contract
				// of not modifying any Bar, and therefore
				//transitively foo.Bar
}

immutable method

A method can be declared immutable to disallow modification of any field of the class with the exception of fields with the mutable modifier.

class Foo
{
	int Value { get; set; }
	float bar;
	float Bar { get => bar; set { bar = value; } }
	public float immutable Observe()
	{
		Value = 5; // illegal, as it modifies state of Foo
		bar = 2.0; // illegal, as it modifies state of Foo
		Bar = 2.0; // illegal, as it modifies state of Foo
		return Value * Bar; // legal, no modification of state
	}
	public void mutable Modify()
	{
		Value = 5;
	}
}

Non-immutable methods may not be called from a method declared immutable, including by transitivity all non-immutable methods on any immutable field. Methods are mutable unless otherwise determined, but can be optionally marked mutable.

immutable return values

class Foo
{
	private Bar bar = new Bar();
	public immutable Bar SetAndViewBar()
	{
		bar = new Bar(); // legal
		return bar; // legal
	}
	public Bar immutable ViewMutableBar()
	{
		bar = new Bar(); // illegal, modification of field
		return bar; // illegal, called may now violate the immutability of Foo. bar is implicitly immutable inside the scope of ViewMutableBar
	}
	public immutable Bar immutable ViewImmutableBar()
	{
		bar = new Bar(); // illegal, modification of field
		return bar; // legal, caller cannot modify state of Foo
	}
}

Note that public immutable T Method() is different to public T immutable Method(). The former returns an object of type T that cannot be modified, whereas the latter returns a modifiable object of type T, but the method itself does not modify the state of the class. public immutable T immutable Method() does not modify its classes state, and the returned object is immutable.

immutable at call-site

To highlight the expectation of immutability of an object at the call-site, one can add immutable to the passed object.

public class Foo
{
	public static int Total(immutable List<immutable int> list)
	{
		return 0;
	}
	public static void ClearList(List<int> list)
	{
		list.Clear();
	}
}
void caller()
{
	var list = new List<int> { 0, 1, 2 };
	var total = Foo.Total(immutable list); // legal
	Foo.ClearList(immutable list); // illegal, as ClearList expects mutable list
}

immutable generics type parameters

On instantiation of a generic type or method, type parameters may be declared immutable.

public class Foo<T>
{
	public T Value { get; set; }
	public void Reset()
	{
		Value = default;
	}
	public Foo<T>(T value)
	{
		Value = value;
	}
}
// type instantiated with immutable
var foo = new Foo<immutable Bar>(new Bar());
foo.Value.Modify();		// illegal
foo.Value.Observe();		// legal
foo.Value = default;		// legal
foo.Reset();			// legal
var _ = foo as Foo<Bar>;	// illegal
// observing a Foo<T> as Foo<immutable T>
var foo2 = new Foo<Bar>(new Bar());
{
	var ro_foo2 = foo2 as Foo<immutable Bar>;	// legal
	ro_foo2.Value.Modify();				// illegal
	ro_foo2.Value.Observe();			// legal
	ro_foo2.Value = default;			// legal
	ro_foo2.Reset();				// legal
}
// List behaviour
var list = new List<immutable Foo>();
list.Add(new Foo());				// legal
list.Clear();					// legal
list.Add(new Foo());				// legal
list.First().Modify();				// illegal

Any Type<T> can be cast to a Type<immutable T>, but not vice-versa.

immutable arrays

An immutable array must be distinguishable from an array of immutable objects. In immutable T[], immutable applies to T, in T immutable[], it applies to the array.

Type casting

The keyword immutable may not be cast away, i.e. if an object of type T is declared immutable and T is type-convertible to S, then the object may be cast to immutable S, but not S.

public class Class : Base
{
}
immutable var foo = new Class();
immutable var boo = foo as immutable Base; // legal
var boo = foo as immutable Base;  // illegal, boo not declared immutable
var boo = foo as Base; // illegal, foo is immutable Class; cannot cast away immutable

Explicit override to non-immutable

For some corner cases, the override of the immutability of an object may be necessary, e.g. to use legacy libraries. To pass an immutable object to a function that doesn't promise immutable, the object must explicitly be modified to be mutable. To highlight the danger of such an operation, this proposal argues for the use of mutable! instead of just mutable.

public static void Observe(immutable Foo foo)
{
	Legacy.Library.Call(foo); // illegal
	Legacy.Library.Call(mutable! foo); // legal
}

Some methods must be able to modify state while appearing immutable. Similarly to a function call, mutable! can be used to override immutability in an expression or a code block.

public class Foo
{
	public void immutable ActuallyModifying()
	{
		mutable!
		{
			Value++; // legal
			Value--; // legal
		}
		mutable! Value = 0; // legal
		Value = -1; // illegal
	}
}

Why existing keywords are not reused

There are two keywords in the language that can be associated with immutability: const (coming from a C++ background) and readonly. However, the existing usage is distinctly different to what is proposed here (no transitivity in readonly, compile time constant for const) and not compatible in declarations, e.g. private readonly immutable T value; -- here, the writer intends initialization in the constructor only, hence readonly. In the class, value can be observed, but not modified.

Inferred immutable

The immutable modifier to methods can be inferred through static code analysis. A pessimistic analysis seems most appropriate for this language feature.

public int Unclear(bool flag) // determined not to be immutable
{
	if (flag)
	{
		Value += 1;
		return Value;
	}
	return Value;
}
public int ReadOnly() // immutable inferred
{
	return Value;
}
public void Increment() // mutable inferred
{
	Value += 1;
}

Example: Effects on List<T>

Current definition

The definition of List<T> is:

public List();
public List(IEnumerable<T> collection);
public List(int capacity);

public T this[int index] { get; set; }

public int Count { get; }
public int Capacity { get; set; }

public void Add(T item);
public void AddRange(IEnumerable<T> collection);
public ReadOnlyCollection<T> AsReadOnly();
public int BinarySearch(T item);
public int BinarySearch(T item, IComparer<T> comparer);
public int BinarySearch(int index, int count, T item, IComparer<T> comparer);
public void Clear();
public bool Contains(T item);
public List<TOutput> ConvertAll<TOutput>(Converter<T, TOutput> converter);
public void CopyTo(int index, T[] array, int arrayIndex, int count);
public void CopyTo(T[] array, int arrayIndex);
public void CopyTo(T[] array);
public bool Exists(Predicate<T> match);
public T Find(Predicate<T> match);
public List<T> FindAll(Predicate<T> match);
public int FindIndex(int startIndex, int count, Predicate<T> match);
public int FindIndex(int startIndex, Predicate<T> match);
public int FindIndex(Predicate<T> match);
public T FindLast(Predicate<T> match);
public int FindLastIndex(int startIndex, int count, Predicate<T> match);
public int FindLastIndex(int startIndex, Predicate<T> match);
public int FindLastIndex(Predicate<T> match);
public void ForEach(Action<T> action);
public Enumerator GetEnumerator();
public List<T> GetRange(int index, int count);
public int IndexOf(T item, int index, int count);
public int IndexOf(T item, int index);
public int IndexOf(T item);
public void Insert(int index, T item);
public void InsertRange(int index, IEnumerable<T> collection);
public int LastIndexOf(T item);
public int LastIndexOf(T item, int index);
public int LastIndexOf(T item, int index, int count);
public bool Remove(T item);
public int RemoveAll(Predicate<T> match);
public void RemoveAt(int index);
public void RemoveRange(int index, int count);
public void Reverse(int index, int count);
public void Reverse();
public void Sort(Comparison<T> comparison);
public void Sort(int index, int count, IComparer<T> comparer);
public void Sort();
public void Sort(IComparer<T> comparer);
public T[] ToArray();
public void TrimExcess();
public bool TrueForAll(Predicate<T> match);

New definition

The definition of List<T> can communicate intent of mutability / immutability much clearer:

public List();
public List(IEnumerable<T> collection);
public List(int capacity);

+// note: The current CoreLib implementation increments _version on set of an element.
+// This requires the override of immutable in either the setter, or the _version field.
-public T this[int index] { get; set; }
+public T immutable this[int index] { get; set; }

public int Count { get; }
public int Capacity { get; set; }

public void Add(T item);
public void AddRange(IEnumerable<T> collection);
-public ReadOnlyCollection<T> AsReadOnly();
+public ReadOnlyCollection<T> immutable AsReadOnly(); // obsolete
-public int BinarySearch(T item);
+public int immutable BinarySearch(immutable T item);
+// note: Under the assumption that IComparer<T> will not change to contain Compare(immutable T x, immutable T y)
+// BinarySearch cannot be made immutable. Given the amount of existing code relying on IComparer implementations
+// to have the the freedom to modify the parameters x and y, the only solution is to add an overload that accepts
+// an IComparer<immutable T>.
public int BinarySearch(T item, IComparer<T> comparer);
public int BinarySearch(int index, int count, T item, IComparer<T> comparer);
+public int immutable BinarySearch(immutable T item, IComparer <immutable T> comparer); 
+public int immutable BinarySearch(int index, int count, immutable T item, IComparer<immutable T> comparer);

public void Clear();
-public bool Contains(T item); 
+public bool immutable Contains(immutable T item); 
public List<TOutput> ConvertAll<TOutput>(Converter<T, TOutput> converter);
+public List<TOutput> immutable ConvertAll<TOutput>(Converter<immutable T, TOutput> converter);
-public void CopyTo(int index, T[] array, int arrayIndex, int count);
-public void CopyTo(T[] array, int arrayIndex);
-public void CopyTo(T[] array);
+public void immutable CopyTo(int index, T[] array, int arrayIndex, int count);
+public void immutable CopyTo(T[] array, int arrayIndex);
+public void immutable CopyTo(T[] array);
public bool Exists(Predicate<T> match);
public T Find(Predicate<T> match);
public List<T> FindAll(Predicate<T> match);
public int FindIndex(int startIndex, int count, Predicate<T> match);
public int FindIndex(int startIndex, Predicate<T> match);
public int FindIndex(Predicate<T> match);
public T FindLast(Predicate<T> match);
public int FindLastIndex(int startIndex, int count, Predicate<T> match);
public int FindLastIndex(int startIndex, Predicate<T> match);
public int FindLastIndex(Predicate<T> match);
+public bool immutable Exists(Predicate<immutable T> match);
+public T immutable Find(Predicate<immutable T> match);
+public List<T> immutable FindAll(Predicate<immutable T> match);
+public int immutable FindIndex(int startIndex, int count, Predicate<immutable T> match);
+public int immutable FindIndex(int startIndex, Predicate<immutable T> match);
+public int immutable FindIndex(Predicate<immutable T> match);
+public T immutable FindLast(Predicate<immutable T> match);
+public int immutable FindLastIndex(int startIndex, int count, Predicate<immutable T> match);
+public int immutable FindLastIndex(int startIndex, Predicate<immutable T> match);
+public int immutable FindLastIndex(Predicate<immutable T> match);

-public void ForEach(Action<T> action);
+public void immutable ForEach(Action<T> action);
+public void immutable ForEach(Action<immutable T> action);
-public Enumerator GetEnumerator();
-public List<T> GetRange(int index, int count);
-public int IndexOf(T item, int index, int count);
-public int IndexOf(T item, int index);
-public int IndexOf(T item);
+public Enumerator immutable GetEnumerator();
+public List<T> immutable GetRange(int index, int count);
+public int immutable IndexOf(immutable T item, int index, int count);
+public int immutable IndexOf(immutable T item, int index);
+public int immutable IndexOf(immutable T item);
public void Insert(int index, T item);
public void InsertRange(int index, IEnumerable<T> collection);
-public int LastIndexOf(T item);
-public int LastIndexOf(T item, int index);
-public int LastIndexOf(T item, int index, int count);
+public int immutable LastIndexOf(immutable T item);
+public int immutable LastIndexOf(immutable T item, int index);
+public int immutable LastIndexOf(immutable T item, int index, int count);
-public bool Remove(T item); 
+public bool Remove(immutable T item); 
public int RemoveAll(Predicate<T> match);
+public int RemoveAll(Predicate<immutable T> match);
public void RemoveAt(int index);
public void RemoveRange(int index, int count);
public void Reverse(int index, int count);
public void Reverse();
public void Sort(Comparison<T> comparison);
+public void Sort(Comparison<immutable T> comparison); 
public void Sort(int index, int count, IComparer<T> comparer);
+public void Sort(int index, int count, IComparer<immutable T> comparer);
public void Sort();
public void Sort(IComparer<T> comparer);
+public void Sort(IComparer<immutable T> comparer);
-public T[] ToArray();
+public T[] immutable ToArray();
public void TrimExcess();
-public bool TrueForAll(Predicate<T> match);
+public bool immutable TrueForAll(Predicate<T> match);
+public bool immutable TrueForAll(Predicate<immutable T> match);

Reduced interface when observed as immutable List<T>

An immutable List<T> will expose the subset

public List();
public List(IEnumerable<T> collection);
public List(int capacity);

-public T immutable this[int index] { get; set; }
+public T immutable this[int index] { get; }

public int Count { get; }
-public int Capacity { get; set; }
+public int Capacity { get; }

-public void Add(T item);
-public void AddRange(IEnumerable<T> collection);
public ReadOnlyCollection<T> immutable AsReadOnly(); // obsolete
public int immutable BinarySearch(immutable T item);
-public int BinarySearch(T item, IComparer<T> comparer);
-public int BinarySearch(int index, int count, T item, IComparer<T> comparer);
public int immutable BinarySearch(immutable T item, IComparer <immutable T> comparer); 
public int immutable BinarySearch(int index, int count, immutable T item, IComparer<immutable T> comparer);

-public void Clear();
public bool immutable Contains(immutable T item); 
-public List<TOutput> ConvertAll<TOutput>(Converter<T, TOutput> converter);
public List<TOutput> immutable ConvertAll<TOutput>(Converter<immutable T, TOutput> converter);
public void immutable CopyTo(int index, T[] array, int arrayIndex, int count);
public void immutable CopyTo(T[] array, int arrayIndex);
public void immutable CopyTo(T[] array);
-public bool Exists(Predicate<T> match);
-public T Find(Predicate<T> match);
-public List<T> FindAll(Predicate<T> match);
-public int FindIndex(int startIndex, int count, Predicate<T> match);
-public int FindIndex(int startIndex, Predicate<T> match);
-public int FindIndex(Predicate<T> match);
-public T FindLast(Predicate<T> match);
-public int FindLastIndex(int startIndex, int count, Predicate<T> match);
-public int FindLastIndex(int startIndex, Predicate<T> match);
-public int FindLastIndex(Predicate<T> match);
public bool immutable Exists(Predicate<immutable T> match);
public T immutable Find(Predicate<immutable T> match);
public List<T> immutable FindAll(Predicate<immutable T> match);
public int immutable FindIndex(int startIndex, int count, Predicate<immutable T> match);
public int immutable FindIndex(int startIndex, Predicate<immutable T> match);
public int immutable FindIndex(Predicate<immutable T> match);
public T immutable FindLast(Predicate<immutable T> match);
public int immutable FindLastIndex(int startIndex, int count, Predicate<immutable T> match);
public int immutable FindLastIndex(int startIndex, Predicate<immutable T> match);
public int immutable FindLastIndex(Predicate<immutable T> match);

public void immutable ForEach(Action<T> action);
public void immutable ForEach(Action<immutable T> action);
public Enumerator immutable GetEnumerator();
public List<T> immutable GetRange(int index, int count);
public int immutable IndexOf(immutable T item, int index, int count);
public int immutable IndexOf(immutable T item, int index);
public int immutable IndexOf(immutable T item);
-public void Insert(int index, T item);
-public void InsertRange(int index, IEnumerable<T> collection);
public int immutable LastIndexOf(immutable T item);
public int immutable LastIndexOf(immutable T item, int index);
public int immutable LastIndexOf(immutable T item, int index, int count);
-public bool Remove(immutable T item); 
-public int RemoveAll(Predicate<T> match);
-public int RemoveAll(Predicate<immutable T> match);
-public void RemoveAt(int index);
-public void RemoveRange(int index, int count);
-public void Reverse(int index, int count);
-public void Reverse();
-public void Sort(Comparison<T> comparison);
-public void Sort(Comparison<immutable T> comparison); 
-public void Sort(int index, int count, IComparer<T> comparer);
-public void Sort(int index, int count, IComparer<immutable T> comparer);
-public void Sort();
-public void Sort(IComparer<T> comparer);
-public void Sort(IComparer<immutable T> comparer);
public T[] immutable ToArray();
-public void TrimExcess();
public bool immutable TrueForAll(Predicate<T> match);
public bool immutable TrueForAll(Predicate<immutable T> match);

Reduced interface when observed as List<immutable T>

A List<immutable T> will expose

public List();
-public List(IEnumerable<T> collection);
+public List(IEnumerable<immutable T> collection);
public List(int capacity);

-public T immutable this[int index] { get; set; }
+public immutable T immutable this[int index] { get; set; }

public int Count { get; }
public int Capacity { get; set; }

-public void Add(T item);
-public void AddRange(IEnumerable<T> collection);
-public ReadOnlyCollection<T> immutable AsReadOnly(); // obsolete
+public void Add(immutable T item);
+public void AddRange(IEnumerable<immutable T> collection);
+public ReadOnlyCollection<immutable T> immutable AsReadOnly(); // obsolete
public int immutable BinarySearch(immutable T item);
+// note that immutable T would introduce ambiguity between methods with methods where parameters
+// are declared immutable and such where parameters are not declared immutable, but are implicit
+// through using List<immutable T>. In that case, the overload with declared immutable parameters
+// is strictly preferred.
-public int BinarySearch(immutable T item, IComparer<immutable T> comparer);
-public int BinarySearch(int index, int count, immutable T item, IComparer<immutable T> comparer);
public int immutable BinarySearch(immutable T item, IComparer <immutable T> comparer); 
public int immutable BinarySearch(int index, int count, immutable T item, IComparer<immutable T> comparer);

public void Clear();
public bool immutable Contains(immutable T item); 
-public List<TOutput> ConvertAll<TOutput>(Converter<T, TOutput> converter);
public List<TOutput> immutable ConvertAll<TOutput>(Converter<immutable T, TOutput> converter);
-public void immutable CopyTo(int index, T[] array, int arrayIndex, int count);
-public void immutable CopyTo(T[] array, int arrayIndex);
-public void immutable CopyTo(T[] array);
+public void immutable CopyTo(int index, immutable T[] array, int arrayIndex, int count);
+public void immutable CopyTo(immutable T[] array, int arrayIndex);
+public void immutable CopyTo(immutable T[] array);
-public bool Exists(Predicate<T> match);
-public T Find(Predicate<T> match);
-public List<T> FindAll(Predicate<T> match);
-public int FindIndex(int startIndex, int count, Predicate<T> match);
-public int FindIndex(int startIndex, Predicate<T> match);
-public int FindIndex(Predicate<T> match);
-public T FindLast(Predicate<T> match);
-public int FindLastIndex(int startIndex, int count, Predicate<T> match);
-public int FindLastIndex(int startIndex, Predicate<T> match);
-public int FindLastIndex(Predicate<T> match);
public bool immutable Exists(Predicate<immutable T> match);
-public T immutable Find(Predicate<immutable T> match);
+public immutable T immutable Find(Predicate<immutable T> match);
-public List<T> immutable FindAll(Predicate<immutable T> match);
+public List<immutable T> immutable FindAll(Predicate<immutable T> match);
public int immutable FindIndex(int startIndex, int count, Predicate<immutable T> match);
public int immutable FindIndex(int startIndex, Predicate<immutable T> match);
public int immutable FindIndex(Predicate<immutable T> match);
-public T immutable FindLast(Predicate<immutable T> match);
+public immutable T immutable FindLast(Predicate<immutable T> match);
public int immutable FindLastIndex(int startIndex, int count, Predicate<immutable T> match);
public int immutable FindLastIndex(int startIndex, Predicate<immutable T> match);
public int immutable FindLastIndex(Predicate<immutable T> match);

-public void immutable ForEach(Action<T> action);
public void immutable ForEach(Action<immutable T> action);
public Enumerator immutable GetEnumerator();
-public List<T> immutable GetRange(int index, int count);
+public List<immutable T> immutable GetRange(int index, int count);
public int immutable IndexOf(immutable T item, int index, int count);
public int immutable IndexOf(immutable T item, int index);
public int immutable IndexOf(immutable T item);
-public void Insert(int index, T item);
+public void Insert(int index, immutable T item);
-public void InsertRange(int index, IEnumerable<T> collection);
+public void InsertRange(int index, IEnumerable<immutable T> collection);
public int immutable LastIndexOf(immutable T item);
public int immutable LastIndexOf(immutable T item, int index);
public int immutable LastIndexOf(immutable T item, int index, int count);
public bool Remove(immutable T item); 
-public int RemoveAll(Predicate<T> match);
public int RemoveAll(Predicate<immutable T> match);
public void RemoveAt(int index);
public void RemoveRange(int index, int count);
public void Reverse(int index, int count);
public void Reverse();
-public void Sort(Comparison<T> comparison);
public void Sort(Comparison<immutable T> comparison); 
-public void Sort(int index, int count, IComparer<T> comparer);
public void Sort(int index, int count, IComparer<immutable T> comparer);
public void Sort();
-public void Sort(IComparer<T> comparer);
public void Sort(IComparer<immutable T> comparer);
-public T[] immutable ToArray();
+public immutable T[] immutable ToArray();
public void TrimExcess();
-public bool immutable TrueForAll(Predicate<T> match);
public bool immutable TrueForAll(Predicate<immutable T> match);

Reduced interface when observed as immutable List

An immutable List<immutable T> will expose

public List();
-public List(IEnumerable<T> collection);
+public List(IEnumerable<immutable T> collection);
public List(int capacity);

-public T immutable this[int index] { get; set; }
+public immutable T immutable this[int index] { get; }

public int Count { get; }
-public int Capacity { get; set; }
+public int Capacity { get; }

-public void Add(T item);
-public void AddRange(IEnumerable<T> collection);
-public ReadOnlyCollection<T> immutable AsReadOnly(); // obsolete
+public ReadOnlyCollection<immutable T> immutable AsReadOnly(); // obsolete
public int immutable BinarySearch(immutable T item);
+// note that immutable T would introduce ambiguity between methods with methods where parameters
+// are declared immutable and such where parameters are not declared immutable, but are implicit
+// through using List<immutable T>. In that case, the overload with declared immutable parameters
+// is strictly preferred.
-public int BinarySearch(T item, IComparer<T> comparer);
-public int BinarySearch(int index, int count, T item, IComparer<T> comparer);
public int immutable BinarySearch(immutable T item, IComparer <immutable T> comparer); 
public int immutable BinarySearch(int index, int count, immutable T item, IComparer<immutable T> comparer);

-public void Clear();
public bool immutable Contains(immutable T item); 
-public List<TOutput> ConvertAll<TOutput>(Converter<T, TOutput> converter);
public List<TOutput> immutable ConvertAll<TOutput>(Converter<immutable T, TOutput> converter);
-public void immutable CopyTo(int index, T[] array, int arrayIndex, int count);
-public void immutable CopyTo(T[] array, int arrayIndex);
-public void immutable CopyTo(T[] array);
+public void immutable CopyTo(int index, immutable T[] array, int arrayIndex, int count);
+public void immutable CopyTo(immutable T[] array, int arrayIndex);
+public void immutable CopyTo(immutable T[] array);
-public bool Exists(Predicate<T> match);
-public T Find(Predicate<T> match);
-public List<T> FindAll(Predicate<T> match);
-public int FindIndex(int startIndex, int count, Predicate<T> match);
-public int FindIndex(int startIndex, Predicate<T> match);
-public int FindIndex(Predicate<T> match);
-public T FindLast(Predicate<T> match);
-public int FindLastIndex(int startIndex, int count, Predicate<T> match);
-public int FindLastIndex(int startIndex, Predicate<T> match);
-public int FindLastIndex(Predicate<T> match);
public bool immutable Exists(Predicate<immutable T> match);
-public T immutable Find(Predicate<immutable T> match);
-public List<T> immutable FindAll(Predicate<immutable T> match);
+public immutable T immutable Find(Predicate<immutable T> match);
+public List<immutable T> immutable FindAll(Predicate<immutable T> match);
public int immutable FindIndex(int startIndex, int count, Predicate<immutable T> match);
public int immutable FindIndex(int startIndex, Predicate<immutable T> match);
public int immutable FindIndex(Predicate<immutable T> match);
-public T immutable FindLast(Predicate<immutable T> match);
+public immutable T immutable FindLast(Predicate<immutable T> match);
public int immutable FindLastIndex(int startIndex, int count, Predicate<immutable T> match);
public int immutable FindLastIndex(int startIndex, Predicate<immutable T> match);
public int immutable FindLastIndex(Predicate<immutable T> match);

-public void immutable ForEach(Action<T> action);
public void immutable ForEach(Action<immutable T> action);
public Enumerator immutable GetEnumerator();
-public List<T> immutable GetRange(int index, int count);
+public List<immutable T> immutable GetRange(int index, int count);
public int immutable IndexOf(immutable T item, int index, int count);
public int immutable IndexOf(immutable T item, int index);
public int immutable IndexOf(immutable T item);
-public void Insert(int index, T item);
-public void InsertRange(int index, IEnumerable<T> collection);
public int immutable LastIndexOf(immutable T item);
public int immutable LastIndexOf(immutable T item, int index);
public int immutable LastIndexOf(immutable T item, int index, int count);
-public bool Remove(immutable T item); 
-public int RemoveAll(Predicate<T> match);
-public int RemoveAll(Predicate<immutable T> match);
-public void RemoveAt(int index);
-public void RemoveRange(int index, int count);
-public void Reverse(int index, int count);
-public void Reverse();
-public void Sort(Comparison<T> comparison);
-public void Sort(Comparison<immutable T> comparison); 
-public void Sort(int index, int count, IComparer<T> comparer);
-public void Sort(int index, int count, IComparer<immutable T> comparer);
-public void Sort();
-public void Sort(IComparer<T> comparer);
-public void Sort(IComparer<immutable T> comparer);
-public T[] immutable ToArray();
+public immutable T[] immutable ToArray();
-public void TrimExcess();
-public bool immutable TrueForAll(Predicate<T> match);
public bool immutable TrueForAll(Predicate<immutable T> match);

Difference to existing language features

Difference to in parameters

in parameters disallow the change of references, they do not disallow modification of the object state itself:

void func(in Foo object)
{
	object = default;				// illegal
	object.Property = default;			// legal
	object.Property.ChildProperty = default;	// legal
}

An immutable parameter on the other hand disallows modification transitively, but not itself:

int func(immutable Foo object)
{
	object.StringProperty = default;		// illegal
	object.Property.ChildProperty = default;	// illegal
	object = default; 				// legal
	return object.StringProperty.Length;	    // legal
}

Difference to get-only properties

A get-only property disallows the modification of the field itself, but as with in parameters, they do not disallow modification of the object:

class Foo
{
	Bar GetOnly {get;}
	immutable Bar Bar {get; set; }
	immutable Bar Baz {get; }
}
var foo = new Foo();
foo.GetOnly = new Bar(); // illegal
foo.GetOnly.Modify(); // legal
foo.Bar = new Bar(); // legal
foo.Baz = new Bar(); // illegal, as get-only
foo.Bar.Modify(); // illegal, Bar is immutable
foo.Baz.Modify(); // illegal, Baz is immutable

Difference to implementation with interfaces / inheritance

The safety against unintentional modification can be implemented via interfaces, e.g. IReadOnlyList versus List. While it is technically possible to write IReadOnlyT interfaces for all T, it is an undesirable amount of boilerplate code. Furthermore, nothing prevents the inclusion of state-modifying methods in such a IReadOnlyT interface, or the implementation of the interface to violate the assumption. Lastly, the transitivity of immutable cannot be implemented via interfaces / inheritance:

public interface IReadOnlyBar
{
}
public class Bar : IReadOnlyBar
{
}
public interface IReadOnlyFoo
{
	IReadOnlyBar Bar { get; } // declared as get-only to make property of Foo immutable. Type of property must be IReadOnly equivalent, otherwise transitivity is broken.
}
public class Foo : IReadOnlyFoo
{
	public Bar Bar {get; set; } // compilation error: Foo doesn't implement IReadOnlyFoo, as property is declared to be of type IReadOnlyBar in IReadOnlyFoo.
}

Comparison to C++ const

The proposed immutable keyword behaves in many ways similar to C++ const, i.e. immutability is transitive and applies to fields and methods. The key difference lies in their behavior in generics/templates. In C++, a vector<int> cannot be cast to vector<const int>, because the vector template gets compiled to fundamentally different types. Allowing a conversion of IEnumerable<T> to IEnumerable<immutable T> - but not vice-versa – enables writing safer code.

Future

I would like to invite any person interested to challenge, add, correct, and build upon this initial proposal.

[svick]

This proposal is to add two new keywords immutable and mutable.

Is immutable meant to become widespread? If it is, isn't it too verbose? (Consider that for nullable reference types, a single character was considered too verbose.) If it isn't, would it be worth implementing?

Some fields are used to track internal state, but not observable logical state. Such fields (e.g. a version property such as in CoreLib's System.Collections.Generic.List<T>) can be marked mutable.

This means that immutable does not imply that the object in question is thread-safe. I think that thread-safety is an important reason why the inconvenience of immutability can be worth it (see e.g. the Roslyn codebase), but this proposal does not attempt to do that. Is that the right approach?

Any Type<T> can be cast to a Type<immutable T>, but not vice-versa.

I don't think that would be safe. Consider:

void Sneaky(immutable Foo foo)
{
    List<Foo> listOfMutable = new List<Foo>();
    List<immutable Foo> listOfImmutable = listOfMutable;
    listOfImmutable.Add(foo);
    listOfMutable[0].Property = 42;
}

Thanks to that cast from List<Foo> to List<immutable Foo>, I was able to mutate an immutable object.

The immutable modifier to methods can be inferred through static code analysis.

I think this could be a trap for libraries. If the compiler infers that a method is immutable, and I later need to modify it to make it mutable, it would be a breaking change. Or does this mean that library authors would be recommended to explicitly mark every method as mutable, unless they made sure that the method can stay immutable in the future?

+public T immutable this[int index] { get; set; }

What does it mean for a property an indexer with a setter to be immutable? Does that modifier only apply to the getter?

public int BinarySearch(T item, IComparer<T> comparer);
+public int immutable BinarySearch(immutable T item, IComparer <immutable T> comparer); 

This raises the question of how immutable would be represented in metadata. The obvious answer is to use attributes, but those are not considered to be part of method signature, so you couldn't have both of the methods above at the same time.

An alternative would be to use modopt or modreq, which I think would allow this kind of overloading. But then, what would happen if I wrote code like the above and then attempted to use it from a language that didn't understand immutable (including older versions of C#)?

[stefanloerwald]

This proposal is to add two new keywords immutable and mutable.

Is immutable meant to become widespread? If it is, isn't it too verbose? (Consider that for nullable reference types, a single character was considered too verbose.) If it isn't, would it be worth implementing?

Good question. In my question, immutable should be widespread as it communicates clear intent to observe and not modify. I don't personally consider it too verbose, but that's opinion-based. The most use I see in method signatures. I'm open to suggestions on shorter ways of saying "only observation allowed".

Some fields are used to track internal state, but not observable logical state. Such fields (e.g. a version property such as in CoreLib's System.Collections.Generic.List<T>) can be marked mutable.

This means that immutable does not imply that the object in question is thread-safe. I think that thread-safety is an important reason why the inconvenience of immutability can be worth it (see e.g. the Roslyn codebase), but this proposal does not attempt to do that. Is that the right approach?

I personally value thread-safety a lot, so I am open to support that immutable can be equivalent to thread-safety. However, it might be too restrictive for adding this to existing code bases.

Any Type<T> can be cast to a Type<immutable T>, but not vice-versa.

I don't think that would be safe. Consider:

void Sneaky(immutable Foo foo)
{
    List<Foo> listOfMutable = new List<Foo>();
    List<immutable Foo> listOfImmutable = listOfMutable;
    listOfImmutable.Add(foo);
    listOfMutable[0].Property = 42;
}

Thanks to that cast from List<Foo> to List<immutable Foo>, I was able to mutate an immutable object.

Correct and as intended. immutable does not promise that the observed objects cannot ever change, it only guarantees that it won't be through that part of the content (this also relates to the thread-safety aspect: immutable guarantees that it won't be the source of changes to some object, but another thread may still concurrently modify the object.

static void Thread1(Foo foo)
{
    foo.Modify();
}
static void Thread2(immutable Foo foo)
{
   foo.Observe();
}
void Start(Foo foo)
{
    new Thread(() => Thread1(foo).)Start();
    new Thread(() => Thread2(foo).)Start();
}

The immutable modifier to methods can be inferred through static code analysis.

I think this could be a trap for libraries. If the compiler infers that a method is immutable, and I later need to modify it to make it mutable, it would be a breaking change. Or does this mean that library authors would be recommended to explicitly mark every method as mutable, unless they made sure that the method can stay immutable in the future?

Good point about breaking changes. Potentially, the static code analysis for immutability should only used for tooling that facilitates adding immutable.

+public T immutable this[int index] { get; set; }

What does it mean for a property with a setter to be immutable? Does that modifier only apply to the getter?

In this example, the data of a list will not be considered changed when an element is changed. The modifier here refers to the state of the class (this), not the returned object (T).

public int BinarySearch(T item, IComparer<T> comparer);
+public int immutable BinarySearch(immutable T item, IComparer <immutable T> comparer); 

This raises the question of how immutable would be represented in metadata. The obvious answer is to use attributes, but those are not considered to be part of method signature, so you couldn't have both of the methods above at the same time.

An alternative would be to use modopt or modreq, which I think would allow this kind of overloading. But then, what would happen if I wrote code like the above and then attempted to use it from a language that didn't understand immutable (including older versions of C#)?

C++ name mangling comes to mind, but doesn't feel right. Definitely something to be discussed.

Thanks for all the points you raised @svick!

[svick]

Thanks to that cast from List<Foo> to List<immutable Foo>, I was able to mutate an immutable object.

Correct and as intended. immutable does not promise that the observed objects cannot ever change, it only guarantees that it won't be through that part of the content

I understand that this kind of feature can't guarantee much. But I think that if I a method receives an immutable object, it should not be able to mutate it without using any "unsafe" code (like mutable!). As proposed, I worry it would lead to mutating immutable objects by accident and I think that would make the feature much less useful.

What does it mean for a property an indexer with a setter to be immutable? Does that modifier only apply to the getter?

In this example, the data of a list will not be considered changed when an element is changed. The modifier here refers to the state of the class (this), not the returned object (T).

You also said that immutable applies transitively. But here it seems you're saying that immutable List<Foo> is an immutable list of mutable objects. I don't understand how can you have both at the same time.

But that's not really what I was asking. As I understand it, if I have an immutable object, I can access its immutable members. And since the whole indexer is immutable, does that mean the setter is always accessible? Or does the immutable modifier on indexers and properties actually apply only to their getters? (Wouldn't that be confusing?)

[yaakov-h]

I feel like this could largely be solved today with a couple attributes and an extension method or two.

However, we already have System.Collections.Immutable for immutable lists etc, including extension methods to create them easily from other collections. We also have IReadOnlyXXX for mutable-but-not-for-you collections.

Your underlying problem seems to be mutability of the element type, but why are current solutions such as .Cast<T> or other extension methods insufficient?

[Nition]

I'd also really appreciate a feature like this, to support writing good code. Current solutions usually involve having to make a copy of a class, or adding a read-only facade.

In terms of immutable being too long, I'm not sure it'd be such a bad idea to just use const like C++, or even readonly. It wouldn't be the only keyword to be used with slightly different meaning in different contexts. The length is indeed somewhat important as ideally you'd want to be using immutable wherever possible. Dare I say, if we were starting the language anew without compatibility concerns, it could even be the default.

[stefanloerwald]

In response to @svick:

Thanks to that cast from List<Foo> to List<immutable Foo>, I was able to mutate an immutable object.

Correct and as intended. immutable does not promise that the observed objects cannot ever change, it only guarantees that it won't be through that part of the content

I understand that this kind of feature can't guarantee much. But I think that if I a method receives an immutable object, it should not be able to mutate it without using any "unsafe" code (like mutable!). As proposed, I worry it would lead to mutating immutable objects by accident and I think that would make the feature much less useful.

I'm afraid you're mistaken: even in your code, immutable lives up to its promise. The modification exclusively occurs through a mutable reference to the data. I would expect only a tiny portion of code containing both a mutable and an immutable reference to data in the same scope.

What does it mean for a property an indexer with a setter to be immutable? Does that modifier only apply to the getter?

In this example, the data of a list will not be considered changed when an element is changed. The modifier here refers to the state of the class (this), not the returned object (T).

You also said that immutable applies transitively. But here it seems you're saying that immutable List<Foo> is an immutable list of mutable objects. I don't understand how can you have both at the same time.

But that's not really what I was asking. As I understand it, if I have an immutable object, I can access its immutable members.

Talking about collections, I see four kinds of options: mutable collection of mutable objects, mutable collection of immutable objects, immutable collection of mutable objects, and immutable collection of immutable objects.
An example for immutable collection of mutable objects:

void ResetCounters(immutable List<Counter> counters)
{
    foreach (var counter in counters)
    {
        counter.Reset(); // modification of element of list
    }
}

[...] And since the whole indexer is immutable, does that mean the setter is always accessible? Or does the immutable modifier on indexers and properties actually apply only to their getters? (Wouldn't that be confusing?)

You are talking here about an immutable collection of mutable objects, which in my opinion is perfectly valid, including the replacement of an element. Note that I'm not proposing to implement immutable-friendly List exactly this way, it simply serves as an example, and the final implementation may make some different design choices.

In response to @yaakov-h:

I feel like this could largely be solved today with a couple attributes and an extension method or two.

However, we already have System.Collections.Immutable for immutable lists etc, including extension methods to create them easily from other collections. We also have IReadOnlyXXX for mutable-but-not-for-you collections.

Your underlying problem seems to be mutability of the element type, but why are current solutions such as .Cast<T> or other extension methods insufficient?

I don't see how the transitivity aspect of immutable can be adequately solved with attributes (e.g. lambdas do not support this), interfaces (c.f. the section about that in the original post), and casts (please provide example if you disagree).

In response to @Nition:

I'd also really appreciate a feature like this, to support writing good code. Current solutions usually involve having to make a copy of a class, or adding a read-only facade.

In terms of immutable being too long, I'm not sure it'd be such a bad idea to just use const like C++, or even readonly. It wouldn't be the only keyword to be used with slightly different meaning in different contexts. The length is indeed somewhat important as ideally you'd want to be using immutable wherever possible. Dare I say, if we were starting the language anew without compatibility concerns, it could even be the default.

I considered readonly until I came across a piece of code that would have needed readonly twice with different meanings. const potentially works (need to think about it more), but doesn't have a natural counterpart (mutable) to make the opposite blatantly explicit.

[franchyd]

@stefanloerwald
Doesn't Any Type<T> can be cast to a Type<immutable T> allow any immutable object to be upgraded to a mutable one by doing generic casts? I.e.

static void Modify(Bar bar)
{
	Bar.Content = “”;
}
static void Test(immutable Foo foo)
{
        MutableImmutable<Foo> mutable = new MutableImmutable<Foo>();
        MutableImmutable<immutable Foo> immutable= mutable;
        immutable.Item = foo;
        Modify(foo.Bar);		// illegal, as Modify expects a mutable Bar
        Modify(mutable.Item.Bar);	// legal for some reason
}

Doesn't that make the whole thing worthless as the immutability is trivially avoided?

[Nition]

I considered readonly until I came across a piece of code that would have needed readonly twice with different meanings.

Good point.

[stefanloerwald]

Doesn't Any Type<T> can be cast to a Type<immutable T> allow any immutable object to be upgraded to a mutable one by doing generic casts? I.e.

static void Modify(Bar bar)
{
	Bar.Content = “”;
}
static void Test(immutable Foo foo)
{
        MutableImmutable<Foo> mutable = new MutableImmutable<Foo>();
        MutableImmutable<immutable Foo> immutable= mutable;
        immutable.Item = foo;
        Modify(foo.Bar);		// illegal, as Modify expects a mutable Bar
        Modify(mutable.Item.Bar);	// legal for some reason
}

Doesn't that make the whole thing worthless as the immutability is trivially avoided?

immutable isn't meant to be non-overridable and yes, you're code sample is valid. You can make it generic:

private class Wrapper<T>
{
    public T Value { get; set; }
}
public static T GetMutableReference<T>(immutable T value)
{
    var wrapper = new Wrapper<T>();
    var immutable_wrapper = wrapper as Wrapper<immutable T>;
    immutable_wrapper.Value = value;
    return wrapper.Value;
}
public void CallSite(immutable Foo foo)
{
    var mutable_reference_to_foo = GetMutableReference(foo);
    mutable_reference_to_foo.Modify();
}

This is trickery to achieve the same as

public void CallSite(immutable Foo foo)
{
    var mutable_reference_to_foo = mutable! foo;
    mutable_reference_to_foo.Modify();
}

So yep, this code is possible and it's not ideal: you can shoot yourself in the foot, but regardless of whether you use the trickery boilerplate code or mutable!, it's a rather explicit decision. Sometimes you have to break immutable...
I consider the benefit of implicit cast from Type<T> to Type<immutable T> greater than this loophole.

[asos-richardgibson]

My point of view on this topic is that, while I'm very happy to see others asking for language-level immutability controls to be added to the language, I'm not in favour of being able to tag individual references as immutable or not; as we've seen from the comments it's rife with loopholes and inconsistencies.

Another thing: if we're going to do immutability properly I don't think we should be using the same mutable types; a read/write list and a read-only list will probably be implemented completely differently, especially since a read-only list is going to want to have some kind of copy-and-update functionality.

[stefanloerwald]

My point of view on this topic is that, while I'm very happy to see others asking for language-level immutability controls to be added to the language, I'm not in favour of being able to tag individual references as immutable or not; as we've seen from the comments it's rife with loopholes and inconsistencies.

The one loophole that was discovered (let's call it "promotion of immutable T to T through generics trickery") is a trade-off between full safety and convenience of (implicit) casts from Type<T> to Type<immutable T>. At the same time, there pretty much has to be a way to override immutable anyway, so it's only a code smell if people use the trick instead of the clean solution. I would be surprised if people accidentally work around immutable with this trick.

Another thing: if we're going to do immutability properly I don't think we should be using the same mutable types; a read/write list and a read-only list will probably be implemented completely differently, especially since a read-only list is going to want to have some kind of copy-and-update functionality.

With this proposed feature, you'd get an implementation of a read-only type for free, including casts, that is a reduction (talking about the types' interface) of the original type. Nothing stops you from writing explicitely different types, should functionality need to be different. I don't see a good argument to implement things like list completely different mutable vs immutable. Could you please elaborate on that, @asos-richardgibson? What can you implement better in the immutable version, that wouldn't also work in the mutable version?