List<E> class abstract interface

An indexable collection of objects with a length.

Subclasses of this class implement different kinds of lists. The most common kinds of lists are:

• Fixed-length list

  An error occurs when attempting to use operations that can change the length of the list.

• Growable list

  Full implementation of the API defined in this class.

The default growable list, as created by [], keeps an internal buffer, and grows that buffer when necessary. This guarantees that a sequence of add operations will each execute in amortized constant time. Setting the length directly may take time proportional to the new length, and may change the internal capacity so that a following add operation will need to immediately increase the buffer capacity. Other list implementations may have different performance behavior.

Example of fixed-length list:

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

Example of growable list:

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

To add data to the growable list, use operator[]=, add or addAll.

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

To check whether, and where, the element is in the list, use indexOf or lastIndexOf.

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

To remove an element from the growable list, use remove, removeAt, removeLast, removeRange or removeWhere.

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

To insert an element at position in the list, use insert or insertAll.

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

To replace a range of elements in the list, use fillRange, replaceRange or setRange.

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

To sort the elements of the list, use sort.

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

To shuffle the elements of this list randomly, use shuffle.

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

To find the first element satisfying some predicate, or give a default value if none do, use firstWhere.

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

There are similar lastWhere and singleWhere methods.

A list is an Iterable and supports all its methods, including where, map, whereType and toList.

Lists are Iterable. Iteration occurs over values in index order. Changing the values does not affect iteration, but changing the valid indices—that is, changing the list's length—between iteration steps causes a ConcurrentModificationError. This means that only growable lists can throw ConcurrentModificationError. If the length changes temporarily and is restored before continuing the iteration, the iterator might not detect it.

It is generally not allowed to modify the list's length (adding or removing elements) while an operation on the list is being performed, for example during a call to forEach or sort. Changing the list's length while it is being iterated, either by iterating it directly or through iterating an Iterable that is backed by the list, will break the iteration.