Dart — Collections, Iterables & Allocation Patterns

// map/where/expand return LAZY Iterables — no computation until iterated.
// Each `.toList()` materializes the chain (one allocation, one pass).

// ❌ Anti-pattern: calling .toList() after every step (multiple allocations).
var result = numbers
    .map((n) => n * 2)      // lazy Iterable
    .toList()                // ← allocates a List here (premature)
    .where((n) => n > 5)    // lazy Iterable (on a List, re-iterates)
    .toList()                // ← another allocation
    .map((n) => n.toString()) // lazy
    .toList();               // ← yet another

// ✓ Correct: chain lazy operations, materialize ONCE at the end.
var resultFixed = numbers
    .map((n) => n * 2)       // lazy
    .where((n) => n > 5)     // lazy
    .map((n) => n.toString()) // lazy
    .toList();               // single allocation, single pass

// Lazy iterables re-evaluate on each iteration — no caching:
var numbers = [1, 2, 3];
var doubled = numbers.map((n) { print('mapping $n'); return n * 2; });
doubled.toList();  // prints: mapping 1, mapping 2, mapping 3
doubled.toList();  // prints again: mapping 1, mapping 2, mapping 3 (re-evaluated!)
// If the mapping is expensive, cache with .toList() and reuse the list.

// ❌ Anti-pattern: assigning the result of sort() — it returns void.
var sorted = [3, 1, 2].sort();  // sorted is void! sort() is in-place.
print(sorted);  // null (or compile error in strict mode)

// ✓ Correct: sort a copy (don't mutate the original).
var numbers = [3, 1, 2];
var sorted = [...numbers]..sort();  // spread creates a copy, cascade sorts it
print(sorted);   // [1, 2, 3]
print(numbers);  // [3, 1, 2] — original unchanged

// Custom comparator — for descending or multi-field sort:
var users = [
  (name: 'Alice', age: 30),
  (name: 'Bob', age: 25),
  (name: 'Alice', age: 25),
];

// Sort by name (asc), then by age (desc):
users.sort((a, b) {
  final nameCmp = a.name.compareTo(b.name);
  if (nameCmp != 0) return nameCmp;
  return b.age.compareTo(a.age);  // descending age
});
// [(name: Alice, age: 30), (name: Alice, age: 25), (name: Bob, age: 25)]

// Comparable<T> — for types with a natural ordering:
class Priority implements Comparable<Priority> {
  final int level;
  const Priority(this.level);
  @override
  int compareTo(Priority other) => level.compareTo(other.level);
}
var tasks = [Priority(3), Priority(1), Priority(2)];
tasks.sort();  // uses compareTo — [1, 2, 3]

// Spread (...) flattens another iterable into a literal.
// Null-aware spread (...?) skips if the iterable is null.
var base = [1, 2, 3];
var extended = [0, ...base, 4];  // [0, 1, 2, 3, 4]

List<int>? maybeNull;
var safe = [0, ...?maybeNull, 4];  // [0, 4] — null spread is a no-op

// Collection-if — conditional elements in a literal (Flutter widget trees):
var widgets = <Widget>[
  Text('Header'),
  if (showAd) BannerAd(),           // included only if showAd is true
  if (user != null) ...[
    ProfilePic(user!),
    UserName(user!),
  ],                                 // spread a conditional group
  if (items.isEmpty)
    EmptyState()
  else
    ...items.map((i) => ItemWidget(i)),  // if-else in a collection literal
];

// Collection-for — programmatic elements:
var indices = [for (var i = 0; i < 5; i++) 'item-$i'];
// ['item-0', 'item-1', 'item-2', 'item-3', 'item-4']

// Nested — build complex structures declaratively:
var matrix = [
  for (var r = 0; r < 3; r++)
    [for (var c = 0; c < 3; c++) r * 3 + c]
];
// [[0,1,2], [3,4,5], [6,7,8]]

// ── const: compile-time, deeply immutable, canonicalized ──
const colors = ['red', 'green'];  // same instance everywhere, zero allocation
// colors.add('blue');  // ✗ UnsupportedError

// ── List.unmodifiable: runtime, throws on mutation, but is a VIEW ──
var source = [1, 2, 3];
var view = List.unmodifiable(source);
// view.add(4);  // ✗ UnsupportedError
source.add(4);
print(view);  // [1, 2, 3, 4] — view reflects source mutation!

// ✓ For a true immutable copy: wrap a copy, not the source.
var immutable = List.unmodifiable([...source]);  // copy then wrap
source.add(5);
print(immutable);  // [1, 2, 3, 4] — unaffected by source mutation after copy

// ── Set.unmodifiable / Map.unmodifiable: same semantics ──
var setView = Set.unmodifiable({1, 2, 3});
var mapView = Map.unmodifiable({'a': 1, 'b': 2});

// For persistent (structural sharing) immutable collections, use packages:
// - package:built_collection — persistent immutable List/Map/Set
// - package:fast_immutable_collections — high-performance persistent collections

// reduce: combines elements, NO initial value — throws on empty.
// ❌ Anti-pattern: reduce on a possibly-empty list.
int sum(List<int> nums) => nums.reduce((a, b) => a + b);  // throws StateError on []
sum([]);  // Uncaught Error: Bad state: no element

// ✓ Correct: fold with an initial value — safe on empty.
int sumSafe(List<int> nums) => nums.fold(0, (a, b) => a + b);  // 0 on empty
sumSafe([]);  // 0

// fold with a different initial type (e.g., building a string):
String csv = [1, 2, 3].fold('', (acc, n) => acc.isEmpty ? '$n' : '$acc,$n');
// '1,2,3'

// reduce's return type matches the element type:
var max = [3, 1, 4, 1, 5].reduce((a, b) => a > b ? a : b);  // 5 (int)

// For first/last/single on possibly-empty: use firstWhere with orElse:
var first = [1, 2, 3].firstWhere((n) => n > 5, orElse: () => -1);  // -1

// Built-in collections use IDENTITY for ==, not value equality.
print([1, 2] == [1, 2]);  // false — different instances
print({1, 2} == {1, 2});  // false
print({'a': 1} == {'a': 1});  // false

// ❌ Anti-pattern: using == to compare collection contents.
bool sameContent(List<int> a, List<int> b) => a == b;  // always false for distinct lists

// ✓ Correct: use listEquals / setEquals / mapEquals (Flutter) or DeepCollectionEquality.
import 'package:flutter/foundation.dart';
print(listEquals([1, 2], [1, 2]));  // true

import 'package:collection/collection.dart';
const deepEq = DeepCollectionEquality();
print(deepEq.equals([1, [2, 3]], [1, [2, 3]]));  // true — nested deep equality
print(deepEq.equals({'a': [1, 2]}, {'a': [1, 2]}));  // true

// Records have structural equality built in:
print((1, 2) == (1, 2));  // true — records compare by value, no helper needed
print((x: 1, y: 2) == (x: 1, y: 2));  // true

var numbers = [1, 2, 3, 4, 5];
var result = numbers
    .map((n) { print('mapping $n'); return n * 2; })
    .where((n) => n > 4);

print(result.first);  // prints: mapping 1, mapping 2, mapping 3 → 6
print(result.last);   // prints: mapping 1, mapping 2, mapping 3, mapping 4, mapping 5 → 10