Collections Sequences

A `Sequence` backed by an `Array`.

Since `Array`s are mutable, this class is private to the language module, where we can be sure the `Array` is not modified after the `ArraySequence` has been initialized.

By: Tom
See also `seq()`

- `Anything`
  - `Object`
    - `ArraySequence` ...and other supertypes

- `ArraySequence`
  - `Object`
    - `Anything`
  - `Sequence`
    - `Iterable`
      - `Category`
    - `Sequential`
      - `List`
        - `Collection`
          - `Iterable`
            - `Category`
        - `Correspondence`
        - `Ranged`
          - `Iterable`
            - `Category`
      - `Ranged`
        - `Iterable`
          - `Category`

no subtypes hierarchy

Initializer
`ArraySequence(Array<Element> array)`

Attributes
`first` | Source Code `shared actual Element first` The first element returned by the iterator, if any, or `null` if this stream is empty. For a stream with an unstable iteration order, a different value might be produced each time `first` is evaluated. Refines `Sequence.first` ultimately refines `Iterable.first`
`last` | Source Code `shared actual Element last` The last element returned by the iterator, if any, or `null` if this stream is empty. In the case of an infinite stream, this operation never terminates; furthermore, this default implementation iterates all elements, which might be very expensive. Refines `Sequence.last` ultimately refines `Iterable.last`
`rest` | Source Code `shared actual Element[] rest` A stream containing all but the first element of this stream. For a stream with an unstable iteration order, a different stream might be produced each time `rest` is evaluated. Therefore, if the stream `i` has an unstable iteration order, the stream `{ i.first, *i.rest }` might not have the same elements as `i`. Refines `Sequence.rest` ultimately refines `Iterable.rest`
`size` | Source Code `shared actual Integer size` The number of elements returned by the `Iterable.iterator()` of this stream, if the iterator terminates. In the case of an infinite stream, this operation never terminates. Refines `Sequence.size` ultimately 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`
Attributes inherited from: `List<Element>` `first`, `hash`, `keys`, `last`, `lastIndex`, `rest`, `reversed`, `size`
Attributes inherited from: `[Element+]` `empty`, `first`, `keys`, `last`, `lastIndex`, `rest`, `reversed`, `size`, `string`
Attributes inherited from: `Element[]` `keys`, `rest`, `reversed`, `size`, `string`

Methods
`any` | Source Code `shared actual Boolean any(Boolean selecting(Element element))` Determines if there is at least one element of this stream that satisfies the given predicate function. If the stream is empty, returns `false`. For an infinite stream, this operation might not terminate. Refines `Iterable.any`
`clone` | Source Code `shared actual [Element+] clone()` A shallow copy of this collection, that is, a collection with identical elements which does not change if this collection changes. If this collection is immutable, it is acceptable to return a reference to this collection. If this collection is mutable, a newly instantiated collection must be returned. Refines `Sequence.clone` ultimately refines `Collection.clone`
`collect` | Source Code `shared actual [Result+] collect<Result>(Result collecting(Element element))` Produce a new sequence containing the results of applying the given mapping to the elements of this stream. This operation is an eager counterpart to `Iterable.map()`. For any stream `it`, and mapping `f`:
    it.collect(f) == [*it.map(f)]
Parameters: `collecting` `nonempty sequence = array.collect(collecting)` Refines `Sequence.collect` ultimately refines `Iterable.collect`
`contains` | Source Code `shared actual 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 `Sequence.contains` ultimately refines `Category.contains`
`count` | Source Code `shared actual Integer count(Boolean selecting(Element element))` Produces the number of elements in this stream that satisfy the given predicate function. For an infinite stream, this method never terminates. Refines `Iterable.count`
`each` | Source Code `shared actual void each(void step(Element element))` Call the given function for each element of this stream, passing the elements in the order they occur in this stream. For example:
    words.each((word) {
        print(word.lowercased);
        print(word.uppercased);
    });
Has the same effect as the following `for` loop:
    for (word in words) {
        print(word.lowercased);
        print(word.uppercased);
    }
For certain streams this method is highly efficient, surpassing the performance of `for` loops on the JVM. Thus, `each()` is sometimes preferred in highly performance-critical low-level code. Refines `Iterable.each`
`every` | Source Code `shared actual Boolean every(Boolean selecting(Element element))` Determines if all elements of this stream satisfy the given predicate function. If the stream is empty, return `true`. For an infinite stream, this operation might not terminate. Refines `Iterable.every`
`find` | Source Code `shared actual Element? find(Boolean selecting(Element&Object element))` 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 `Sequence.find` ultimately refines `Iterable.find`
`findLast` | Source Code `shared actual Element? findLast(Boolean selecting(Element&Object element))` 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 `Sequence.findLast` ultimately refines `Iterable.findLast`
`getFromFirst` | Source Code `shared actual Element? getFromFirst(Integer index)` The `index`th element returned by an iterator of this stream, or `null` if there are fewer than `index+1` elements in the stream. For a stream with an unstable iteration order, a different value might be produced each time `getFromFirst(index)` is called for a given integer `index`. Refines `List.getFromFirst` ultimately refines `Iterable.getFromFirst`
`iterator` | Source Code `shared actual 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. Refines `List.iterator` ultimately refines `Iterable.iterator`
`measure` | Source Code `shared actual 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 `Sequence.measure` ultimately refines `Ranged.measure`
`reduce` | Source Code `shared actual Result|Element reduce<Result>(Result accumulating(Result|Element partial, Element element))` Beginning with the `Iterable.first` element of this stream, apply the given combining function to each element of this stream in turn, progressively accumulating a single result. For an empty stream, `reduce()` always returns `null`. For a stream with one element, `reduce()` returns that element:
    { first }.reduce(f) == first
For a given stream `it` with more than one element, and combining function `f`, the result of `reduce()` is obtained according to the following recursive definition:
    it.reduce(f) == f(it.exceptLast.reduce(f), it.last)
For example, the expression
    (1..100).reduce(plus)
results in the integer `5050`. Parameters: `accumulating` `exists result = array.reduce(accumulating)` Refines `Iterable.reduce`
`sort` | Source Code `shared actual [Element+] sort(Comparison comparing(Element x, Element y))` Produce a new sequence containing the elements of this stream, sorted according to the given comparator function imposing a partial order upon the elements of the stream. For convenience, the functions `byIncreasing()` and `byDecreasing()` produce suitable comparator functions. For example, this expression
    "Hello World!".sort(byIncreasing(Character.lowercased))
evaluates to the sequence `[ , !, d, e, H, l, l, l, o, o, r, W].` This operation is eager by nature. Note that the toplevel function `sort()` may be used to sort a stream of `Comparable` values according to the natural order of its elements. Parameters: `comparing` `nonempty sequence = array.sort(comparing)` Refines `Sequence.sort` ultimately refines `Iterable.sort`
`span` | Source Code `shared actual 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 `Sequence.span` ultimately refines `Ranged.span`
`spanFrom` | Source Code `shared actual ArraySequence<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 `Sequence.spanFrom` ultimately refines `Ranged.spanFrom`
`spanTo` | Source Code `shared actual ArraySequence<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 `Sequence.spanTo` ultimately refines `Ranged.spanTo`

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()`, `collect()`, `contains()`, `find()`, `findLast()`, `indexes()`, `longerThan()`, `measure()`, `prepend()`, `repeat()`, `sequence()`, `shorterThan()`, `slice()`, `sort()`, `span()`, `spanFrom()`, `spanTo()`, `withLeading()`, `withTrailing()`
Methods inherited from: `Element[]` `append()`, `clone()`, `initial()`, `prepend()`, `repeat()`, `sequence()`, `slice()`, `terminal()`, `trim()`, `trimLeading()`, `trimTrailing()`, `withLeading()`, `withTrailing()`