Collections

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

See also `Sequence`, `Empty`, `Array`

no type hierarchy

- `List`
  - `Collection`
    - `Iterable`
      - `Category`
  - `Correspondence`
  - `Ranged`
    - `Iterable`
      - `Category`

- `List`
  - `SearchableList`
    - `Array`
    - `String`
  - `Sequential`
    - `Empty`
      - `empty`
    - `Sequence`
      - `ArraySequence`
      - `Range`
      - `Singleton`
      - `Tuple`
  - `StringBuilder`

Attributes
`first` | Source Code `shared actual default Element? first` The first element of this `List`, if any. Refines `Iterable.first`
`hash` | Source Code `shared 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`. Because the `Integer` type is platform-dependent a compiler for a given platform is permitted to further manipulate the calculated hash for an object, and the resulting hash may differ between platforms. Refines `Object.hash`
`keys` | Source Code `shared 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 Code `shared actual default Element? last` The last element of this `List`, if any. Refines `Iterable.last`
`lastIndex` | Source Code `shared 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`
`rest` | Source Code `shared 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 Code `shared 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.
`size` | Source Code `shared actual default Integer size` The number of elements in this list, always `1 + (lastIndex else -1)`. See also `lastIndex` Refines `Iterable.size`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`
Attributes inherited from: `Collection<Element>` `empty`, `permutations`, `string`
Attributes inherited from: `Correspondence<Key,Item>` `keys`
Attributes inherited from: `Iterable<Element,Absent>` `coalesced`, `cycled`, `distinct`, `empty`, `exceptLast`, `first`, `indexed`, `last`, `paired`, `rest`, `size`, `string`

Methods
`clone` | Source Code `shared 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 Code `shared 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. Refines `Iterable.collect`
`contains` | Source Code `shared 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`
`defines` | Source Code `shared 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`. Refines `Correspondence.defines`
`endsWith` | Source Code `shared default Boolean endsWith(List<Anything> sublist)` Determine if the given list occurs at the end of this list. See also `startsWith()`
`equals` | Source Code `shared actual default Boolean equals(Object that)` Two `List`s 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`. Refines `Object.equals`
`find` | Source Code `shared actual default Element? find(Boolean selecting(Element&Object elem))` The first element of this stream which 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`. Refines `Iterable.find`
`findLast` | Source Code `shared actual default Element? findLast(Boolean selecting(Element&Object elem))` The last element of this stream which 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`. Refines `Iterable.findLast`
`firstIndexWhere` | Source Code `shared 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 See also `Iterable.locate()`
`get` | Source Code `shared 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`. Refines `Correspondence.get`
`getFromFirst` | Source Code `shared 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()` Refines `Iterable.getFromFirst`
`getFromLast` | Source Code `shared 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`.
`indexesWhere` | Source Code `shared 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 See also `Iterable.locations()`
`initial` | Source Code `shared 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. For any `list`, and for any integer `length`:
    list.initial(length) == list[...length-1] == list[0:length]
This is an eager operation. See also `terminal()`, `sublistTo()`, `Iterable.take()`
`iterator` | Source Code `shared actual default Iterator<Element> iterator()` An iterator for the elements belonging to this stream. Refines `Iterable.iterator`
`lastIndexWhere` | Source Code `shared 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. See also `Iterable.locateLast()`
`longerThan` | Source Code `shared 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. Refines `Iterable.longerThan`
`measure` | Source Code `shared 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. 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. Refines `Ranged.measure`
`patch` | Source Code `shared 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}`, and `[-2, 2].patch(-1..1,1)` produces the list `{-2,-1,0,1,2}`.' `0:3`.patch(2..0) produces the list `{0,1,2,2,1,0}`. 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.
`repeat` | Source Code `shared 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. Refines `Iterable.repeat`
`shorterThan` | Source Code `shared 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. Refines `Iterable.shorterThan`
`slice` | Source Code `shared 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 indices 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.
`span` | Source Code `shared actual default List<Element> span(Integer from, Integer to)` Obtain a span containing the elements between the two given indices. 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`
`spanFrom` | Source Code `shared 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. 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. Refines `Ranged.spanFrom`
`spanTo` | Source Code `shared 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. 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. Refines `Ranged.spanTo`
`startsWith` | Source Code `shared default Boolean startsWith(List<Anything> sublist)` Determine if the given list occurs at the start of this list. See also `endsWith()`
`sublist` | Source Code `shared 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.
`sublistFrom` | Source Code `shared 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` | Source Code `shared 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()`
`terminal` | Source Code `shared 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()`
`trim` | Source Code `shared 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.
`trimLeading` | Source Code `shared 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.
`trimTrailing` | Source Code `shared 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` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`
Methods inherited from: `Collection<Element>` `clone()`, `contains()`
Methods inherited from: `Correspondence<Key,Item>` `defines()`, `definesAny()`, `definesEvery()`, `get()`, `getAll()`
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>` `measure()`, `span()`, `spanFrom()`, `spanTo()`