Sequences

A `Sequence` with exactly one `element`, which may be null.

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

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

no subtypes hierarchy

Initializer
`Singleton(Element element)`

Attributes
`coalesced` | Source Code `shared actual Singleton<Element&Object>|[] coalesced` The non-null elements of this stream, in the order in which they occur in this stream. For null elements of the original stream, there is no entry in the resulting stream. For example, the expression
    { "123", "abc", "456"}.map(parseInteger).coalesced
results in the stream `{ 123, 456 }`. Refines `Iterable.coalesced`
`cycled` | Source Code `shared actual {Element+} cycled` An infinite stream that produces the `element` of this singleton, repeatedly. For example, the expression
    Singleton(null).cycled.take(4)
evaluates to the stream `{ null, null, null, null }`. See also `Sequence.repeat()` Refines `Iterable.cycled`
`distinct` | Source Code `shared actual Singleton<Element> distinct` This singleton. Refines `Iterable.distinct`
`first` | Source Code `shared actual Element first` Returns the element contained in this `Singleton`. Refines `Sequence.first` ultimately refines `Iterable.first`
`hash` | Source Code `shared actual 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 `List.hash` ultimately refines `Object.hash`
`indexed` | Source Code `shared actual {<Integer->Element>+} indexed` A stream containing all entries of form `index->element` where `element` is an element of this stream, and `index` is the position at which `element` occurs in this stream, ordered by increasing `index`. For example, the expression
    { "hello", null, "world" }.indexed
results in the stream `{ 0->"hello", 1->null, 2->"world" }`. Refines `Iterable.indexed`
`last` | Source Code `shared actual Element last` Returns the element contained in this `Singleton`. Refines `Sequence.last` ultimately refines `Iterable.last`
`lastIndex` | Source Code `shared actual Integer lastIndex` Returns `0`. Refines `Sequence.lastIndex` ultimately refines `List.lastIndex`
`paired` | Source Code `shared actual [] paired` An empty stream. Refines `Iterable.paired`
`rest` | Source Code `shared actual [] rest` Returns `Empty`. Refines `Sequence.rest` ultimately refines `Iterable.rest`
`reversed` | Source Code `shared actual Singleton<Element> reversed` Return this singleton. Refines `Sequence.reversed` ultimately refines `List.reversed`
`size` | Source Code `shared actual Integer size` Returns `1`. Refines `Sequence.size` ultimately refines `Iterable.size`
`string` | Source Code `shared actual 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 `Sequence.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+]` `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 e))` 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`
`chain` | Source Code `shared actual {Element|Other+} chain<Other, OtherAbsent>(Iterable<Other,OtherAbsent> other) given OtherAbsent satisfies Null` The elements of this stream, in the order in which they occur in this stream, followed by the elements of the given stream in the order in which they occur in the given stream. For example, the expression
    (1..3).chain("abc")
evaluates to the stream `{ 1, 2, 3, 'a', 'b', 'c' }`. Refines `Iterable.chain`
`clone` | Source Code `shared actual Singleton<Element> clone()` Returns a `Singleton` with the same element. Refines `Sequence.clone` ultimately refines `Collection.clone`
`collect` | Source Code `shared actual Singleton<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)]
Refines `Sequence.collect` ultimately refines `Iterable.collect`
`contains` | Source Code `shared actual Boolean contains(Object element)` Returns `true` if the specified element is this `Singleton`'s element. Refines `Sequence.contains` ultimately refines `Category.contains`
`count` | Source Code `shared actual Integer count(Boolean selecting(Element element))` Returns `1` if this `Singleton`'s element satisfies the predicate, or `0` otherwise. 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`
`equals` | Source Code `shared actual Boolean equals(Object that)` A `Singleton` can be equal to another `List` if that `List` has only one element which is equal to this `Singleton`'s element. Refines `List.equals` ultimately refines `Object.equals`
`every` | Source Code `shared actual Boolean every(Boolean selecting(Element e))` 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 Singleton<Element>|[] filter(Boolean selecting(Element e))` 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 Element? find(Boolean selecting(Element&Object e))` 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 e))` 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`
`fold` | Source Code `shared actual Result fold<Result>(Result initial)(Result accumulating(Result partial, Element e))` 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|Element+} follow<Other>(Other head)` A stream with given `head`, followed by the `element` of this singleton. For example, the expression
    Singleton(1).follow(2)
evaluates to the stream `{ 2, 1 }`. Refines `Iterable.follow`
`getFromFirst` | Source Code `shared actual Element? getFromFirst(Integer index)` Returns the contained element, if the specified index is `0`. Refines `List.getFromFirst` ultimately refines `Iterable.getFromFirst`
`initial` | Source Code `shared actual []|Singleton<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. Refines `Sequential.initial` ultimately refines `List.initial`
`interpose` | Source Code `shared actual Singleton<Element> interpose<Other>(Other element, Integer step)` This singleton. Parameters: `step` step must be strictly positive Refines `Iterable.interpose`
`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`
`map` | Source Code `shared actual Singleton<Result> map<Result>(Result collecting(Element e))` 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 []|Singleton<Element> measure(Integer from, Integer length)` Returns a `Singleton` if the given starting index is `0` and the given `length` is greater than `0`. Otherwise, returns an instance of `Empty`. Refines `Sequence.measure` ultimately refines `Ranged.measure`
`reduce` | Source Code `shared actual Element reduce<Result>(Result accumulating(Result|Element partial, Element e))` 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`
`select` | Source Code `shared actual Singleton<Element>|[] select(Boolean selecting(Element 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`
`skip` | Source Code `shared actual Singleton<Element>|[] 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`
`slice` | Source Code `shared actual [[], Singleton<Element>]|[Singleton<Element>, []] 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 `Sequence.slice` ultimately refines `List.slice`
`sort` | Source Code `shared actual Singleton<Element> sort(Comparison comparing(Element a, Element 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 `Sequence.sort` ultimately refines `Iterable.sort`
`span` | Source Code `shared actual []|Singleton<Element> span(Integer from, Integer to)` Returns a `Singleton` if the given starting index is `0`. Otherwise, returns an instance of `Empty`. Refines `Sequence.span` ultimately refines `Ranged.span`
`spanFrom` | Source Code `shared actual []|Singleton<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 []|Singleton<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`
`take` | Source Code `shared actual Singleton<Element>|[] 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`
`terminal` | Source Code `shared actual []|Singleton<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. Refines `Sequential.terminal` ultimately refines `List.terminal`

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()`