Sequences

A sequence with no elements. The type `Empty` may be abbreviated `[]`, and an instance is produced by the expression `[]`. That is, in the following expression, `none` has type `[]` and refers to the value `[]`:

    [] none = [];

(Whether the syntax `[]` refers to the type or the value depends upon how it occurs grammatically.)

See also `Sequence`

no type hierarchy

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

- `Empty` of
  - `empty`

Attributes
`coalesced` | Source Code `shared actual [] coalesced` Returns `[]`. Refines `Iterable.coalesced`
`cycled` | Source Code `shared actual [] cycled` Returns `[]`. Refines `Iterable.cycled`
`empty` | Source Code `shared actual Boolean empty` Returns `true`. Refines `Collection.empty` ultimately refines `Iterable.empty`
`exceptLast` | Source Code `shared actual [] exceptLast` Returns `[]`. Since 1.3.3 Refines `Sequential.exceptLast` ultimately refines `Iterable.exceptLast`
`first` | Source Code `shared actual Null first` Returns `null`. Refines `List.first` ultimately refines `Iterable.first`
`indexed` | Source Code `shared actual [] indexed` Returns `[]`. Refines `Iterable.indexed`
`keys` | Source Code `shared actual [] keys` Returns `[]`. Refines `Sequential.keys` ultimately refines `Correspondence.keys`
`last` | Source Code `shared actual Null last` Returns `null`. Refines `List.last` ultimately refines `Iterable.last`
`lastIndex` | Source Code `shared actual Null lastIndex` Returns `null`. Refines `List.lastIndex`
`paired` | Source Code `shared actual [] paired` Returns `[]`. Refines `Iterable.paired`
`rest` | Source Code `shared actual [] rest` Returns `[]`. Refines `Sequential.rest` ultimately refines `Iterable.rest`
`reversed` | Source Code `shared actual [] reversed` Returns `[]`. Refines `Sequential.reversed` ultimately refines `List.reversed`
`size` | Source Code `shared actual Integer size` Returns 0. Refines `Sequential.size` ultimately refines `Iterable.size`
`string` | Source Code `shared actual String string` Returns a string description of the empty sequence: `[]`. 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
`any` | Source Code `shared actual Boolean any(Boolean selecting(Nothing 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`
`append` | Source Code `shared actual Other[] append<Other>(Other[] elements)` Return a sequence containing the elements of this sequence, in the order in which they occur in this sequence, followed by the given `elements`, in the order in which they occur in the given sequence. Refines `Sequential.append`
`by` | Source Code `shared actual [] by(Integer step)` Produces a stream containing every `step`th element of this stream. If the step size is `1`, the resulting stream contains the same elements as this stream. For example, the expression
    (0..10).by(3)
results in the stream `{ 0, 3, 6, 9 }`. The step size must be greater than zero. Refines `Iterable.by`
`chain` | Source Code `shared actual Iterable<Other,OtherAbsent> chain<Other, OtherAbsent>(Iterable<Other,OtherAbsent> other) given OtherAbsent satisfies Null` Returns the given `other` iterable object. Refines `Iterable.chain`
`clone` | Source Code `shared actual [] clone()` Returns `[]`. Refines `Sequential.clone` ultimately refines `Collection.clone`
`collect` | Source Code `shared actual [] collect<Result>(Result collecting(Nothing 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)]
Refines `List.collect` ultimately refines `Iterable.collect`
`contains` | Source Code `shared actual Boolean contains(Object element)` Returns `false` for any given element. Refines `List.contains` ultimately refines `Category.contains`
`count` | Source Code `shared actual Integer count(Boolean selecting(Nothing element))` Returns 0 for any given predicate. Refines `Iterable.count`
`defaultNullElements` | Source Code `shared actual [] defaultNullElements<Default>(Default defaultValue) given Default satisfies Object` Produces a stream containing the elements of this stream, in the order in which they occur in this stream, after replacing every `null` element in the stream with the given default value. The value `null` does not ocur in the resulting stream. For example, the expression
    { "123", "abc", "456" }.map(parseInteger).defaultNullElements(0)
results in the stream `{ 123, 0, 456 }`. Refines `Iterable.defaultNullElements`
`defines` | Source Code `shared actual Boolean defines(Integer index)` Returns `false` for any given index. Refines `List.defines` ultimately refines `Correspondence.defines`
`each` | Source Code `shared actual void each(void step(Nothing 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(Nothing 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`
`filter` | Source Code `shared actual [] filter(Boolean selecting(Nothing element))` Produces a stream containing the elements of this stream that satisfy the given predicate function. For any empty stream, `filter()` returns an empty stream:
    {}.filter(p) == {}
For any nonempty stream `it`, and predicate `p`, the result of `filter()` may be obtained according to this recursive definition:
    it.filter(p) == { if (p(it.first)) it.first }.chain(it.rest.filter(f))
Alternatively, and in practice, `filter()` may be defined by this comprehension:
    it.filter(p) == { for (e in it) if (p(e)) e };
For example, the expression
    (1..100).filter(13.divides)
results in the stream `{ 13, 26, 39, 52, 65, 78, 91 }`. Refines `Iterable.filter`
`find` | Source Code `shared actual Null find(Boolean selecting(Nothing 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 `List.find` ultimately refines `Iterable.find`
`firstIndexWhere` | Source Code `shared actual Null firstIndexWhere(Boolean selecting(Nothing element))` The first index in this list for which the element is not null and satisfies the given predicate function. Refines `List.firstIndexWhere`
`flatMap` | Source Code `shared actual [] flatMap<Result, OtherAbsent>(Iterable<Result,OtherAbsent> collecting(Nothing element)) given OtherAbsent satisfies Null` Given a mapping function that accepts an `Element` and returns a stream of `Result`s, produces a new stream containing all elements of every `Result` stream that results from applying the function to the elements of this stream. For example, the expression
    { "Hello", "World" }.flatMap(String.lowercased)
results in this stream:
    { 'h', 'e', 'l', 'l', 'o', 'w', 'o', 'r,' 'l', 'd' }
The expression
    { "hello"->"hola", "world"->"mundo" }
            .flatMap(Entry<String,String>.pair)
produces this stream:
    { "hello", "hola", "world", "mundo" }
Refines `Iterable.flatMap`
`fold` | Source Code `shared actual Result fold<Result>(Result initial)(Result accumulating(Result partial, Nothing element))` Beginning with a given initial value, apply the given combining function to each element of this stream in turn, progressively accumulating a single result. For an empty stream, `fold()` returns the given initial value `z`:
    {}.fold(z)(f) == z
For a given nonempty stream `it`, initial value `z`, and combining function `f`, the result of `fold()` is obtained according to the following recursive definition:
    it.fold(z)(f) == f(it.exceptLast.fold(z)(f), it.last)
For example, the expression
    (1..100).fold(0)(plus)
results in the integer `5050`. Refines `Iterable.fold`
`follow` | Source Code `shared actual {Other+} follow<Other>(Other head)` Produces a stream with a given initial element, followed by the elements of this stream, in the order in which they occur in this stream. For example, the expression
    (1..3).follow(0)
evaluates to the stream `{ 0, 1, 2, 3 }`. Note that the expression `stream.follow(head)` eagerly evaluates `head`, and therefore is not precisely the same as this enumeration expression, where `head` is evaluated lazily:
    { head, *stream }
Refines `Iterable.follow`
`getFromFirst` | Source Code `shared actual Null getFromFirst(Integer index)` Returns `null` for any given index. Refines `List.getFromFirst` ultimately refines `Iterable.getFromFirst`
`getFromLast` | Source Code `shared actual Null getFromLast(Integer index)` Returns `null` for any given index. Refines `List.getFromLast`
`indexes` | Source Code `shared actual [] indexes()` Returns `[]`. Refines `Iterable.indexes`
`indexesWhere` | Source Code `shared actual [] indexesWhere(Boolean selecting(Nothing element))` The indexes in this list for which the element is not null and satisfies the given predicate function. Refines `List.indexesWhere`
`initial` | Source Code `shared actual [] 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. Refines `Sequential.initial` ultimately refines `List.initial`
`iterator` | Source Code `shared actual Iterator<Nothing> iterator()` Returns an iterator that is already exhausted. Refines `List.iterator` ultimately refines `Iterable.iterator`
`lastIndexWhere` | Source Code `shared actual Null lastIndexWhere(Boolean selecting(Nothing element))` The last index in this list for which the element is not null and satisfies the given predicate function. Refines `List.lastIndexWhere`
`map` | Source Code `shared actual [] map<Result>(Result collecting(Nothing element))` Produces a stream containing the results of applying the given mapping to the elements of this stream. For any empty stream, `map()` returns an empty stream:
    {}.map(f) == {}
For any nonempty stream `it`, and mapping function `f`, the result of `map()` may be obtained according to this recursive definition:
    it.map(f).first == f(it.first)
    it.map(f).rest == it.rest.map(f)
Alternatively, and in practice, `map()` may be defined by this comprehension:
    it.map(f) == { for (e in it) f(e) }
For example, the expression
    (0..4).map(10.power)
results in the stream `{ 1, 10, 100, 1000, 10000 }`. Refines `Iterable.map`
`measure` | Source Code `shared actual [] measure(Integer from, Integer length)` Returns `[]` for any given measure. Refines `List.measure` ultimately refines `Ranged.measure`
`prepend` | Source Code `shared actual Other[] prepend<Other>(Other[] elements)` Return a sequence containing the given `elements`, in the order in which they occur in the given sequence, followed by the elements of this sequence, in the order in which they occur in this sequence. Refines `Sequential.prepend`
`reduce` | Source Code `shared actual Null reduce<Result>(Result accumulating(Result partial, Nothing 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`. Refines `Iterable.reduce`
`repeat` | Source Code `shared actual [] repeat(Integer times)` Returns `[]`. Refines `Sequential.repeat` ultimately refines `Iterable.repeat`
`select` | Source Code `shared actual [] select(Boolean selecting(Nothing element))` Produce a new sequence containing all elements of this stream that satisfy the given predicate function, in the order in which they occur in this stream. This operation is an eager counterpart to `Iterable.filter()`. For any stream `it`, and predicate `p`:
    it.select(p) == [*it.filter(p)]
Refines `Iterable.select`
`sequence` | Source Code `shared actual [] sequence()` Returns `[]`. Refines `Sequential.sequence` ultimately refines `Iterable.sequence`
`skip` | Source Code `shared actual [] skip(Integer skipping)` Produces a stream containing the elements of this stream, after skipping the first `skipping` elements produced by its iterator. If this stream does not contain more elements than the specified number of elements to skip, the resulting stream has no elements. If the specified number of elements to skip is zero or fewer, the resulting stream contains the same elements as this stream. Refines `Iterable.skip`
`skipWhile` | Source Code `shared actual [] skipWhile(Boolean skipping(Nothing elem))` Produces a stream containing the elements of this stream, after skipping the leading elements until the given predicate function returns `false`. Refines `Iterable.skipWhile`
`slice` | Source Code `shared actual [][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 [] sort(Comparison comparing(Nothing a, Nothing b))` 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. Refines `Iterable.sort`
`span` | Source Code `shared actual [] span(Integer from, Integer to)` Returns `[]` for any given span. Refines `List.span` ultimately refines `Ranged.span`
`spanFrom` | Source Code `shared actual [] spanFrom(Integer from)` Returns `[]` for any given span. Refines `List.spanFrom` ultimately refines `Ranged.spanFrom`
`spanTo` | Source Code `shared actual [] spanTo(Integer to)` Returns `[]` for any given span. Refines `List.spanTo` ultimately refines `Ranged.spanTo`
`spread` | Source Code `shared actual [](*Args) spread<Result, Args>(Result(*Args) method(Nothing element)) given Args satisfies Anything[]` Given a `method()` of the element type `Element`, return a function that, when supplied with a list of method arguments, produces a new iterable object that applies the `method` to each element of this iterable object in turn.
    {Boolean+}(Object) fun = (-1..1).spread(Object.equals);
    print(fun(0)); //prints { false, true, false }
Refines `Iterable.spread`
`sublist` | Source Code `shared actual [] 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. Refines `Sequential.sublist` ultimately refines `List.sublist`
`sublistFrom` | Source Code `shared actual [] 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. Refines `Sequential.sublistFrom` ultimately refines `List.sublistFrom`
`sublistTo` | Source Code `shared actual [] 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. Refines `Sequential.sublistTo` ultimately refines `List.sublistTo`
`take` | Source Code `shared actual [] take(Integer taking)` Produces a stream containing the first `taking` elements of this stream. If the specified number of elements to take is larger than the number of elements of this stream, the resulting stream contains the same elements as this stream. If the specified number of elements to take is fewer than one, the resulting stream has no elements. Refines `Iterable.take`
`takeWhile` | Source Code `shared actual [] takeWhile(Boolean taking(Nothing elem))` Produces a stream containing the leading elements of this stream until the given predicate function returns `false`. Refines `Iterable.takeWhile`
`terminal` | Source Code `shared actual [] 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. Refines `Sequential.terminal` ultimately refines `List.terminal`
`trim` | Source Code `shared actual [] trim(Boolean trimming(Nothing 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. Refines `Sequential.trim` ultimately refines `List.trim`
`trimLeading` | Source Code `shared actual [] trimLeading(Boolean trimming(Nothing 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. Refines `Sequential.trimLeading` ultimately refines `List.trimLeading`
`trimTrailing` | Source Code `shared actual [] trimTrailing(Boolean trimming(Nothing 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. Refines `Sequential.trimTrailing` ultimately refines `List.trimTrailing`
`tuple` | Source Code `shared actual [] tuple()` Returns `[]`. Since 1.3.3 Refines `Sequential.tuple`
`withLeading` | Source Code `shared actual [Other] withLeading<Other>(Other element)` Returns a new sequence that starts with the specified `element`, followed by the elements of this sequence, in the order they occur in this sequence. Refines `Sequential.withLeading`
`withTrailing` | Source Code `shared actual [Other] withTrailing<Other>(Other element)` Returns a new sequence that starts with the elements of this sequence, in the order they occur in this sequence, and ends with the specified `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()`