按顺序访问的值或元素的集合。

可迭代对象的元素通过Iterator来访问,该迭代器使用iterator的getter方法来获取, 并且可使用迭代器对所有值进行单步遍历。 迭代器通过调用Iterator.moveNext来进行遍历, 如果调用返回true,迭代器会移动到下一个元素,并将元素作为Iterator.current可用的返回值。 如果调用返回false,表示没有更多的元素,iterator.current返回null

对于同一个Iterable,你可以创建多次迭代器。 每次读取iterator,它会返回一个新的迭代器, 不同的迭代器可以进行遍历而互不影响,每个迭代器都可以访问对象的所有元素。 相同对象的迭代器应该提供相同的值和顺序(除非在迭代期间,基础集合被修改,部分集合允许此操作)。

泥也可以使用for-in循环结构来迭代Iterable的所有元素, 该结构在后台同样使用了iterator的getter方法。 例如,可以迭代Map所有的key值,因为Map的keys是可迭代对象。

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

ListSet也是Iterabledart:collection库中同样有很多。

部分Iterable集合可以被修改。 向ListSet添加元素将改变对象所有包含的元素。 向Map添加新的Key会改变所有Map.keys的元素。 在集合改变后,创建的迭代器将提供新的所有元素, 并且可能会保持目前元素的顺序,也可能不会 (例如,在添加一个元素之后,HashSet也许会完全地改变它的顺序)。

迭代的同时修改集合,这通常是不允许的。这样做会破坏迭代。 然后,通常会抛出ConcurrentModificationError, 向下一次调用的Iterator.moveNext发出信号。 当前Iterator.current的getter方法的值不应该受集合的变化影响, current的值是上一次调用Iterator.moveNext时设置的。 经测试,在修改集合后break,并不会引起异常,但并不建议这么做。 下面是重现异常的代码:

main() {
  List<int> list = [0, 1, 2];
  for(int i in list) {
    if(i == 0) {
      //for-in后台使用迭代器遍历对象
      //在迭代过程中修改集合,会在下一次调用 Iterator.moveNext 时出现异常
      list.remove(i);
      //break;
    }
  }

  print(list);
}

一些可迭代对象会在每次迭代时,动态计算它们的元素, 如Iterable.generatesync*异步函数生成器。 如果计算不依赖其它可能会改变的对象,那么每次迭代时生成的序列应该是一样的。

Iterable的成员,除了iterator自身,都通过查看可迭代对象的元素来工作。 这可以通过获取iterator来实现,但一些类可能类可能有更高效的查找结果的方法 (如ListlastlengthSetcontains)。

返回Iterable的方法(如mapwhere)都是 惰性的。 它们会在每次返回的可迭代对象被使用时,才开始迭代(在必要时)原始数据,而不是之前。

因为可迭代对象可能被迭代多次,所以并不建议在迭代器中有任何副作用。 对于类似mapwhile的方法,返回的可迭代对象会对每个迭代执行带参函数, 因此那些函数也不应该有副作用。

Implemented by

Constructors

Iterable()

const
Iterable.empty()

创建空的可迭代对象。

const
factory
Iterable.generate(int count, [E generator(int index)])

创建一个Iterable,通过序列来动态生成元素。

factory

Properties

first → E

返回第一个元素。

read-only
hashCode int

获取对象的哈希值。

read-only, inherited
isEmpty bool

如果this没有元素,则返回true

read-only
isNotEmpty bool

如果集合中至少有一个元素,返回true

read-only
iterator Iterator<E>

返回Iterator,被允许迭代Iterable的所有元素。

read-only
last → E

返回最后一个元素。

read-only
length int

返回this对象中元素的数量。

read-only
runtimeType Type

表示对象的运行时类型。

read-only, inherited
single → E

检查可迭代对象仅有一个元素,并返回那个元素。

read-only

Operators

operator ==(other) bool

相等操作符。

inherited

Methods

any(bool f(E element)) bool

检查可迭代对象是否有任何一个元素满足test

contains(Object element) bool

返回true,如果集合中包含一个元素等于element

elementAt(int index) → E

通过索引返回元素。

every(bool f(E element)) bool

检查可迭代对象的每一个元素是否都满足test

expand(Iterable f(E element)) Iterable

Iterable的每个元素扩展为0个或多个元素。

firstWhere(bool test(E element), {E orElse()}) → E

返回满足test断言的第一个元素。

fold(initialValue, dynamic combine(previousValue, E element)) → dynamic

通过迭代,将集合的所有元素与一个存在的值(initialValue)用提供的函数结合(combine), 将集合换算成单一的值,

forEach(void f(E element)) → void

对集合的每个元素,按迭代顺序应用f函数。

join([String separator = ""]) String

将每个元素转换成String并连接。

lastWhere(bool test(E element), {E orElse()}) → E

返回满足test断言的最后一个元素。

map(dynamic f(E e)) Iterable

按迭代顺序,对Iterable的每个元素调用f,用返回值创建一个新的惰性Iterable

noSuchMethod(Invocation invocation) → dynamic

当一个不存在的函数或成员变量被访问时,该函数被调用。

inherited
reduce(E combine(E value, E element)) → E

通过迭代,用提供的函数结合(combine)集合的所有元素,将集合换算成单一的值,

singleWhere(bool test(E element)) → E

返回满足test的单个元素。

skip(int count) Iterable<E>

返回一个惰性的可迭代对象,包含此对象除了最初的count个元素外的所有元素。

skipWhile(bool test(E value)) Iterable<E>

跳过最初的满足测试条件test的元素,返回Iterable

take(int count) Iterable<E>

返回一个惰性的可迭代对象,包含有此对象最初的count个元素。

takeWhile(bool test(E value)) Iterable<E>

返回一个惰性的Iterable,包含最初的满足test的所有元素。

toList({bool growable: true}) List<E>

创建一个包含Iterable所有元素的List

toSet() Set<E>

创建一个与Iterable有相同元素的Set

toString() String

返回一个字符串,表示this的所有(或部分)元素。

where(bool test(E element)) Iterable<E>

使用所有满足测试的元素,创建一个新的惰性Iterable