> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Dart Iterable An `Iterable` in Dart is an abstract class representing a sequence of elements that can be accessed sequentially. It serves as the foundational interface for collections like `List` and `Set`, defining the contract for traversing elements without exposing the underlying data structure's implementation details. ## The Iterator Mechanism An `Iterable` itself does not maintain iteration state. Instead, it provides an `iterator` getter that returns an `Iterator` object. The `Iterator` is responsible for maintaining the cursor position and traversing the sequence using `moveNext()` and `current`. ```dart theme={"dark"} Iterable numbers = [1, 2, 3]; Iterator iterator = numbers.iterator; while (iterator.moveNext()) { print(iterator.current); } ``` ## Lazy Evaluation A defining characteristic of Dart's `Iterable` methods (such as `map`, `where`, `expand`, and `take`) is lazy evaluation. Invoking these methods does not immediately process the elements or allocate memory for a new collection. Instead, they return a new `Iterable` that wraps the original one. The computation is deferred until the elements are explicitly consumed (e.g., via a `for-in` loop, `.toList()`, or `.length`). ```dart theme={"dark"} Iterable baseIterable = [1, 2, 3, 4]; // No computation happens here. Returns a MappedIterable. Iterable lazyMapped = baseIterable.map((n) { print('Processing $n'); return n * 2; }); // Computation is triggered here during consumption. List materializedList = lazyMapped.toList(); ``` ## Synchronous Generators Dart provides language-level support for constructing custom `Iterable` sequences using synchronous generator functions. By marking a function with `sync*` and using the `yield` keyword, the Dart compiler automatically generates the underlying `Iterable` and `Iterator` boilerplate. ```dart theme={"dark"} Iterable generateSequence(int max) sync* { for (int i = 0; i < max; i++) { yield i; // Emits a single value to the Iterable } } Iterable recursiveSequence(int max) sync* { if (max > 0) { yield max; yield* recursiveSequence(max - 1); // Delegates to another Iterable } } ``` ## Structural Characteristics 1. **Immutability of Interface:** The base `Iterable` class exposes a strictly read-only view. It defines accessors (`first`, `last`, `elementAt`) and transformation methods, but lacks mutator methods (`add`, `remove`). Mutation is strictly the domain of concrete subclasses like `List`. 2. **Iteration Behavior:** The Dart `Iterable` contract explicitly requires that iterables can be iterated multiple times. Each time the `.iterator` getter is accessed, it must return a new, independent `Iterator` that starts from the beginning of the sequence. However, while multiple passes are guaranteed to be possible, the elements yielded—or their order—are not strictly required to be identical across iterations if the `Iterable` is backed by impure functions, randomized logic, or changing external state (such as those created via `Iterable.generate` or `sync*`). 3. **Length Computation:** Because iterables can be lazily generated or infinite, accessing the `.length` property on an unmaterialized `Iterable` operates in $O(n)$ time, requiring a full traversal of the sequence to count the elements, unless overridden by a concrete subclass (like `List`) to operate in $O(1)$ time.

Tired of Poor Dart Skills? Fix That With Deep Grasping! Learn More