Класс List<E>

Индексируемая коллекция объектов с длиной.

Подклассы этого класса реализуют различные виды списков. Наиболее распространены следующие виды списков:

Список фиксированной длины

При попытке выполнить операции, которые могут изменить длину списка, возникает ошибка.
Расширяемый список

Полная реализация API, определённого в этом классе.

Расширяемый список по умолчанию, создаваемый с помощью [], хранит внутренний буфер и при необходимости увеличивает его. Это гарантирует, что каждая операция add в последовательности будет выполняться за амортизированное постоянное время. Непосредственное изменение длины может занять время, пропорциональное новой длине, и изменить внутреннюю ёмкость так, что для следующей операции добавления потребуется сразу увеличить ёмкость буфера. Другие реализации списков могут иметь иные характеристики производительности.

Пример списка фиксированной длины:

final fixedLengthList = List<int>.filled(5, 0); // Creates fixed-length list.
print(fixedLengthList); // [0, 0, 0, 0, 0]
fixedLengthList[0] = 87;
fixedLengthList.setAll(1, [1, 2, 3]);
print(fixedLengthList); // [87, 1, 2, 3, 0]
// Fixed length list length can't be changed or increased
fixedLengthList.length = 0;  // Throws
fixedLengthList.add(499);    // Throws

Пример расширяемого списка:

final growableList = <String>['A', 'B']; // Creates growable list.

Чтобы добавить данные в расширяемый список, используйте operator[]=, add или addAll.

growableList[0] = 'G';
print(growableList); // [G, B]
growableList.add('X');
growableList.addAll({'C', 'B'});
print(growableList); // [G, B, X, C, B]

Чтобы проверить, содержится ли элемент в списке и где он находится, используйте indexOf или lastIndexOf.

final indexA = growableList.indexOf('A'); // -1 (not in the list)
final firstIndexB = growableList.indexOf('B'); // 1
final lastIndexB = growableList.lastIndexOf('B'); // 4

Чтобы удалить элемент из расширяемого списка, используйте remove, removeAt, removeLast, removeRange или removeWhere.

growableList.remove('C');
growableList.removeLast();
print(growableList); // [G, B, X]

Чтобы вставить элемент в список в заданную позицию, используйте insert или insertAll.

growableList.insert(1, 'New');
print(growableList); // [G, New, B, X]

Чтобы заменить диапазон элементов в списке, используйте fillRange, replaceRange или setRange.

growableList.replaceRange(0, 2, ['AB', 'A']);
print(growableList); // [AB, A, B, X]
growableList.fillRange(2, 4, 'F');
print(growableList); // [AB, A, F, F]

Чтобы отсортировать элементы списка, используйте sort.

growableList.sort((a, b) => a.compareTo(b));
print(growableList); // [A, AB, F, F]

Чтобы перемешать элементы этого списка в случайном порядке, используйте shuffle.

growableList.shuffle();
print(growableList); // e.g. [AB, F, A, F]

Чтобы найти первый элемент, удовлетворяющий условию, или вернуть значение по умолчанию, если таких элементов нет, используйте firstWhere.

bool isVowel(String char) => char.length == 1 && "AEIOU".contains(char);
final firstVowel = growableList.firstWhere(isVowel, orElse: () => ''); // ''

Аналогичные методы: lastWhere и singleWhere.

Список является Iterable и поддерживает все его методы, в том числе where, map, whereType и toList.

Списки являются Iterable. Перебор выполняется в порядке значений индексов. Изменение значений не влияет на перебор, но изменение допустимых индексов — то есть изменение длины списка — между шагами перебора вызывает ConcurrentModificationError. Это означает, что исключение ConcurrentModificationError могут вызывать только расширяемые списки. Если длина временно изменится, а затем восстановится до продолжения перебора, итератор может этого не обнаружить.

Как правило, во время выполнения операции над списком, например вызова forEach или sort, изменять длину списка (добавлять или удалять элементы) нельзя. Изменение длины списка во время перебора — напрямую или через перебор Iterable, основанного на этом списке, — приведёт к нарушению перебора.

Реализуемые типы

Iterable<T>

Реализаторы

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

EnumByName

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

List([int? length]) factory: Создаёт список заданной длины.
List.empty({bool growable = false}) factory: Создаёт новый пустой список.
List.filled(int length, E fill, {bool growable = false}) factory: Создаёт список заданной длины, заполняя каждую позицию значением fill.
List.from(Iterable elements, {bool growable = true}) factory: Создаёт список, содержащий все elements.
List.generate(int length, E generator(int index), {bool growable = true}) factory: Создаёт список значений.
List.of(Iterable<E> elements, {bool growable = true}) factory: Создаёт список из elements.
List.unmodifiable(Iterable elements) factory: Создаёт неизменяемый список, содержащий все elements.

Свойства

first ↔ E чтение / записьунаследованный геттер: Возвращает первый элемент.
hashCode → int только чтениеунаследовано: Хеш-код этого объекта.
isEmpty → bool только чтениеунаследовано: Показывает, не содержит ли эта коллекция элементов.
isNotEmpty → bool только чтениеунаследовано: Показывает, содержит ли эта коллекция хотя бы один элемент.
iterator → Iterator<E> только чтениеунаследовано: Возвращает новый Iterator, который позволяет перебирать элементы этого Iterable.
last ↔ E чтение / записьунаследованный геттер: Возвращает последний элемент.
length ↔ int чтение / запись: Количество объектов в этом списке.
reversed → Iterable<E> только чтение: Iterable объектов этого списка в обратном порядке.
runtimeType → Type только чтениеунаследовано: Представление типа объекта во время выполнения.
single → E только чтениеунаследовано: Проверяет, что этот итерируемый объект содержит только один элемент, и возвращает его.

Методы

add(E value) → void: Добавляет value в конец этого списка, увеличивая его длину на единицу.
addAll(Iterable<E> iterable) → void: Добавляет все объекты из iterable в конец этого списка.
any(bool test(E element)) → bool унаследовано: Проверяет, удовлетворяет ли какой-либо элемент этого итерируемого объекта условию test.
asMap() → Map<int, E>: Неизменяемое представление этого списка в виде Map.
cast<R>() → List<R> переопределение: Возвращает представление этого списка как списка экземпляров R.
clear() → void: Удаляет из этого списка все объекты; длина списка становится равной нулю.
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 в ноль или более элементов.
fillRange(int start, int end, [E? fillValue]) → void: Перезаписывает диапазон элементов значением fillValue.
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 для каждого элемента этого итерируемого объекта в порядке перебора.
getRange(int start, int end) → Iterable<E>: Создаёт Iterable, который перебирает диапазон элементов.
indexOf(E element, [int start = 0]) → int: Первый индекс элемента element в этом списке.
indexWhere(bool test(E element), [int start = 0]) → int: Первый индекс в списке, элемент которого удовлетворяет заданному test.
insert(int index, E element) → void: Вставляет element в позицию index этого списка.
insertAll(int index, Iterable<E> iterable) → void: Вставляет все объекты из iterable в позицию index этого списка.
join([String separator = ""]) → String унаследовано: Преобразует каждый элемент в String и объединяет полученные строки.
lastIndexOf(E element, [int? start]) → int: Последний индекс элемента element в этом списке.
lastIndexWhere(bool test(E element), [int? start]) → int: Последний индекс в списке, элемент которого удовлетворяет заданному test.
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 унаследовано: Сводит коллекцию к одному значению, последовательно объединяя её элементы с помощью заданной функции.
remove(Object? value) → bool: Удаляет первое вхождение value из этого списка.
removeAt(int index) → E: Удаляет объект в позиции index из этого списка.
removeLast() → E: Удаляет и возвращает последний объект в этом списке.
removeRange(int start, int end) → void: Удаляет диапазон элементов из списка.
removeWhere(bool test(E element)) → void: Удаляет из этого списка все объекты, удовлетворяющие условию test.
replaceRange(int start, int end, Iterable<E> replacements) → void: Заменяет диапазон элементов элементами из replacements.
retainWhere(bool test(E element)) → void: Удаляет из этого списка все объекты, не удовлетворяющие условию test.
setAll(int index, Iterable<E> iterable) → void: Перезаписывает элементы объектами из iterable.
setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]) → void: Записывает некоторые элементы из iterable в диапазон этого списка.
shuffle([Random? random]) → void: Перемешивает элементы этого списка в случайном порядке.
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.
sort([int compare(E a, E b)?]) → void: Сортирует этот список в порядке, заданном функцией compare.
sublist(int start, [int? end]) → List<E>: Возвращает новый список, содержащий элементы между start и end.
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 унаследовано: Строковое представление этого объекта.
where(bool test(E element)) → Iterable<E> унаследовано: Возвращает новый ленивый Iterable со всеми элементами, удовлетворяющими условию test.
whereType<T>() → Iterable<T> унаследовано: Возвращает новый ленивый Iterable со всеми элементами типа T.

Операторы

operator +(List<E> other) → List<E>: Возвращает результат объединения этого списка и other.
operator ==(Object other) → bool переопределение: Равен ли этот список other.
operator [](int index) → E: Объект в заданной index списка.
operator []=(int index, E value) → void: Устанавливает значение value в заданной index списка.

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

castFrom<S, T>(List<S> source) → List<T> переопределение: Адаптирует source, чтобы он стал List<T>.
copyRange<T>(List<T> target, int at, List<T> source, [int? start, int? end]) → void: Копирует диапазон из одного списка в другой.
writeIterable<T>(List<T> target, int at, Iterable<T> source) → void: Записывает элементы итерируемого объекта в список.

© 2012 the Dart project authors
Licensed under the BSD 3-Clause "New" or "Revised" License.
https://api.dart.dev/stable/2.19.6/dart-core/List-class.html