dart:core

Класс Iterable<E>

Коллекция значений, или «элементов», к которым можно обращаться последовательно.

Доступ к элементам итерируемой коллекции осуществляется с помощью Iterator, полученного через геттер iterator, который используется для последовательного перебора значений. Перемещение с помощью итератора выполняется вызовом Iterator.moveNext. Если вызов возвращает true, итератор перемещается к следующему элементу, который становится доступен через Iterator.current. Если вызов возвращает false, элементов больше нет. Значение Iterator.current можно использовать, только если последний вызов Iterator.moveNext вернул true. Если обратиться к нему до первого вызова Iterator.moveNext для итератора или после того, как вызов вернул false либо вызвал ошибку, чтение Iterator.current может привести к исключению или вернуть произвольное значение.

Из одного и того же Iterable можно создать несколько итераторов. При каждом чтении iterator возвращается новый итератор, и перемещаться по разным итераторам можно независимо, получая доступ ко всем элементам итерируемой коллекции. Итераторы одной и той же итерируемой коллекции должны возвращать одинаковые значения в одинаковом порядке (если только исходная коллекция не изменяется между итерациями, что допускается для некоторых коллекций).

Элементы Iterable также можно перебрать с помощью цикла for-in, который скрыто использует геттер iterator. Например, можно перебрать все ключи 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 может полностью изменить свой порядок при добавлении одного элемента).

Как правило, изменять коллекцию во время её перебора нельзя. Это нарушит перебор, и обычно об этом сигнализирует исключение ConcurrentModificationError при следующем вызове Iterator.moveNext. Изменение коллекции не должно влиять на текущее значение геттера Iterator.current: значение current было установлено предыдущим вызовом Iterator.moveNext.

Некоторые итерируемые коллекции вычисляют элементы динамически при каждом переборе, например коллекция, возвращаемая Iterable.generate, или коллекция, возвращаемая функцией-генератором sync*. Если вычисление не зависит от других объектов, которые могут изменяться, генерируемая последовательность должна быть одинаковой при каждом переборе.

Члены Iterable, за исключением самого iterator, работают с элементами итерируемой коллекции. Это можно реализовать перебором с помощью iterator, однако некоторые классы могут предоставлять более эффективные способы получения результата (например, last или length у List либо contains у Set).

Методы, возвращающие другую Iterable (например, map и where), являются ленивыми: они перебирают исходную коллекцию (по мере необходимости) при каждом переборе возвращённой коллекции, а не раньше.

Поскольку итерируемую коллекцию можно перебрать несколько раз, не рекомендуется использовать в итераторе побочные эффекты, которые можно обнаружить. Для таких методов, как map и where, возвращённая коллекция будет выполнять функцию-аргумент при каждом переборе, поэтому эти функции также не должны иметь побочных эффектов.

Реализуют

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

Доступные расширения

• EnumByName

Конструкторы

Iterable()

const

Iterable.empty()

const

factory

Создаёт пустую итерируемую коллекцию.

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

factory

Создаёт Iterable, элементы которой генерируются динамически.

Свойства

first → E

только для чтения

Возвращает первый элемент.

hashCode → int

только для чтения, наследуется

Хэш-код этого объекта.

isEmpty → bool

только для чтения

Указывает, не содержит ли эта коллекция элементов.

isNotEmpty → bool

только для чтения

Указывает, содержит ли эта коллекция хотя бы один элемент.

iterator → Iterator<E>

только для чтения

Возвращает новый Iterator, позволяющий перебирать элементы этого Iterable.

last → E

только для чтения

Возвращает последний элемент.

length → int

только для чтения

Возвращает количество элементов в этой коллекции.

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>

Преобразует каждый элемент этой Iterable в ноль или более элементов.

firstWhere(bool test(E element), {E 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, пропускающую начальные элементы, пока выполняется условие test.

take(int count) → Iterable<E>

Возвращает ленивую итерируемую коллекцию из первых count элементов этой коллекции.

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

Возвращает ленивую итерируемую коллекцию из начальных элементов, удовлетворяющих условию test.

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

Создаёт List, содержащий элементы этой коллекции Iterable.

toSet() → Set<E>

Создаёт Set, содержащий те же элементы, что и эта итерируемая коллекция.

toString() → String

переопределён

Возвращает строковое представление некоторых элементов this.

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

Возвращает новую ленивую Iterable, содержащую все элементы, удовлетворяющие условию test.

whereType<T>() → Iterable<T>

Возвращает новую ленивую Iterable, содержащую все элементы типа T.

Операторы

operator ==(Object other) → bool

наследуется

Оператор равенства.

Статические методы

castFrom<S, T>(Iterable<S> source) → Iterable<T>

Адаптирует source, чтобы получить Iterable<T>.