▩Dart-Iterable＜E＞类

本文是自己翻译的，来源：Iterable<E> class

Iterable<E> class (Null safety)
可以按顺序访问的值或“元素”的集合。

一、概述

通过使用iterator getter获取Iterator，并使用它逐步遍历值，达到访问iterable的元素的目的。使用迭代器单步执行是通过调用iterator.moveNext，如果调用返回true，则迭代器现在已移动到下一个元素，该元素随后可用作迭代器。现在的如果调用返回false，则没有更多元素。Iterator.current只能在最近调用iterator.moveNext返回true时使用。如果在首次调用iterator.moveNext或当调用返回false时，读取Iterator.current会抛出错误或返回任意值。

可以从同一个Iterable创建多个iterator。每次读取iterator时，它都会返回一个新的迭代器，可以独立地遍历不同的迭代器，每个迭代器都允许访问iterable的所有元素。相同iterable的iterators应该以相同的顺序提供相同的值（除非在迭代之间修改了基础集合，这是某些集合允许的）。

你还可以使用for-in-loop构造对Iterable的元素进行迭代，该构造在后台使用iterator getter。例如，你可以迭代Map的所有键，因为映射键是可迭代的。

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]}');
}

List类和Set类都是Iterable，dart:collection库中的大多数类也是如此。

可以修改某些Iterable集合。向List或Set中添加元素将更改其包含的元素，向Map添加新键将更改Map.keys的元素。更改后创建的迭代器将提供新元素，并且可能保留或不保留现有元素的顺序（例如，当添加单个元素时，HashSet可能会完全更改其顺序）。

通常不允许在迭代集合时对其进行更改。这样做将中断迭代，这通常在下次调用Iterator.moveNext时抛出ConcurrentModificationError。Iterator.current getter的当前值不应受到集合中的更改的影响，当前值是由上一次调用Iterator.moveNext设置的。

有些iterables每次迭代时都会动态计算它们的元素，就像Iterable.generate返回的元素或sync* generator函数返回的iterable。如果计算不依赖于可能更改的其他对象，那么每次迭代生成的序列都应该是相同的。

Iterable的成员，而不是iterator本身，通过查看iterable的元素来工作。这可以通过贯穿iterator来实现，但是有些类可能有更有效的方法来查找结果（比如List中的last或length，或者Set中的contains）。

返回另一个Iterable的方法（如map和where）都是惰性的——它们将在每次迭代返回的Iterable时（根据需要）迭代原始的Iterable，而不是在迭代之前。

由于iterable可能被多次迭代，因此不建议在迭代器中具有可检测的副作用。对于像map和where这样的方法，返回的iterable将在每次迭代中执行参数函数(谓词函数)，因此这些函数也不应该有副作用。

二、子类

DoubleLinkedQueue，IterableBase，IterableMixin，LinkedList，List，ListQueue，Queue，Runes，Set

三、可用的扩展

EnumByName

四、构造函数

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

五、成员属性

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

六、方法

any(bool test(E element)) → bool
Checks whether any element of this iterable satisfies test. […]
․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…
cast<R>() → Iterable<R>
Provides 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 indexth element. […]
․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…
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
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 […]
․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…
followedBy(Iterable<E> other) → Iterable<E>
Returns 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
Returns 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 non-existent 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
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. […]
override
․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…
where(bool test(E element)) → Iterable<E>
Returns a new lazy Iterable with all elements that satisfy the predicate test. […]
․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…․‥…
whereType<T>() → Iterable<T>
Returns a new lazy Iterable with all elements that have type T. […]

七、运算符

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

八、静态方法

castFrom<S, T>(Iterable<S> source) → Iterable<T>
Adapts source to be an Iterable<T>. […]