description

# Iterable<E> class abstract mixin

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. The Iterator.current value must only be used when the most recent call to Iterator.moveNext has returned `true`. If it is used before calling Iterator.moveNext the first time on an iterator, or after a call has returned false or has thrown an error, reading Iterator.current may throw or may return an arbitrary value.

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.

    var 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.

The `Iterable` declaration provides a default implementation, which can be extended or mixed in to implement the `Iterable` interface. It implements every member other than the iterator getter, using the Iterator provided by iterator. An implementation of the `Iterable` interface should provide a more efficient implementation of the members of `Iterable` when it can do so.

Implementers
  - DoubleLinkedQueue
  - LinkedList
  - List
  - ListQueue
  - Queue
  - Runes
  - Set
  - SplayTreeSet
Available extensions
  - EnumByName
  - FutureIterable
  - IterableExtensions
  - IterableToJSIterable
  - NullableIterableExtensions

## Constructors

Iterable()
  const
Iterable.empty()
  Creates an empty iterable.
  const
  factory
Iterable.generate(int count, [E generator(int index)?])
  Creates an `Iterable` which generates its elements dynamically.
  factory
Iterable.withIterator(Iterator<E> iteratorFactory())
  Creates an Iterable from the Iterator factory.
  factory

## Properties

first → E
  The first element.
  no setter
firstOrNull → T?

  Available on Iterable<T>, provided by the IterableExtensions extension

  The first element of this iterator, or `null` if the iterable is empty.
  no setter
hashCode → int
  The hash code for this object.
  no setter inherited
indexed → Iterable<(int, T)>

  Available on Iterable<T>, provided by the IterableExtensions extension

  Pairs of elements of the indices and elements of this iterable.
  no setter
isEmpty → bool
  Whether this collection has no elements.
  no setter
isNotEmpty → bool
  Whether this collection has at least one element.
  no setter
iterator → Iterator<E>
  A new `Iterator` that allows iterating the elements of this `Iterable`.
  no setter
last → E
  The last element.
  no setter
lastOrNull → T?

  Available on Iterable<T>, provided by the IterableExtensions extension

  The last element of this iterable, or `null` if the iterable is empty.
  no setter
length → int
  The number of elements in this Iterable.
  no setter
nonNulls → Iterable<T>

  Available on Iterable<T?>, provided by the NullableIterableExtensions extension

  The non-`null` elements of this iterable.
  no setter
runtimeType → Type
  A representation of the runtime type of the object.
  no setter inherited
single → E
  Checks that this iterable has only one element, and returns that element.
  no setter
singleOrNull → T?

  Available on Iterable<T>, provided by the IterableExtensions extension

  The single element of this iterator, or `null`.
  no setter
toJSIterable → JSIterable<T>

  Available on Iterable<T>, provided by the IterableToJSIterable extension

  A JSIterable wrapper that proxies to the Dart iterable API.
  no setter
wait → Future<List<T>>

  Available on Iterable<Future<T>>, provided by the FutureIterable extension

  Waits for futures in parallel.
  no setter

## Methods

any(bool test(E element)) → bool
  Checks whether any element of this iterable satisfies `test`.
asNameMap() → Map<String, T>

  Available on Iterable<T>, provided by the EnumByName extension

  Creates a map from the names of enum values to the values.
byName(String name) → T

  Available on Iterable<T>, provided by the EnumByName extension

  Finds the enum value in this list with name `name`.
cast<R>() → Iterable<T>
  A view of this iterable as an iterable of `R` instances.
contains(Object? element) → bool
  Whether the collection contains an element equal to `element`.
elementAt(int index) → E
  Returns the `index`th element.
elementAtOrNull(int index) → T?

  Available on Iterable<T>, provided by the IterableExtensions extension

  The element at position `index` of this iterable, or `null`.
every(bool test(E element)) → bool
  Checks whether every element of this iterable satisfies `test`.
expand<T>(Iterable<T> toElements(E element)) → Iterable<T>
  Expands each element of this Iterable into zero or more elements.
firstWhere(bool test(E element), {E orElse()?}) → E
  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
followedBy(Iterable<E> other) → Iterable<E>
  Creates the lazy concatenation of this iterable and `other`.
forEach(void action(E element)) → void
  Invokes `action` on each element of this iterable 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
  The last element that satisfies the given predicate `test`.
map<T>(T toElement(E e)) → Iterable<T>
  The current elements of this iterable modified by `toElement`.
noSuchMethod(Invocation invocation) → dynamic
  Invoked when a nonexistent method or property is accessed.
  inherited
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 orElse()?}) → E
  The single element that satisfies `test`.
skip(int count) → Iterable<E>
  Creates an Iterable that provides all but the first `count` elements.
skipWhile(bool test(E element)) → Iterable<E>
  Creates an `Iterable` that skips leading elements while `test` is satisfied.
take(int count) → Iterable<E>
  Creates a lazy iterable of the `count` first elements of this iterable.
takeWhile(bool test(E element)) → Iterable<E>
  Creates 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`.
  override
where(bool test(E element)) → Iterable<E>
  Creates a new lazy Iterable with all elements that satisfy the predicate `test`.
whereType<T>() → Iterable<T>
  Creates a new lazy Iterable with all elements that have type `T`.

## Operators

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

## Static Methods

castFrom<S, T>(Iterable<S> source) → Iterable<T>
  Adapts `source` to be an `Iterable<T>`.
iterableToFullString(Iterable iterable, [String leftDelimiter = '(', String rightDelimiter = ')']) → String
  Converts an `Iterable` to a string.
iterableToShortString(Iterable iterable, [String leftDelimiter = '(', String rightDelimiter = ')']) → String
  Convert an `Iterable` to a string like Iterable.toString.