一组值,或称为“元素”,可以按顺序访问。
可迭代元素的访问是通过使用 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]}');
}
List 和 Set 类都是 Iterable
,以及大多数在 dart:collection
库中的类。
某些 Iterable 集合可以进行修改。向 List
或 Set
添加元素将改变它包含的元素,向 Map
添加新键将改变 Map.keys 的元素。在更改后创建的迭代器将提供新元素,并且可能或可能不保留现有元素的顺序(例如,HashSet 在添加单个元素时可能完全改变其顺序)。
在迭代时更改集合通常是不允许的。这样做将中断迭代,这通常在下次调用 Iterator.moveNext 时通过抛出 ConcurrentModificationError 来表示。Iterator.current getter 的当前值不应受集合更改的影响,因为 current
值是在前一次调用 Iterator.moveNext 时设置的。
某些可迭代在每次迭代时都会动态计算其元素,例如由 Iterable.generate 返回的或由 sync*
生成器函数返回的可迭代。如果计算不依赖于可能更改的其他对象,则生成的序列应该每次迭代时都相同。
Iterable
的成员(除了 iterator
本身)通过查看可迭代对象的元素来工作。这可以通过运行 iterator 来实现,但某些类可能有更有效的方法来查找结果(例如,在 last 或 length 上对 List,或在 Set 上的 contains)。
返回另一个 Iterable
的方法(如 map 和 where)都是 惰性 的——它们将在返回的可迭代对象被迭代时每次迭代原始对象(如有必要),而不是在此之前。
由于可迭代对象可能被迭代多次,因此不建议在迭代器中存在可检测的副作用。对于 map 和 where 等方法,返回的可迭代对象将在每次迭代时执行参数函数,因此这些函数也不应有副作用。
Iterable
声明提供了一个默认实现,可以扩展或混入以实现 Iterable
接口。它实现了除了 iterator 获取器之外的所有成员,使用 iterator 提供的 Iterator。当可以这样做时,Iterable
接口的实现应该提供更有效的成员实现。
构造函数
- Iterable()
-
const
- Iterable.empty()
- 创建一个空的可迭代对象。constfactory
- 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的字符串。