Class List
extends CollectionBase implements Collection
A linear collection of objects.
A List is an array with constant-time access to numbered elements, starting at index zero. (This is not a linked-list collection.)
Lists are mutable and growable.
Class summary
| constructor | Creates an empty list. |
|---|---|
| constructor size/int filler/any | Creates a new List of the given size where every slot is filled with the given filler. |
| constructor size/int --initial/any= | Creates a new List of the given size where every slot is filled with the given initial value. |
| constructor size/int [block] | Creates a List and initializes each element with the result of invoking the block. |
Constructors
Creates an empty list.
This operation is identical to creating a list with a list-literal:
[].Creates a new List of the given size where every slot is filled with the given filler.
Creates a new List of the given size where every slot is filled with the given initial value.
constructor size/int [block]
Creates a List and initializes each element with the result of invoking the block.
Statics
Calls the given block with indexes splitting the from-to range into chunks of the available size.
The block is called with three arguments:
chunk-from, chunk-to, and chunk-size, where chunk-size is always equal to chunk-to - chunk-from. The first invocation receives indexes for at most available elements. Subsequent invocations switch to max-available elements (which by default is the same as available).Returns to - from.
Creates a List, containing all elements of the given collection
Methods
Adds the given value to the list.
This operation increases the size of this instance.
It is an error to call this method on lists that can't grow.
Adds all elements of the given collection to the list.
This operation increases the size of this instance.
It is an error to call this method on lists that can't grow.
Clears this list, setting the size to 0.
It is an error to call this method on lists that can't change size.
Creates a copy of a slice of this list.
The returned object generally has the same type is this instance. Some subclasses may decide to return an object of different type, if the new size allows a more efficient class to be used.
The arguments from and to must satisfy:
0 <= from <= to <= size.Aliases
slice: JavaScript.sublist: Dart, Java,
Inheritance
This method should be implemented by each subclass of
List, as the type of the returned object should match the one of this instance. As exception, classes that have multiple implementations (say a SmallCarList and LargeCarList) may switch type, *especially* if the individual types are not visible to the users.Iterates over all elements in reverse order and invokes the given block on each of them.
Whether this instance is equal to other, using element-equals to compare the elements.
Equality only returns true when both operands are of the same type.
Returns false, if this instance and other are not of the same size, or if the contained elements are not equal themselves (using element-equals).
It is an error to compare self-recursive data-structures, if the element-equals block is not ensuring that the comparison leads to infinite loops.
Inheritance
Collections do *not* need to ensure that recursive data structures don't lead to infinite loops.
Fills values, computed by evaluating block, into list elements [from..to[.
Filters this instance using the given predicate.
Returns this instance if in-place is true. In this case replaces the elements in this list with the filtered elements.
Returns a new list if in-place is false (the default).
The result contains all the elements of this instance for which the predicate returns true.
The first element of the list.
The list must not be empty.
Searches for needle in the range from (inclusive) - to (exclusive).
If last is false (the default) returns the index of the first occurrence of needle in the given range from - to. Otherwise returns the last occurrence.
Returns -1 if needle is not contained in the range.
Calls if-absent without argument if the needle is not contained in the range, and returns the result of the call.
Uses binary search, with
<, > and ==, to find the element.The given range must be sorted.
Searches for needle in the sorted range from (inclusive) - to (exclusive).
Uses binary search with
<, > and == to find the needle.If not found, calls if-absent with the smallest index at which the element is greater than needle. If no such index exists (either because this instance is empty, or because the first element is greater than the needle) calls if-absent with to (where to was adjusted according to the rules in index-of --last needle from to).
Uses binary-compare to compare the elements in the sorted range.
The binary-compare block always receives one of the list elements as first argument, and the needle as second argument.
Uses binary-compare to compare the elements in the sorted range.
The binary-compare block always receives one of the list elements as first argument, and the needle as second argument.
Calls stringify on each element of the list, and concatenates the results into one string, using the separator.
Examples
[1, 2].join ", " // "1, 2"
Calls the block on each element of the list, and concatenates the results into one string, using the separator.
Examples
[1, 2].join ", ": "0x$(%02x it)" // "0x01, 0x02"
The last element of the list.
The list must not be empty.
Invokes the given block on each element.
Returns this instance if in-place is true. In this case replaces the elements in this list with the mapped elements.
Returns a new list if in-place is false (the default).
Returns a slice of this list.
Slices are views on the underlying object. As such they see and modify the object they come from.
The parameter from is inclusive.
The parameter to is exclusive.
Advanced
Slices keep the whole underlying object alive. This can lead to memory waste if the underlying object is not used otherwise. In some cases it might thus make sense to call copy on the slice.
At the call-site the arguments from and to are passed in with the slice syntax:
list[from..to]. Since both arguments are optional (as they have default values), it is valid to omit from or to.Examples
list := [1, 2, 3, 4, 5]
sub := list[1..3] // A view into [2, 3]
sub[0] = 22
print list // => [1, 22, 3, 4, 5]
sub = list[..3] // A view into [1, 22, 3]
sub.sort --in-place // Sorts just the 3 values.
print sub // => [1, 3, 22]
print list // => [1, 3, 22, 4, 5]
sub2 := sub[1..]
print sub2 // => [3, 22]
sub2[1] = 499
print list // => [1, 3, 499, 4, 5]
sub3 := list[2..].copy // => Creates a copy of [499, 4, 5]
sub3[0] = 3 // This time only the copy is affected.
print sub3 // => [3, 4, 5]
print list // => [1, 3, 499, 4, 5]
Returns the element in the slot of the given index.
// TODO(florian): document whether it's ok to index with -1 etc.
Stores the given value in the slot of the given index.
// TODO(florian): document whether it's ok to index with -1 etc.
Removes the first entry that is equal to the given needle.
Does nothing if the needle is not in this instance.
This operation is in
O(n) and thus not efficient.It is an error to call this method on lists that can't change size.
Removes the value at the given index.
If n is the distance to the end of the list, the operation runs in
O(n) and is thus not efficient for deletions that are not near the end of the list.Returns the value that was removed.
Removes all entries that are equal to the given needle.
Does nothing if the needle is not in this instance.
This operation is in
O(n) and thus not efficient.It is an error to call this method on lists that can't change size.
Removes the last entry that is equal to the given needle.
Does nothing if the needle is not in this instance.
This operation is in
O(n) and thus not efficient.It is an error to call this method on lists that can't change size.
Removes the last element of this instance.
Returns the removed element.
It is an error to call this method on lists that can't change size.
It is an error to call this method on empty lists.
Replaces this[index..index+(to-from)[ with source[from..to[
Changes the size of this list to the given new-size.
If the list grows as a result of this operation, then the elements are filled with null.
If the list shrinks as a result of this operation, then these elements are dropped.
Sorts the range [from..to[ using the given compare block.
The compare block must take two arguments
a and b and should return:- -1 if
a < b, - 0 if
a == b, and - 1 if
a > b.
Sorts the range [from..to[ using the the < and > operators.
The sort is stable, meaning that equal elements do not change their relative order.
Returns this instance if in-place is true.
Returns a new list if in-place is false (the default).