Sequences

A nonempty, immutable sequence of values. The type `Sequence<Element>` may be abbreviated `[Element+]`.

Given a possibly-empty sequence of type `[Element*]`, the `if (nonempty ...)` construct, or, alternatively, `assert (nonempty ...)`, may be used to narrow to a sequence type to a nonempty sequence type:

    [Integer*] nums = ... ;
    if (nonempty nums) {
        Integer first = nums.first;
        Integer max = max(nums);
        [Integer+] squares = nums.collect((Integer i) => i**2));
        [Integer+] sorted = nums.sort(byIncreasing((Integer i) => i));
    }

Operations like `first`, `max()`, `collect()`, and `sort()`, which polymorphically produce a nonempty or non-null output when given a nonempty input are called emptiness-preserving.

`Sequence` has the following subtypes:

- `ArraySequence`, a sequence backed by an `Array`,
- `Range`, an efficient representation of a sequence of adjacent enumerable values,
- `Tuple`, a typed linked list, and
- `Singleton`, a sequence of just one element.

By: Gavin
See also `Empty`, `ArraySequence`, `Range`, `Tuple`, `Singleton`

no type hierarchy

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

- `Sequence`
  - `ArraySequence`
  - `Range`
  - `Singleton`
  - `Tuple`

Attributes
`empty` | Source Code `shared actual Boolean empty` Returns `false`, since every `Sequence` contains at least one element. Refines `Collection.empty` ultimately refines `Iterable.empty`
`exceptLast` | Source Code `shared actual default Element[] exceptLast` This sequence, without the last element. Since 1.3.3 Refines `Sequential.exceptLast` ultimately refines `Iterable.exceptLast`
`first` | Source Code `shared formal Element first` The first element of the sequence, that is, the element with index `0`. Refines `List.first` ultimately refines `Iterable.first`
`keys` | Source Code `shared actual default Range<Integer> keys` An integer `Range` containing all indexes of this sequence, that is, the range `0..sequence.lastIndex`. Refines `Sequential.keys` ultimately refines `Correspondence.keys`
`last` | Source Code `shared formal Element last` The last element of the sequence, that is, the element with index `sequence.lastIndex`. Refines `List.last` ultimately refines `Iterable.last`
`lastIndex` | Source Code `shared actual default Integer lastIndex` The index of the last element of the sequence. See also `size` Refines `List.lastIndex`
`rest` | Source Code `shared actual default Element[] rest` The rest of the sequence, without the first element. Refines `Sequential.rest` ultimately refines `Iterable.rest`
`reversed` | Source Code `shared actual default [Element+] reversed` A sequence containing the elements of this sequence in reverse order to the order in which they occur in this sequence. Refines `Sequential.reversed` ultimately refines `List.reversed`
`size` | Source Code `shared formal Integer size` The non-negative length of this sequence, that is, the number of elements in this sequence. Refines `Sequential.size` ultimately refines `Iterable.size`
`string` | Source Code `shared actual default String string` A developer-friendly string representing the instance. Concatenates the name of the concrete class of the instance with the `hash` of the instance. Subclasses are encouraged to refine this implementation to produce a more meaningful representation. Refines `Sequential.string` ultimately refines `Object.string`

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`
Attributes inherited from: `List<Element>` `first`, `hash`, `keys`, `last`, `lastIndex`, `rest`, `reversed`, `size`
Attributes inherited from: `Element[]` `exceptLast`, `keys`, `rest`, `reversed`, `size`, `string`

Methods
`append` | Source Code `shared actual default [Element|Other+] append<Other>(Other[] elements)` Return a nonempty sequence containing the elements of this sequence, followed by the given `elements`. Refines `Sequential.append`
`clone` | Source Code `shared actual default [Element+] clone()` This nonempty sequence. Refines `Sequential.clone` ultimately refines `Collection.clone`
`collect` | Source Code `shared actual default [Result+] collect<Result>(Result collecting(Element element))` A nonempty sequence containing the results of applying the given mapping to the elements of this sequence. Parameters: `collecting` The transformation applied to the elements. Refines `List.collect` ultimately refines `Iterable.collect`
`contains` | Source Code `shared actual default Boolean contains(Object element)` Returns `true` if the given value belongs to this `Category`, that is, if it is an element of this `Category`, or `false` otherwise. For any instance `c` of `Category`, `c.contains(element)` may be written using the `in` operator:
    element in c
For most `Category`s, the following relationship is satisfied by every pair of elements `x` and `y`: if `x==y`, then `x in category == y in category` However, it is possible to form a useful `Category` consistent with some other equivalence relation, for example `===`. Therefore implementations of `contains()` which do not satisfy this relationship are tolerated. Refines `Iterable.contains` ultimately refines `Category.contains`
`find` | Source Code `shared 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`. Refines `List.find` ultimately refines `Iterable.find`
`findLast` | Source Code `shared 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`. Refines `List.findLast` ultimately refines `Iterable.findLast`
`indexes` | Source Code `shared actual default Range<Integer> indexes()` An integer `Range` containing all indexes of this sequence, that is, the range `0..sequence.lastIndex`. Refines `Iterable.indexes`
`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 `List.longerThan` ultimately refines `Iterable.longerThan`
`measure` | Source Code `shared actual default 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. Refines `List.measure` ultimately refines `Ranged.measure`
`prepend` | Source Code `shared actual default [Element|Other+] prepend<Other>(Other[] elements)` Return a nonempty sequence containing the given `elements`, followed by the elements of this sequence. Refines `Sequential.prepend`
`repeat` | Source Code `shared actual default Element[] repeat(Integer times)` Produces a sequence formed by repeating the elements of this sequence the given number of times, or the empty sequence if `times<=0`. Refines `Sequential.repeat` ultimately refines `Iterable.repeat`
`sequence` | Source Code `shared actual default [Element+] sequence()` This nonempty sequence. Refines `Sequential.sequence` ultimately refines `Iterable.sequence`
`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 `List.shorterThan` ultimately refines `Iterable.shorterThan`
`slice` | Source Code `shared actual default 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. Refines `Sequential.slice` ultimately refines `List.slice`
`sort` | Source Code `shared actual default [Element+] sort(Comparison comparing(Element x, Element y))` A nonempty sequence containing the elements of this container, sorted according to a function imposing a partial order upon the elements. Parameters: `comparing` The function comparing pairs of elements. Refines `Iterable.sort`
`span` | Source Code `shared actual default 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 `List.span` ultimately refines `Ranged.span`
`spanFrom` | Source Code `shared actual default 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. Refines `List.spanFrom` ultimately refines `Ranged.spanFrom`
`spanTo` | Source Code `shared actual default 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. Refines `List.spanTo` ultimately refines `Ranged.spanTo`
`sublist` | Source Code `shared actual default 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.3.3 Refines `Sequential.sublist` ultimately refines `List.sublist`
`sublistFrom` | Source Code `shared actual default 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.3.3 Refines `Sequential.sublistFrom` ultimately refines `List.sublistFrom`
`sublistTo` | Source Code `shared actual default 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.3.3 Refines `Sequential.sublistTo` ultimately refines `List.sublistTo`
`tuple` | Source Code `shared actual default [Element+] tuple()` A `Tuple` with the same elements as this sequence. This operation makes it possible to narrow this sequence to a given static length, for example:
    assert (is String[3] bits
               = string.split('/'.equals)
                       .sequence()
                       .tuple);
    value [prefix, middle, postfix] = bits;
Since 1.3.3 Refines `Sequential.tuple`
`withLeading` | Source Code `shared actual default [Other, Element+] withLeading<Other>(Other element)` Return a nonempty sequence containing the given `element`, followed by the elements of this sequence. Refines `Sequential.withLeading`
`withTrailing` | Source Code `shared actual default [Element|Other+] withTrailing<Other>(Other element)` Return a nonempty sequence containing the elements of this sequence, followed by the given `element`. Refines `Sequential.withTrailing`

Inherited Methods
Methods inherited from: `Object` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`
Methods inherited from: `Collection<Element>` `clone()`, `combinations()`, `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: `List<Element>` `clone()`, `collect()`, `contains()`, `defines()`, `endsWith()`, `equals()`, `find()`, `findLast()`, `firstIndexWhere()`, `get()`, `getFromFirst()`, `getFromLast()`, `indexesWhere()`, `initial()`, `iterator()`, `lastIndexWhere()`, `longerThan()`, `mapElements()`, `measure()`, `patch()`, `repeat()`, `shorterThan()`, `slice()`, `span()`, `spanFrom()`, `spanTo()`, `startsWith()`, `sublist()`, `sublistFrom()`, `sublistTo()`, `terminal()`, `trim()`, `trimLeading()`, `trimTrailing()`
Methods inherited from: `Ranged<Index,Element,Subrange>` `measure()`, `span()`, `spanFrom()`, `spanTo()`
Methods inherited from: `Element[]` `append()`, `clone()`, `initial()`, `prepend()`, `repeat()`, `sequence()`, `slice()`, `sublist()`, `sublistFrom()`, `sublistTo()`, `terminal()`, `trim()`, `trimLeading()`, `trimTrailing()`, `tuple()`, `withLeading()`, `withTrailing()`