A collection in which every element has a unique
non-negative integer index. The elements of a nonempty
list are indexed starting with 0
at the first
element of the list, and ending with the index
lastIndex
at the last
element of the list.
lastIndex==size-1
.size==0
and the lastIndex
is
null
.Thus, the range of indexes of the list is formed by the
expression 0:list.size
.
A List
is a Collection
of its elements, and a
Correspondence
from indexes to elements.
Every list has a well-defined and stable iteration order.
An iterator()
of a nonempty list is required to return
the elements of the list in order of increasing index,
beginning with the element at index 0
, and ending with
the element at index lastIndex
. Thus, every iterator of
an immutable list produces exactly the same elements in
exactly the same order.
Direct access to a list element by index produces a value
of optional type. The following idiom may be used instead
of upfront bounds-checking, as long as the list element
type is a non-null
type:
if (exists char = "hello world"[index]) { //do something with char } else { //out of bounds }
When an algorithm guarantees that a list contains a given index, the following idiom may be used:
assert (exists char = "hello world"[index]); //do something with char
To iterate the indexes of a List
, use the following
idiom:
for (i->char in "hello world".indexed) { ... }
Strings, sequences,
tuples, and arrays are all List
s,
and are all of fixed length. Variable-length mutable
List
s are also possible.
no type hierarchy
Attributes | |
first | Source Codeshared actual default Element? first The first element of this Refines Iterable.first |
hash | Source Codeshared actual default Integer hash The hash value of the value, which allows the value to be an element of a hash-based set or key of a hash-based map. Implementations must respect the constraint that:
Therefore, a class which refines In general, Note that when executing on a Java Virtual Machine, the
64-bit Refines Object.hash |
keys | Source Codeshared actual default List<Integer> keys A list containing all indexes of this list. This is a lazy operation returning a view of this list. See also Iterable.indexes() Refines Correspondence.keys |
last | Source Codeshared actual default Element? last The last element of this Refines Iterable.last |
lastIndex | Source Codeshared formal Integer? lastIndex The index of the last element of the list, or See also size |
rest | Source Codeshared actual default List<Element> rest The rest of the list, without the first element. This is a lazy operation returning a view of this list. Refines Iterable.rest |
reversed | Source Codeshared default List<Element> reversed A list containing the elements of this list in reverse
order to the order in which they occur in this list.
For every list.reversed[index]==list[size-1-index] This is a lazy operation returning a view of this list. |
size | Source Codeshared actual default Integer size The number of elements in this list, always
See also lastIndex Refines Iterable.size |
Inherited Attributes |
Attributes inherited from: Object |
Attributes inherited from: Collection<Element> |
Attributes inherited from: Correspondence<Key,Item> |
Attributes inherited from: Iterable<Element,Absent> |
Methods | |
clone | Source Codeshared actual default List<Element> clone() A shallow copy of this list, that is, a list with the same elements as this list, which do not change if the elements of this list change. Refines Collection.clone |
collect | Source Codeshared actual default [Result+]|[] collect<Result>(Result collecting(Element element)) A sequence containing the results of applying the given mapping to the elements of this list. Refines Iterable.collect |
contains | Source Codeshared actual default Boolean contains(Object element) Determines if this list contains the given value.
Returns |
defines | Source Codeshared actual default Boolean defines(Integer index) Determines if the given index refers to an element of
this list, that is, if Refines Correspondence.defines |
endsWith | Source Codeshared default Boolean endsWith(List<Anything> sublist) Determine if the given list occurs at the end of this list. See also startsWith() |
equals | Source Codeshared actual default Boolean equals(Object that) Two
As a special exception, a Refines Object.equals |
find | Source Codeshared actual default Element? find(Boolean selecting(Element&Object elem)) The first element of this stream which is not null and
satisfies the given predicate function,
if any, or For example, the expression (-10..10).find(Integer.positive) evaluates to Refines Iterable.find |
findLast | Source Codeshared actual default Element? findLast(Boolean selecting(Element&Object elem)) The last element of this stream which is not null and
satisfies the given predicate function,
if any, or For example, the expression (-10..10).findLast(3.divides) evaluates to Refines Iterable.findLast |
firstIndexWhere | Source Codeshared default Integer? firstIndexWhere(Boolean selecting(Element&Object element)) The first index in this list for which the element is not null and satisfies the given predicate function. See also Iterable.locate() Since 1.1.0 |
get | Source Codeshared actual Element? get(Integer index) Returns the element of this list with the given
Refines Correspondence.get |
getFromFirst | Source Codeshared formal Element? getFromFirst(Integer index) Returns the element of this list with the given
See also getFromLast() Refines Iterable.getFromFirst |
getFromLast | Source Codeshared default Element? getFromLast(Integer index) |
indexesWhere | Source Codeshared default {Integer*} indexesWhere(Boolean selecting(Element&Object element)) The indexes in this list for which the element is not null and satisfies the given predicate function. See also Iterable.locations() Since 1.1.0 |
initial | Source Codeshared default List<Element> initial(Integer length) Select the first elements of this list, returning a
list no longer than the given length. If this list is
shorter than the given length, return this list.
Otherwise return a list of the given length. If
For any list.initial(length) == list[...length-1] == list[0:length] This is an eager operation. See also terminal() , sublistTo() , Iterable.take() |
iterator | Source Codeshared actual default Iterator<Element> iterator() An iterator for the elements belonging to this stream. If this is a nonempty stream with type Refines Iterable.iterator |
lastIndexWhere | Source Codeshared default Integer? lastIndexWhere(Boolean selecting(Element&Object element)) The last index in this list for which the element is not null and satisfies the given predicate function. See also Iterable.locateLast() Since 1.1.0 |
longerThan | Source Codeshared actual default Boolean longerThan(Integer length) Determines if this stream has more elements than the
given Refines Iterable.longerThan |
mapElements | Source Codeshared default List<Result> mapElements<Result>(Result mapping(Integer index, Element item)) Produces a list with the same indexes as this list. For every index, the element is the result of applying the given transformation function to its associated element in this list. This is a lazy operation, returning a view of this list. Parameters: Since 1.3.0 |
measure | Source Codeshared actual default List<Element> measure(Integer from, Integer length) Obtain a measure containing the mapped values starting
from the given starting index, with the given
For any ranged stream r[from:length] The measure should contain the given number
of elements of this stream, starting from the element
at the given starting index, in the same order
as they are produced by the When the given index does not belong to this ranged object, the behavior is implementation dependent. Refines Ranged.measure |
patch | Source Codeshared default List<Element|Other> patch<Other>(List<Other> list, Integer from = ..., Integer length = 0) Return a list formed by patching the given This is a lazy operations, returning a view over this list and the given list. Four special cases are interesting:
For example:
Finally, to patch a single element, leaving the
If Parameters:
Since 1.1.0 |
repeat | Source Codeshared actual default List<Element> repeat(Integer times) A list containing the elements of this list repeated
the given number of times, or an empty list
if list.repeat(n)[index]==list[index%n] This is a lazy operation returning a view of this list. Refines Iterable.repeat |
shorterThan | Source Codeshared actual default Boolean shorterThan(Integer length) Determines if this stream has fewer elements than the
given Refines Iterable.shorterThan |
slice | Source Codeshared default List<Element>[2] slice(Integer index) Return two lists, the first containing the elements
that occur before the given For any list.slice(index) == [list[...index-1], list[index...]] This is an eager operation. Since 1.1.0 |
span | Source Codeshared actual default List<Element> span(Integer from, Integer to) Obtain a span containing the elements between the two given indices. For any ranged stream r[from..to] The span should contain elements of this stream,
starting from the element at the given starting
index, and ending with the element at the given
ending index, in the same order as they are
produced by the When one or both of the given indices does not belong to this ranged stream, the behavior is implementation dependent. Refines Ranged.span |
spanFrom | Source Codeshared actual default List<Element> spanFrom(Integer from) Obtain a span containing the elements between the given starting index and the last index of this ranged object. For any ranged stream r[from...] The span should contain elements of this stream,
starting from the element at the given starting
index, in the same order as they are produced by
the When the given index does not belong to this ranged stream, the behavior is implementation dependent. Refines Ranged.spanFrom |
spanTo | Source Codeshared actual default List<Element> spanTo(Integer to) Obtain a span containing the elements between the first index of this ranged stream and given end index. For any ranged stream r[...to] The span should contain elements of this stream, up to
the element at the given ending index, in the
same order as they are produced by the When the given index does not belong to this ranged stream, the behavior is implementation dependent. Refines Ranged.spanTo |
startsWith | Source Codeshared default Boolean startsWith(List<Anything> sublist) Determine if the given list occurs at the start of this list. See also endsWith() |
sublist | Source Codeshared default List<Element> sublist(Integer from, Integer to) A sublist of this list, starting at the element with
index This is a lazy operation, returning a view of this list. See also sublistTo() , sublistFrom() Since 1.1.0 |
sublistFrom | Source Codeshared default List<Element> sublistFrom(Integer from) A sublist of this list, starting at the element with the given index. This is a lazy operation, returning a view of this list. See also Iterable.skip() , sublistTo() Since 1.1.0 |
sublistTo | Source Codeshared default List<Element> sublistTo(Integer to) A sublist of this list, ending at the element with the given index. This is a lazy operation, returning a view of this list. See also Iterable.take() , initial() , sublistFrom() Since 1.1.0 |
terminal | Source Codeshared default List<Element> terminal(Integer length) Select the last elements of the list, returning a list no longer than the given length. If this list is shorter than the given length, return this list. Otherwise return a list of the given length. For any list.terminal(length) == list[size-length...] This is an eager operation. See also initial() |
trim | Source Codeshared default List<Element> trim(Boolean trimming(Element&Object elem)) Trim the elements satisfying the given predicate function, along with any null elements, from the start and end of this list, returning a list no longer than this list. This is an eager operation. |
trimLeading | Source Codeshared default List<Element> trimLeading(Boolean trimming(Element&Object elem)) Trim the elements satisfying the given predicate function, along with any null elements, from the start of this list, returning a list no longer than this list. This is an eager operation. |
trimTrailing | Source Codeshared default List<Element> trimTrailing(Boolean trimming(Element&Object elem)) Trim the elements satisfying the given predicate function, along with any null elements, from the end of this list, returning a list no longer than this list. This is an eager operation. |
Inherited Methods |
Methods inherited from: Object |
Methods inherited from: Category<Element> |
Methods inherited from: Collection<Element> |
Methods inherited from: Correspondence<Key,Item> |
Methods inherited from: Iterable<Element,Absent> any() , by() , chain() , collect() , contains() , count() , defaultNullElements() , each() , every() , filter() , find() , findLast() , flatMap() , fold() , follow() , frequencies() , getFromFirst() , group() , indexes() , interpose() , iterator() , locate() , locateLast() , locations() , longerThan() , map() , max() , narrow() , partition() , product() , reduce() , repeat() , scan() , select() , sequence() , shorterThan() , skip() , skipWhile() , sort() , spread() , summarize() , tabulate() , take() , takeWhile() |
Methods inherited from: Ranged<Index,Element,Subrange> |