Iterator Design Pattern

public final class Playlist implements Iterable<Track> {

    private final Node head;

    @Override public Iterator<Track> iterator() {
        return new Iterator<>() {
            private Node cursor = head;      // position lives HERE, not in Playlist

            @Override public boolean hasNext() { return cursor != null; }

            @Override public Track next() {
                if (cursor == null) throw new NoSuchElementException();
                Track track = cursor.track;
                cursor = cursor.next;
                return track;
            }
        };
    }
}

// Implementing Iterable is what earns you the for-each syntax:
for (Track track : playlist) {
    play(track);
}

// The JDK's collections are FAIL-FAST, and it's worth knowing why. Each
// iterator remembers the collection's modCount when it was created; if the
// collection is structurally modified while you're walking it, next() throws
// ConcurrentModificationException:
//
//     for (Track t : playlist)
//         if (t.isExplicit()) playlist.remove(t);   // throws
//
// Use it.remove(), removeIf(), or collect and remove afterwards. Note the name
// is misleading — a single thread triggers it just as easily as two.

class Playlist:
    def __init__(self, head: Node | None) -> None:
        self._head = head

    def __iter__(self):
        """A generator IS an iterator — Python hands you the whole pattern.

        No class, no hasNext, no state machine: the `yield` suspends the
        function and resumes it on the next call, so local variables are the
        cursor. This is the idiomatic answer and almost always the right one.
        """
        node = self._head
        while node is not None:
            yield node.track
            node = node.next


for track in playlist:
    play(track)


# The tree walk is where generators really earn it — `yield from` recurses with
# no explicit stack at all:
#
#     def __iter__(self):
#         for child in self._children:
#             if isinstance(child, Playlist):
#                 yield from child          # recursion, one keyword
#             else:
#                 yield child
#
# And laziness is free: itertools.islice(playlist, 10) fetches ten tracks and
# stops, even if the source is a paginated API with a thousand pages.

class Playlist {
public:
    class iterator {
    public:
        using iterator_category = std::forward_iterator_tag;
        using value_type = Track;
        using difference_type = std::ptrdiff_t;

        explicit iterator(Node* n) : node_(n) {}

        const Track& operator*()  const { return node_->track; }
        iterator& operator++()          { node_ = node_->next; return *this; }
        bool operator!=(const iterator& o) const { return node_ != o.node_; }

    private:
        Node* node_;
    };

    iterator begin() { return iterator{head_}; }
    iterator end()   { return iterator{nullptr}; }

private:
    Node* head_;
};

// begin()/end() is all the range-based for loop needs:
for (const auto& track : playlist) play(track);

// Two things C++ makes explicit that other languages hide. First, the ITERATOR
// CATEGORY is part of the contract — a forward iterator cannot be used by an
// algorithm that needs random access, and the compiler enforces it. Second,
// INVALIDATION is precisely specified: vector::push_back may reallocate and
// invalidate every iterator, while list::insert invalidates none. Iterating a
// container you're modifying is undefined behaviour, not an exception.
//
// C++20 ranges make composition first-class:
//   for (const auto& t : playlist | std::views::filter(clean) | std::views::take(10))

public sealed class Playlist : IEnumerable<Track>
{
    private readonly Node? _head;

    // `yield return` builds the state machine for you — the compiler generates
    // a full IEnumerator class from this method.
    public IEnumerator<Track> GetEnumerator()
    {
        for (var node = _head; node is not null; node = node.Next)
            yield return node.Track;
    }

    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
}

foreach (var track in playlist) Play(track);

// LINQ is lazy for the same reason: Where and Select return iterators, and
// nothing runs until something enumerates them.
var firstTen = playlist.Where(t => !t.Explicit).Take(10);   // no work yet
foreach (var t in firstTen) Play(t);                        // now it walks

// The classic trap that follows from deferred execution: enumerating twice
// re-runs the whole query, so a query over a paginated API hits the network
// again. `.ToList()` once, or accept the second walk deliberately.
//
// IAsyncEnumerable<T> and `await foreach` are the paginated case done properly —
// each MoveNextAsync may await a page without blocking a thread.

class Playlist {
  #head

  constructor(head) { this.#head = head }

  // A generator method satisfies the iterable protocol in three lines.
  *[Symbol.iterator]() {
    for (let node = this.#head; node; node = node.next) {
      yield node.track
    }
  }
}

for (const track of playlist) play(track)

// Anything with [Symbol.iterator] works with for...of, spread and destructuring:
const [first, second] = playlist
const all = [...playlist]        // careful: this fully drains a lazy source

// The paginated case is an ASYNC iterator, and the syntax mirrors it exactly:
const tracks = {
  async *[Symbol.asyncIterator]() {
    let page = 1
    while (page) {
      const res = await fetch(`/tracks?page=${page}`).then(r => r.json())
      yield* res.items
      page = res.nextPage
    }
  },
}

for await (const track of tracks) play(track)

// Note that `[...tracks]` on an infinite or very large source hangs forever —
// spread is eager, and the whole point of the iterator was that it needn't be.

package playlist

// Until Go 1.23 the language had no iterator interface at all, and the idiom was
// a callback: give me a function, I'll call it for each element.
func (p *Playlist) Each(fn func(Track) bool) {
	for node := p.head; node != nil; node = node.next {
		if !fn(node.track) {
			return                    // returning false stops the walk early
		}
	}
}

// Go 1.23 turned exactly that shape into a language feature: a function of type
// iter.Seq[V] can be used directly in a range loop.
func (p *Playlist) All() iter.Seq[Track] {
	return func(yield func(Track) bool) {
		for node := p.head; node != nil; node = node.next {
			if !yield(node.track) {
				return
			}
		}
	}
}

// for track := range playlist.All() { play(track) }
//
// iter.Seq2[K, V] is the two-value form, which is how maps.All and slices.All
// give you index/value or key/value pairs.
//
// The paginated case returns iter.Seq2[Track, error], because a walk that can
// fail must say so — Go won't let you hide a network error inside next().

class Playlist implements Iterable<Track> {
  #head: Node | null

  constructor(head: Node | null) { this.#head = head }

  *[Symbol.iterator](): Iterator<Track> {
    for (let node = this.#head; node; node = node.next) {
      yield node.track
    }
  }
}

for (const track of playlist) play(track)

// Typing the paginated source says the important thing in the signature: this
// walk is asynchronous, so every caller has to acknowledge it.
async function* pagedTracks(): AsyncGenerator<Track> {
  let page: number | null = 1
  while (page !== null) {
    const res: Page<Track> = await api.get(`/tracks?page=${page}`)
    yield* res.items
    page = res.nextPage
  }
}

// A generic helper that works over any iterable, sync or not — the payoff for
// the collection having disappeared behind the interface:
async function take<T>(source: AsyncIterable<T>, n: number): Promise<T[]> {
  const out: T[] = []
  for await (const item of source) {
    out.push(item)
    if (out.length === n) break        // stops the source mid-page
  }
  return out
}