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 returned by new List()
or []
, 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.
The following code illustrates that some List implementations support only a subset of the API.
List<int> fixedLengthList = new List(5);
fixedLengthList.length = 0; // Error
fixedLengthList.add(499); // Error
fixedLengthList[0] = 87;
List<int> growableList = [1, 2];
growableList.length = 0;
growableList.add(499);
growableList[0] = 87;
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 does 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.
fill
at each position. [...]
elements
. [...]
elements
. [...]
elements
. [...]
true
if there are no elements in this collection. [...]
Iterator
that allows iterating the elements of this
Iterable
. [...]
value
to the end of this list,
extending the length by one. [...]
iterable
to the end of this list. [...]
this
. [...]
R
instances. [...]
start
inclusive to end
exclusive
to the given fillValue
. [...]
start
inclusive to end
exclusive. [...]
element
in this list. [...]
test
. [...]
index
in this list. [...]
iterable
at position index
in this list. [...]
element
in this list. [...]
test
. [...]
value
from this list. [...]
index
from this list. [...]
start
inclusive to end
exclusive. [...]
test
. [...]
start
inclusive to end
exclusive
and inserts the contents of replacement
in its place. [...]
test
. [...]
this
with the objects of iterable
, starting
at position index
in this list. [...]
iterable
, skipping skipCount
objects first,
into the range start
, inclusive, to end
, exclusive, of the list. [...]
compare
function. [...]
start
and end
. [...]
test
. [...]
element
. [...]
index
th element. [...]
test
. [...]
test
. [...]
other
. [...]
f
to each element of this collection in iteration
order.
test
. [...]
f
on each element of this Iterable
in iteration order. [...]
test
. [...]
count
elements. [...]
Iterable
that skips leading elements while test
is satisfied. [...]
count
first elements of this iterable. [...]
test
. [...]
test
. [...]
T
. [...]
other
. [...]
index
in the list
or throws a RangeError if index
is out of bounds.
index
in the list to value
or throws a RangeError if index
is out of bounds.
source
to be a List<T>
. [...]