Iterable<E>抽象 混入

一组值,或称为“元素”,可以按顺序访问。

可迭代元素的访问是通过使用 Iterator 使用 iterator getter 来获取的,并使用它来遍历值。通过迭代器进行遍历是通过调用 Iterator.moveNext 来完成的,如果调用返回 true,则迭代器已移动到下一个元素,该元素随后可用作 Iterator.current。如果调用返回 false,则没有更多元素。必须仅在最近的 Iterator.moveNext 调用返回 true 时使用 Iterator.current 的值。如果在使用迭代器的第一次调用 Iterator.moveNext 之前或调用已返回 false 或抛出错误之后使用它,则读取 Iterator.current 可抛出或返回任意值。

您可以从同一个 Iterable 创建多个迭代器。每次读取 iterator 时,它都会返回一个新的迭代器,不同的迭代器可以独立遍历,每个迭代器都可以访问可迭代中的所有元素。同一个可迭代的迭代器应提供相同的值并在相同的顺序中(除非在迭代之间修改了底层集合,有些集合允许这样做)。

您还可以使用 for-in 循环结构遍历 Iterable 的元素,该结构在幕后使用 iterator getter。例如,您可以遍历一个 Map 的所有键,因为 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]}');
}

ListSet 类都是 Iterable,以及大多数在 dart:collection 库中的类。

某些 Iterable 集合可以进行修改。向 ListSet 添加元素将改变它包含的元素,向 Map 添加新键将改变 Map.keys 的元素。在更改后创建的迭代器将提供新元素,并且可能或可能不保留现有元素的顺序(例如,HashSet 在添加单个元素时可能完全改变其顺序)。

在迭代时更改集合通常是不允许的。这样做将中断迭代,这通常在下次调用 Iterator.moveNext 时通过抛出 ConcurrentModificationError 来表示。Iterator.current getter 的当前值不应受集合更改的影响,因为 current 值是在前一次调用 Iterator.moveNext 时设置的。

某些可迭代在每次迭代时都会动态计算其元素,例如由 Iterable.generate 返回的或由 sync* 生成器函数返回的可迭代。如果计算不依赖于可能更改的其他对象,则生成的序列应该每次迭代时都相同。

Iterable 的成员(除了 iterator 本身)通过查看可迭代对象的元素来工作。这可以通过运行 iterator 来实现,但某些类可能有更有效的方法来查找结果(例如,在 lastlength 上对 List,或在 Set 上的 contains)。

返回另一个 Iterable 的方法(如 mapwhere)都是 惰性 的——它们将在返回的可迭代对象被迭代时每次迭代原始对象(如有必要),而不是在此之前。

由于可迭代对象可能被迭代多次,因此不建议在迭代器中存在可检测的副作用。对于 mapwhere 等方法,返回的可迭代对象将在每次迭代时执行参数函数,因此这些函数也不应有副作用。

Iterable 声明提供了一个默认实现,可以扩展或混入以实现 Iterable 接口。它实现了除了 iterator 获取器之外的所有成员,使用 iterator 提供的 Iterator。当可以这样做时,Iterable 接口的实现应该提供更有效的成员实现。

实现者
可用扩展

构造函数

Iterable()
const
Iterable.empty()
创建一个空的可迭代对象。
const
factory
Iterable.generate(int count, [E generator(int index)?])
创建一个动态生成其元素的 Iterable
factory

属性

first → E
第一个元素。
无设置器
hashCode int
此对象的哈希码。
无设置器继承
isEmpty bool
此集合是否没有元素。
无设置器
isNotEmpty bool
此集合是否至少有一个元素。
无设置器
iterator Iterator<E>
一个新的 Iterator,允许迭代此 Iterable 的元素。
无设置器
last → E
最后一个元素。
无设置器
length int
Iterable 中的元素数量。
无设置器
runtimeType Type
对象运行时类型的表示。
无设置器继承
single → E
检查此可迭代对象只有一个元素,并返回该元素。
无设置器

方法

any(bool test(E element)) bool
检查这个可迭代对象中的任何元素是否满足 test
cast<R>() Iterable<R>
将此可迭代对象视为一个 R 实例的可迭代对象。
contains(Object? element) bool
该集合是否包含等于 element 的元素。
elementAt(int index) → E
返回第 index 个元素。
every(bool test(E element)) bool
检查这个可迭代对象中的每个元素是否满足 test
expand<T>(Iterable<T> toElements(E element)) Iterable<T>
将此可迭代对象中的每个元素扩展为零个或多个元素。
firstWhere(bool test(E element), {Object? orElse()?}) → E
返回满足给定谓词 test 的第一个元素。
fold<T>(T initialValue, T combine(T previousValue, E element)) → T
通过迭代将集合中的每个元素与现有值组合,将集合减少到单个值。
followedBy(Iterable<E> other) Iterable<E>
创建此可迭代对象和 other 的懒加载连接。
forEach(void action(E element)) → void
按迭代顺序在可迭代的每个元素上调用 action
join([String separator = ""]) String
将每个元素转换为 String 并连接这些字符串。
lastWhere(bool test(E element), {E orElse()?}) → E
满足给定谓词 test 的最后一个元素。
map<T>(T toElement(E e)) Iterable<T>
使用 toElement 修改当前可迭代元素。
noSuchMethod(Invocation invocation) → dynamic
当访问不存在的方法或属性时被调用。
继承
reduce(E combine(E value, E element)) → E
通过迭代使用提供的函数组合集合的元素,将集合减少到单个值。
singleWhere(bool test(E element), {E orElse()?}) → E
满足 test 的单个元素。
skip(int count) Iterable<E>
创建一个 Iterable,它提供除了前 count 个元素之外的所有元素。
skipWhile(bool test(E value)) Iterable<E>
创建一个在满足条件时跳过前面元素的Iterable
take(int count) Iterable<E>
创建一个包含此可迭代对象前count个元素的懒加载可迭代对象。
takeWhile(bool test(E value)) Iterable<E>
创建一个包含满足test条件的开头元素的懒加载可迭代对象。
toList({bool growable = true}) List<E>
创建一个包含此Iterable中元素的List
toSet() Set<E>
创建一个包含与此可迭代对象相同元素的Set
toString() String
返回this(一些)元素的字符串表示。
override
where(bool test(E element)) Iterable<E>
创建一个包含满足谓词test的所有元素的新懒加载Iterable
whereType<T>() Iterable<T>
创建一个包含具有类型T的所有元素的新懒加载Iterable

运算符

operator ==(Object other) bool
等于运算符。
继承

静态方法

castFrom<S, T>(Iterable<S> source) Iterable<T>
source适配为Iterable<T>
iterableToFullString(Iterable iterable, [String leftDelimiter = '(', String rightDelimiter = ')']) String
Iterable转换为字符串。
iterableToShortString(Iterable iterable, [String leftDelimiter = '(', String rightDelimiter = ')']) String
Iterable转换为类似于Iterable.toString的字符串。