Collections and Iterators

public static class ArrayBasics
{
    public static void Run()
    {
        int[] byLength = new int[3];                  // all elements are default(int) == 0
        int[] byInitializer = { 1, 2, 3 };            // classic array initializer
        int[] explicitly = new int[] { 1, 2, 3 };
        int[] targetTyped = [1, 2, 3];                // collection expression (C# 12) -- preferred

        Console.WriteLine(targetTyped.Length);        // 3
        Console.WriteLine(targetTyped[0]);            // 1
        Console.WriteLine(byLength[2] + byInitializer[2] + explicitly[2]);

        // Array's static helpers cover the everyday operations.
        int[] values = [5, 3, 9, 1];
        Array.Sort(values);
        Console.WriteLine(string.Join(",", values));            // 1,3,5,9
        Console.WriteLine(Array.IndexOf(values, 5));            // 2
        Console.WriteLine(Array.BinarySearch(values, 9));       // 3 -- requires a sorted array

        int[] copy = new int[values.Length];
        Array.Copy(values, copy, values.Length);
        Array.Reverse(copy);
        Console.WriteLine(string.Join(",", copy));              // 9,5,3,1
    }
}

public static class CollectionExpressions
{
    public static void Run()
    {
        int[] array = [1, 2, 3];
        List<int> list = [1, 2, 3];
        Span<int> span = [1, 2, 3];
        ImmutableArray<int> immutable = [1, 2, 3];
        HashSet<int> set = [1, 2, 2, 3];              // duplicates collapse

        int[] head = [1, 2];
        int[] tail = [5, 6];
        int[] joined = [..head, 3, 4, ..tail];        // spread: 1,2,3,4,5,6
        Console.WriteLine(string.Join(",", joined));

        int[] empty = [];
        Console.WriteLine($"{list.Count} {span.Length} {immutable.Length} {set.Count} {empty.Length}");

        // The target type decides -- the same syntax, three different allocations.
        Print([1, 2, 3]);
    }

    private static void Print(ReadOnlySpan<int> values) => Console.WriteLine(values.Length);
}

public static class EverydayCollections
{
    public static void Run()
    {
        var list = new List<string> { "b", "a" };
        list.Add("c");
        list.Insert(0, "z");
        list.Remove("b");
        list.Sort();
        Console.WriteLine(string.Join(",", list));            // a,c,z

        var ages = new Dictionary<string, int> { ["ada"] = 36, ["alan"] = 41 };
        ages["grace"] = 45;                                   // add or overwrite
        Console.WriteLine(ages.TryGetValue("ada", out int age) ? age : -1);         // 36
        Console.WriteLine(ages.GetValueOrDefault("nobody", -1));                    // -1
        Console.WriteLine(ages.ContainsKey("alan"));                                // True

        var seen = new HashSet<int> { 1, 2, 3 };
        Console.WriteLine(seen.Add(3));                       // False -- already present
        seen.UnionWith([3, 4]);
        seen.IntersectWith([2, 3, 4]);
        Console.WriteLine(string.Join(",", seen.Order()));     // 2,3,4

        var queue = new Queue<string>();
        queue.Enqueue("first");
        queue.Enqueue("second");
        Console.WriteLine(queue.Dequeue());                    // first
        Console.WriteLine(queue.Peek());                       // second

        var stack = new Stack<int>([1, 2, 3]);
        Console.WriteLine(stack.Pop());                        // 3

        var jobs = new PriorityQueue<string, int>();
        jobs.Enqueue("low", 10);
        jobs.Enqueue("urgent", 1);
        jobs.Enqueue("medium", 5);
        Console.WriteLine(jobs.Dequeue());                     // urgent -- lowest priority value wins
    }
}

public interface IEnumerableSketch<out T>
{
    IEnumeratorSketch<T> GetEnumerator();
}

public interface IEnumeratorSketch<out T> : IDisposable
{
    T Current { get; }
    bool MoveNext();
}

public static class Iterators
{
    // Each `yield return` hands one element back and suspends; execution resumes here
    // on the next MoveNext() call.
    public static IEnumerable<int> Fibonacci(int count)
    {
        int a = 0, b = 1;
        for (int i = 0; i < count; i++)
        {
            yield return a;
            (a, b) = (b, a + b);
        }
    }

    public static IEnumerable<string> ReadLinesLazily(IEnumerable<string> source)
    {
        foreach (string line in source)
        {
            if (line.Length == 0)
            {
                yield break;              // stop the sequence early
            }

            yield return line.Trim();
        }
    }

    public static void Run()
    {
        Console.WriteLine(string.Join(",", Fibonacci(8)));       // 0,1,1,2,3,5,8,13
        Console.WriteLine(string.Join(",", ReadLinesLazily([" a ", "b", "", "c"])));   // a,b
    }
}

public static class ImmutabilityLevels
{
    public static void Run()
    {
        var mutable = new List<int> { 1, 2, 3 };

        // 1. A read-only VIEW: the caller cannot mutate it, but the underlying list can still change.
        IReadOnlyList<int> view = mutable;
        mutable.Add(4);
        Console.WriteLine(view.Count);                    // 4 -- the view saw the change

        // A defensive wrapper makes the view's read-only-ness explicit at run time too.
        var wrapper = mutable.AsReadOnly();
        Console.WriteLine(wrapper.Count);                 // 4

        // 2. IMMUTABLE: mutation returns a new collection; the original never changes.
        ImmutableList<int> immutable = [1, 2, 3];
        ImmutableList<int> extended = immutable.Add(4);
        Console.WriteLine($"{immutable.Count} {extended.Count}");    // 3 4

        ImmutableArray<int> array = [1, 2, 3];
        Console.WriteLine(array.Length);

        // 3. FROZEN: immutable AND optimised for reads, built once, never updated.
        FrozenDictionary<string, int> frozen = new Dictionary<string, int>
        {
            ["ada"] = 1,
            ["alan"] = 2,
        }.ToFrozenDictionary();
        Console.WriteLine(frozen["ada"]);                 // 1 -- faster lookups than Dictionary

        FrozenSet<string> frozenSet = new[] { "a", "b" }.ToFrozenSet();
        Console.WriteLine(frozenSet.Contains("a"));
    }
}

public static class IndicesAndRanges
{
    public static void Run()
    {
        int[] values = [0, 1, 2, 3, 4, 5];

        Console.WriteLine(values[^1]);                      // 5 -- last element
        Console.WriteLine(values[^2]);                      // 4

        Console.WriteLine(string.Join(",", values[1..4]));   // 1,2,3 -- end is exclusive
        Console.WriteLine(string.Join(",", values[..3]));    // 0,1,2
        Console.WriteLine(string.Join(",", values[3..]));    // 3,4,5
        Console.WriteLine(string.Join(",", values[..]));     // a copy of the whole array

        Index secondFromEnd = ^2;
        Range middle = 1..^1;
        Console.WriteLine(values[secondFromEnd]);            // 4
        Console.WriteLine(string.Join(",", values[middle])); // 1,2,3,4

        // On a List<T>, use CollectionsMarshal or a span; List<T> has no Range indexer.
        List<int> list = [0, 1, 2, 3];
        Console.WriteLine(list[^1]);                         // 3 -- Index works, Range does not
    }
}

public static class SpansAsViews
{
    public static int SumOfMiddle(int[] values)
    {
        ReadOnlySpan<int> span = values;           // no copy
        ReadOnlySpan<int> middle = span[1..^1];    // still no copy -- just offset + length

        int total = 0;
        foreach (int n in middle)
        {
            total += n;
        }
        return total;
    }

    public static void Run()
    {
        Console.WriteLine(SumOfMiddle([1, 2, 3, 4]));    // 5

        // Parsing without allocating substrings.
        ReadOnlySpan<char> line = "name=value".AsSpan();
        int separator = line.IndexOf('=');
        Console.WriteLine($"{line[..separator]} -> {line[(separator + 1)..]}");
    }
}