Iterable abstract class

A collection of values, or "elements", that can be accessed sequentially.

The elements of the iterable are accessed by getting an Iterator using the iterator getter, and using it to step through the values. Stepping with the iterator is done by calling Iterator.moveNext, and if the call returns true, the iterator has now moved to the next element, which is then available as Iterator.current. If the call returns false, there are no more elements, and iterator.current returns null.

You can create more than one iterator from the same Iterable. Each time iterator is read, it returns a new iterator, and different iterators can be stepped through independently, each giving access to all the elements of the iterable. The iterators of the same iterable should provide the same values in the same order (unless the underlying collection is modified between the iterations, which some collections allow).

You can also iterate over the elements of an Iterable using the for-in loop construct, which uses the iterator getter behind the scenes. For example, you can iterate over all of the keys of a Map, because Map keys are iterable.

Map kidsBooks = {'Matilda': 'Roald Dahl',
                 'Green Eggs and Ham': 'Dr Seuss',
                 'Where the Wild Things Are': 'Maurice Sendak'};
for (var book in kidsBooks.keys) {
  print('$book was written by ${kidsBooks[book]}');
}

The List and Set classes are both Iterable, as are most classes in the dart:collection library.

Some Iterable collections can be modified. Adding an element to a List or Set will change which elements it contains, and adding a new key to a Map changes the elements of Map.keys. Iterators created after the change will provide the new elements, and may or may not preserve the order of existing elements (for example, a HashSet may completely change its order when a single element is added).

Changing a collection while it is being iterated is generally not allowed. Doing so will break the iteration, which is typically signalled by throwing a ConcurrentModificationError the next time Iterator.moveNext is called. The current value of Iterator.current getter should not be affected by the change in the collection, the current value was set by the previous call to Iterator.moveNext.

Some iterables compute their elements dynamically every time they are iterated, like the one returned by Iterable.generate or the iterable returned by a sync* generator function. If the computation doesn't depend on other objects that may change, then the generated sequence should be the same one every time it's iterated.

The members of Iterable, other than iterator itself, work by looking at the elements of the iterable. This can be implemented by running through the iterator, but some classes may have more efficient ways of finding the result (like last or length on a List, or contains on a Set).

The methods that return another Iterable (like map and where) are all lazy - they will iterate the original (as necessary) every time the returned iterable is iterated, and not before.

Since an iterable may be iterated more than once, it's not recommended to have detectable side-effects in the iterator. For methods like map and where, the returned iterable will execute the argument function on every iteration, so those functions should also not have side effects.

Implemented by

Constructors

Iterable() const
Iterable.empty() const factory: Creates an empty iterable.
Iterable.generate(int count, [ E generator(int index) ]) factory: Creates an Iterable which generates its elements dynamically.

Properties

first → E read-only: Returns the first element.
isEmpty → bool read-only: Returns true if there are no elements in this collection.
isNotEmpty → bool read-only: Returns true if there is at least one element in this collection.
iterator → Iterator<E> read-only: Returns a new Iterator that allows iterating the elements of this Iterable.
last → E read-only: Returns the last element.
length → int read-only: Returns the number of elements in this.
single → E read-only: Checks that this iterable has only one element, and returns that element.
hashCode → int read-only, inherited: The hash code for this object.
runtimeType → Type read-only, inherited: A representation of the runtime type of the object.

Operators

operator ==(other) → bool inherited: The equality operator.

Methods

any(bool f(E element)) → bool: Checks whether any element of this iterable satisfies test.
contains(Object element) → bool: Returns true if the collection contains an element equal to element.
elementAt(int index) → E: Returns the indexth element.
every(bool f(E element)) → bool: Checks whether every element of this iterable satisfies test.
expand<T>(Iterable<T> f(E element)) → Iterable<T>: Expands each element of this Iterable into zero or more elements.
firstWhere(bool test(E element), { E orElse() }) → E: Returns the first element that satisfies the given predicate test.
fold<T>(T initialValue, T combine(T previousValue, E element)) → T: Reduces a collection to a single value by iteratively combining each element of the collection with an existing value
forEach(void f(E element)) → void: Applies the function f to each element of this collection in iteration order.
join([String separator = "" ]) → String: Converts each element to a String and concatenates the strings.
lastWhere(bool test(E element), { E orElse() }) → E: Returns the last element that satisfies the given predicate test.
map<T>(T f(E e)) → Iterable<T>: Returns a new lazy Iterable with elements that are created by calling f on each element of this Iterable in iteration order.
reduce(E combine(E value, E element)) → E: Reduces a collection to a single value by iteratively combining elements of the collection using the provided function.
singleWhere(bool test(E element)) → E: Returns the single element that satisfies test.
skip(int count) → Iterable<E>: Returns an Iterable that provides all but the first count elements.
skipWhile(bool test(E value)) → Iterable<E>: Returns an Iterable that skips leading elements while test is satisfied.
take(int count) → Iterable<E>: Returns a lazy iterable of the count first elements of this iterable.
takeWhile(bool test(E value)) → Iterable<E>: Returns a lazy iterable of the leading elements satisfying test.
toList({bool growable: true }) → List<E>: Creates a List containing the elements of this Iterable.
toSet() → Set<E>: Creates a Set containing the same elements as this iterable.
toString() → String: Returns a string representation of (some of) the elements of this.
where(bool test(E element)) → Iterable<E>: Returns a new lazy Iterable with all elements that satisfy the predicate test.
noSuchMethod(Invocation invocation) → dynamic inherited: Invoked when a non-existent method or property is accessed.

© 2012 the Dart project authors
Licensed under the Creative Commons Attribution-ShareAlike License v4.0.
https://api.dartlang.org/stable/1.24.3/dart-core/Iterable-class.html