Skip to content

ImmutableNonEmptyList

Jump to bottom
Ahmad Al-freihat edited this page Jan 1, 2026 · 1 revision

ImmutableNonEmptyList

ImmutableNonEmptyList<T> is an immutable variant where all operations return new instances, making it thread-safe.

Creating

// From values
ImmutableNonEmptyList<int> list = new(1, 2, 3);

// From mutable
NonEmptyList<int> mutable = new(1, 2, 3);
ImmutableNonEmptyList<int> immutable = mutable.ToImmutable();

Modification Operations

All modifications return new instances - the original is never changed:

Append

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<int> appended = list.Append(4);
// list:     [1, 2, 3]     (unchanged)
// appended: [1, 2, 3, 4]  (new instance)

Prepend

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<int> prepended = list.Prepend(0);
// prepended: [0, 1, 2, 3]

SetItem

Update an element at an index:

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<int> updated = list.SetItem(1, 99);
// updated: [1, 99, 3]

Insert

Insert at a position:

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<int> inserted = list.Insert(1, 99);
// inserted: [1, 99, 2, 3]

Remove Operations

Remove operations return null if the result would be empty:

RemoveAt

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<int>? removed = list.RemoveAt(0);
// removed: [2, 3]

ImmutableNonEmptyList<int> single = new(1);
ImmutableNonEmptyList<int>? removedSingle = single.RemoveAt(0);
// removedSingle: null (can't remove last element)

RemoveFirst / RemoveLast

ImmutableNonEmptyList<int> list = new(1, 2, 3);

ImmutableNonEmptyList<int>? withoutFirst = list.RemoveFirst();
// withoutFirst: [2, 3]

ImmutableNonEmptyList<int>? withoutLast = list.RemoveLast();
// withoutLast: [1, 2]

Functional Operations

All functional operations from NonEmptyList<T> are available:

Map

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<string> mapped = list.Map(x => x.ToString());
// mapped: ["1", "2", "3"]

Reverse

ImmutableNonEmptyList<int> list = new(1, 2, 3);
ImmutableNonEmptyList<int> reversed = list.Reverse();
// reversed: [3, 2, 1]

Distinct

ImmutableNonEmptyList<int> list = new(1, 2, 2, 3, 3);
ImmutableNonEmptyList<int> distinct = list.Distinct();
// distinct: [1, 2, 3]

Conversion

To Mutable

ImmutableNonEmptyList<int> immutable = new(1, 2, 3);
NonEmptyList<int> mutable = immutable.ToMutable();
// Now you can modify mutable

From Mutable

NonEmptyList<int> mutable = new(1, 2, 3);
ImmutableNonEmptyList<int> immutable = mutable.ToImmutable();

Thread Safety

ImmutableNonEmptyList<T> is completely thread-safe:

ImmutableNonEmptyList<int> shared = new(1, 2, 3);

// Safe to access from multiple threads
var task1 = Task.Run(() => shared.Append(4));
var task2 = Task.Run(() => shared.Append(5));
var task3 = Task.Run(() => shared.Map(x => x * 2));

// shared is never modified
// Each task creates and returns a new instance

JSON Serialization

Works with System.Text.Json:

ImmutableNonEmptyList<int> list = new(1, 2, 3);
string json = JsonSerializer.Serialize(list);
// Output: [1,2,3]

ImmutableNonEmptyList<int> deserialized =
    JsonSerializer.Deserialize<ImmutableNonEmptyList<int>>(json);

When to Use

Scenario Use
Multi-threaded access ImmutableNonEmptyList<T>
Sharing across components ImmutableNonEmptyList<T>
Functional programming style ImmutableNonEmptyList<T>
Performance-critical mutations NonEmptyList<T>
Local, single-threaded use NonEmptyList<T>

Next Steps

Clone this wiki locally