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.

  • For any nonempty list, lastIndex==size-1.
  • For an empty list, 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 Lists, and are all of fixed length. Variable-length mutable Lists are also possible.

See also Sequence, Empty, Array

no type hierarchy

Attributes
firstSource Codeshared actual default Element? first

The first element of this List, if any.

hashSource 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:

  • if x==y then x.hash==y.hash.

Therefore, a class which refines Object.equals() must also refine hash.

In general, hash values vary between platforms and between executions of the same program.

Note that when executing on a Java Virtual Machine, the 64-bit Integer value returned by an implementation of hash is truncated to a 32-bit integer value by taking the exclusive disjunction of the 32 lowest-order bits with the 32 highest-order bits, before returning the value to the caller.

Refines Object.hash
keysSource 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.

lastSource Codeshared actual default Element? last

The last element of this List, if any.

lastIndexSource Codeshared formal Integer? lastIndex

The index of the last element of the list, or null if the list is empty. Always size>0 then size-1.

See also size
restSource 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.

reversedSource 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 index of a reversed list:

list.reversed[index]==list[size-1-index]

This is a lazy operation returning a view of this list.

sizeSource Codeshared actual default Integer size

The number of elements in this list, always 1 + (lastIndex else -1).

See also lastIndex
Inherited Attributes
Attributes inherited from: Object
Attributes inherited from: Collection<Element>
Attributes inherited from: Correspondence<Key,Item>
Attributes inherited from: Iterable<Element,Absent>
Methods
cloneSource 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.

collectSource 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.

Parameters:
  • collecting

    The transformation applied to the elements.

containsSource Codeshared actual default Boolean contains(Object element)

Determines if this list contains the given value. Returns true for every element of this list.

Refines Collection.contains ultimately refines Category.contains
definesSource Codeshared actual default Boolean defines(Integer index)

Determines if the given index refers to an element of this list, that is, if 0<=index<=list.lastIndex.

endsWithSource Codeshared default Boolean endsWith(List<Anything> sublist)

Determine if the given list occurs at the end of this list.

See also startsWith()
equalsSource Codeshared actual default Boolean equals(Object that)

Two Lists are considered equal iff they have the same size and entry sets. The entry set of a list list is the set of elements of list.indexed. This definition is equivalent to the more intuitive notion that two lists are equal iff they have the same size and for every index either:

  • the lists both have the element null, or
  • the lists both have a non-null element, and the two elements are equal.

As a special exception, a String is not equal to any list which is not also a String.

findSource 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 null if there is no such element. For an infinite stream, this method might not terminate.

For example, the expression

(-10..10).find(Integer.positive)

evaluates to 1.

findLastSource 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 null if there is no such element. For an infinite stream, this method will not terminate.

For example, the expression

(-10..10).findLast(3.divides)

evaluates to 9.

firstIndexWhereSource 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.

Parameters:
  • selecting

    The predicate function the indexed elements must satisfy.

Since 1.1.0
getSource Codeshared actual Element? get(Integer index)

Returns the element of this list with the given index if the index refers to an element of this list, that is, if 0<=index<=list.lastIndex, or null otherwise. The first element of the list has index 0, and the last element has index lastIndex.

getFromFirstSource Codeshared formal Element? getFromFirst(Integer index)

Returns the element of this list with the given index if the index refers to an element of this list, that is, if 0<=index<=list.lastIndex, or null otherwise. The first element of the list has index 0, and the last element has index lastIndex.

See also getFromLast()
getFromLastSource Codeshared default Element? getFromLast(Integer index)

Returns the element of this list with the given index, where the list is indexed from the end of the list instead of from the start, if the index refers to an element of this list, or null otherwise. The last element of the list has index 0, and the first element has index lastIndex.

Since 1.1.0
indexesWhereSource 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.

Parameters:
  • selecting

    The predicate function the indexed elements must satisfy.

Since 1.1.0
initialSource 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 length<=0 return an empty list.

For any list, and for any integer length:

list.initial(length) == list[...length-1] == list[0:length]

This is an eager operation.

iteratorSource Codeshared actual default Iterator<Element> iterator()

An iterator for the elements belonging to this stream.

If this is a nonempty stream with type {Element+}, the iterator must produce at least one element.

lastIndexWhereSource 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.

Parameters:
  • selecting

    The predicate function the indexed elements must satisfy.

Since 1.1.0
longerThanSource Codeshared actual default Boolean longerThan(Integer length)

Determines if this stream has more elements than the given length. This is an efficient operation for streams with many elements.

mapElementsSource 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:
  • mapping

    The function that transforms an index/item pair of this list, producing the element of the resulting list.

Since 1.3.0
measureSource 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 length. If length<=0, the resulting measure is empty.

For any ranged stream r, r.measure(from, length) may be written using the measure operator:

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 Iterable.iterator() of the stream. In the case where the iterator would be exhausted before length elements are produced, the resulting measure contains only those elements which were produced before the iterator was exhausted, and the length of the measure is less then the given length.

When the given index does not belong to this ranged object, the behavior is implementation dependent.

patchSource Codeshared default List<Element|Other> patch<Other>(List<Other> list, Integer from = ..., Integer length = 0)

Return a list formed by patching the given list in place of a segment of this list identified by the given starting index and length.

This is a lazy operations, returning a view over this list and the given list.

Four special cases are interesting:

  • If length==0, the patched list has the given values “inserted” into this list at the given index from.
  • If the given list is empty, the patched list has the measure of this list identified by from:length “deleted”.
  • If from==size, the patched list is formed by appending the given list.
  • If from==0, the patched list is formed by prepending the given list.

For example:

  • (-2..2).patch([], 1, 3) produces the list {-2, 2},
  • [-2, 2].patch(-1..1, 1) produces the list {-2, -1, 0, 1, 2}, and
  • 0:3.patch(2..0) produces the list {0, 1, 2, 2, 1, 0}.

Finally, to patch a single element, leaving the size of the list unchanged, explicitly specify length==1:

  • [0, 1, 0, 1].patch([-1], 2, 1) produces the list {0, 1, -1, 1}.

If length<0, or if from is outside the range 0..size, return this list.

Parameters:
  • list

    The list of new elements.

  • from = size

    The index at which the elements will occur, and the start index of the segment to replace.

  • length = 0

    The length of the segment to replace.

Since 1.1.0
repeatSource 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 times<=0. For every index of a repeated list:

list.repeat(n)[index]==list[index%n]

This is a lazy operation returning a view of this list.

shorterThanSource Codeshared actual default Boolean shorterThan(Integer length)

Determines if this stream has fewer elements than the given length. This is an efficient operation for streams with many elements.

sliceSource Codeshared default List<Element>[2] slice(Integer index)

Return two lists, the first containing the elements that occur before the given index, the second with the elements that occur after the given index. If the given index is outside the range of indexes of this list, one of the returned lists will be empty.

For any list, and for any integer index:

list.slice(index) == [list[...index-1], list[index...]]

This is an eager operation.

Since 1.1.0
spanSource 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, r.span(from, to) may be written using the span operator:

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 Iterable.iterator() of the stream, except when the ending index occurs earlier than the starting index, in which case they occur in the opposite order.

When one or both of the given indices does not belong to this ranged stream, the behavior is implementation dependent.

Refines Ranged.span
spanFromSource 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, r.spanFrom(from) may be written using the span operator:

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 Iterable.iterator() of the stream.

When the given index does not belong to this ranged stream, the behavior is implementation dependent.

spanToSource 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, r.spanTo(to) may be written using the span operator:

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 Iterable.iterator() of the stream.

When the given index does not belong to this ranged stream, the behavior is implementation dependent.

startsWithSource Codeshared default Boolean startsWith(List<Anything> sublist)

Determine if the given list occurs at the start of this list.

See also endsWith()
sublistSource Codeshared default List<Element> sublist(Integer from, Integer to)

A sublist of this list, starting at the element with index from, ending at the element with the index to.

This is a lazy operation, returning a view of this list.

Since 1.1.0
sublistFromSource 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.

Since 1.1.0
sublistToSource 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.

Since 1.1.0
terminalSource 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, and for any integer length:

list.terminal(length) == list[size-length...]

This is an eager operation.

See also initial()
trimSource 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.

Parameters:
  • trimming

    The predicate function that the trimmed elements satisfy.

trimLeadingSource 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.

Parameters:
  • trimming

    The predicate function that the trimmed elements satisfy.

trimTrailingSource 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.

Parameters:
  • trimming

    The predicate function that the trimmed elements satisfy.

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>
Methods inherited from: Ranged<Index,Element,Subrange>