Net4x.Collections.Immutable 1.0.0.26251

Net4x.Collections.Immutable

System.Collections.Immutable back-ported to .NET Framework 3.5, 4.0, 4.5 and 4.7.2.

The official System.Collections.Immutable package stopped supporting .NET Framework below 4.6.2 and never supported 3.5 or 4.0 at all. This package provides the same types, in the same namespaces, with the same signatures — so code written against the modern API compiles and runs unchanged on legacy targets.

dotnet add package Net4x.Collections.Immutable

Target frameworks

Because the netstandard2.0 asset forwards to the official package, a project that multi-targets legacy and modern frameworks gets the real implementation where one exists and the back-port only where it doesn't.

On .NET Framework 4.6.2 and later the Span<T>-based overloads resolve against System.Memory; on 3.5/4.0/4.5 they resolve against the polyfill in Net4x.BaseExtensions. Reference the net472 asset (or newer) from any project targeting 4.6.2+ so the two do not mix.

What's included

Everything from the System.Collections.Immutable surface area:

The IImmutableList<T>, IImmutableDictionary<TKey,TValue>, IImmutableSet<T>, IImmutableStack<T> and IImmutableQueue<T> interfaces are included too, along with the classic IList/IDictionary/ISet implementations, so the collections can be handed to APIs that predate them.

Usage

using System.Collections.Immutable;

// Arrays — a struct wrapping T[]; every operation returns a new instance.
var numbers = ImmutableArray.Create(1, 2, 3);
var more    = numbers.Add(4);            // numbers is still [1, 2, 3]

// Lists — an AVL tree, so Add/Insert/Remove are O(log n) and share structure.
var list = ImmutableList.Create("a", "b").Insert(1, "middle");

// Dictionaries and sets, with an optional comparer.
var map = ImmutableDictionary.Create<string, int>(StringComparer.OrdinalIgnoreCase)
                             .Add("One", 1);
bool found = map.ContainsKey("ONE");     // true — the comparer is honoured

var set = ImmutableSortedSet.Create(3, 1, 2);   // enumerates 1, 2, 3

// Stacks and queues.
var stack = ImmutableStack<int>.Empty.Push(1).Push(2);   // Peek() == 2
var queue = ImmutableQueue<int>.Empty.Enqueue(1).Enqueue(2); // Peek() == 1

Builders

Applying many changes one at a time allocates one collection per change. A Builder batches them and produces a single immutable result:

var builder = ImmutableList.CreateBuilder<int>();
foreach (var item in source)
{
    builder.Add(item);
}
ImmutableList<int> result = builder.ToImmutable();

Every collection offers CreateBuilder(...) on its static class and ToBuilder() on an existing instance.

Lock-free updates

ImmutableInterlocked swaps immutable values into a field with a compare-and-exchange loop, giving you a concurrent collection without a lock:

private ImmutableDictionary<string, Session> _sessions = ImmutableDictionary<string, Session>.Empty;

public Session GetOrCreate(string id) =>
    ImmutableInterlocked.GetOrAdd(ref _sessions, id, key => new Session(key));

LINQ without allocating

System.Linq.ImmutableArrayExtensions shadows the common Enumerable operators for ImmutableArray<T>, avoiding the enumerator boxing you would otherwise pay for:

using System.Linq;

var evens = ImmutableArray.Create(1, 2, 3, 4).Where(x => x % 2 == 0);
var total = ImmutableArray.Create(1, 2, 3).Aggregate((a, b) => a + b);

Behavioural notes

These match the official implementation and surprise people often enough to be worth stating:

• default(ImmutableArray<T>) is not ImmutableArray<T>.Empty. It has no backing array; IsDefault is true and most members throw. Use ImmutableArray<T>.Empty for an empty array.
• ImmutableArray<T> equality is reference equality of the backing array, not element-by-element. For a structural comparison use IStructuralEquatable or SequenceEqual.
• Aggregate without a seed returns default(T) for an empty array rather than throwing, unlike Enumerable.Aggregate.
• Add(key, value) on a dictionary is a no-op if the identical pair is already present and throws ArgumentException only when the key exists with a different value. Use SetItem to overwrite.
• Operations that change nothing return the same instance — Remove of an absent item, Add of an item a set already contains, and so on.

Building from source

The net35 target needs the desktop ResGen.exe, so a full build has to run under Visual Studio's MSBuild; the dotnet CLI can build every other target (dotnet build -f net472).

License

Apache-2.0. See LICENSE.