Fast Immutable Collections (FIC)

A ListSet is a hybrid collection that acts as both a mutable, fixed-sized, ordered Set and a mutable, fixed-sized List where values cannot repeat.

Key Characteristics:

• Performance: Similar to LinkedHashSet for set operations, but uses less memory.
• Indexing: Supports efficient constant-time access by index.
• Ordering: Can be sorted or rearranged like a list.
• Limitation: It has a fixed size (unlike LinkedHashSet).

Use ListSet when you need a set that maintains order, allows efficient index-based access, and requires less memory than a standard LinkedHashSet.

ListSet<int> listSet = ListSet.of([1, 2, 3]);
expect(listSet[2], 3); // List behavior
expect(listSet.contains(2), isTrue); // Set behavior

List<int> list = listSet;
Set<int> set = listSet;

The library provides specialized immutable list types for small, fixed numbers of elements to improve performance and clarity:

• IListOf2<T>: Contains exactly 2 items, accessible via .first and .last.
• IListOf3<T>: Contains exactly 3 items, accessible via .first, .second, and .third.
• IListOf4<T>: Contains exactly 4 items, accessible via .first, .second, .third, and .fourth.

While Dart cannot strictly prevent subclassing (which could introduce mutability), you can follow these 5 rules to create effectively immutable objects:

1. Make all immutable fields final or private so they cannot be changed.
2. Make all mutable fields private to prevent direct external access.
3. Create defensive copies of all mutable fields passed to the constructor to prevent external modification of the internal state.
4. Do not provide methods that grant external access to internal mutable fields.
5. Do not provide methods that change fields, except for safe internal uses like lazy initialization or caching.

Best Practice for Subclassing: To get as close to strict immutability as possible, avoid invoking public non-static methods from the constructor, as these can be overridden in subclasses to return different values.

A ListMap is a mutable, fixed-sized, and ordered map.

Key Characteristics:

• Ordering: Maintains order like a LinkedHashMap.
• Memory: Uses less memory than a LinkedHashMap.
• Performance: Slightly slower than LinkedHashMap for key-based retrieval.
• List-like features: Provides efficient sort and shuffle methods, and allows efficient access by index via entryAt, keyAt, and valueAt.
• Limitation: It has a fixed size (unlike LinkedHashMap).

When using the .lock extension, Dart's type inference might result in a more specific type than expected.

• [Dog()].lock results in IList<Dog>.
• If you need a more general type, specify the type explicitly: <Animal>[Dog()].lock results in IList<Animal>.

This behavior is consistent with how Dart handles list literals, where [Dog()] is inferred as List<Dog>.

IList<Animal> ilist1 = [Dog()].lock;       // IList<Dog>
IList<Animal> ilist2 = <Animal>[Dog()].lock; // IList<Animal>

In Dart, List.unmodifiable() creates an unmodifiable list, which is a read-only view. While it prevents mutation via its own methods (throwing errors instead), it does not guarantee that the underlying data won't change if another reference to the same data exists. This can lead to confusion and bugs.

In contrast, Immutability in fast_immutable_collections is a guarantee that the object cannot be mutated. To enforce this at the type level, IList (and other FIC collections) does not extend List. This ensures that if a method accepts an IList, it is mathematically impossible for that method to modify the collection, making the code easier to reason about and providing 'failure atomicity' (objects are never left in an indeterminate state if an exception occurs).

To support both sorted and insertion-ordered sets and maps, FIC implements specialized internal data structures:

• ListSet: Used internally by ISet. It maintains both a HashMap and an array-list (rather than a linked-list). This allows the set to be both sorted and insertion-ordered while remaining memory-efficient and allowing index-based access.
• ListMap: An analogous data structure for maps that uses a HashMap and an array-list internally.

This design differs from standard implementations like Java's LinkedHashMap, which uses a doubly-linked list to manage order. By using an array-list, FIC can optimize for fixed-size or periodically flushed structures.

Unlike regular Dart Lists which compare by identity, ILists compare by deep equality (same items in the same order) by default. This allows IList to be used as a key in a Map.

Comparison Methods

• equalItems: Returns true if items are equal and in the same order (can be slow for large lists).
• unorderedEqualItems: Returns true if items are the same regardless of order.
• equalItemsAndConfig: Returns true if items are equal, in order, AND the list configurations match.
• same: Returns true if the internal state (not necessarily the exact instance) is the same. This is a fast identity-based check.

var ilist1 = [1, 2, 3].lock;
var ilist2 = [1, 2, 3].lock;

print(identical(ilist1, ilist2)); // False
print(ilist1 == ilist2);        // True (Deep equality)