Streams

Abstract supertype of categories whose elements may be iterated. Iterable categories are often called streams. A stream is a source of `Iterator`s, which produce the elements of the stream. A given element may occur more than once in a stream, that is, it may be produced more than once by a given iterator of the stream.

A stream may have null elements. That is, an iterator for the stream may produce the value `null` one or more times. For every non-null `element` of a given stream `it`, the expression `element in it` must evaluate to `true`. Thus, a stream is a `Category` of its non-null elements.

A finite stream is a stream whose iterators are exhaustible, that is, they eventually stop producing elements. A stream need not be finite, but its elements must be countable. That is, for any given element of the stream, every `Iterator` of the stream must eventually return the element, even if the iterator itself is not exhaustible. It is possible for a given element to occur a (countably) infinite number of times in a nonfinite stream. It may not, in general, be possible to even determine if an insteance of `Iterable` is finite.

For a nonfinite stream, certain operations of this interface either never terminate or result in an `AssertionError`.

A stream may be mutable, in which case two distinct iterators for the stream might not produce exactly the same elements. Furthermore, even an immutable stream might not have a well-defined order, and so the order in which elements are produced by the stream's iterator may not be stable. That is, the order may be different for two distinct iterators of the stream.

However, a stream has a well-defined set of elements, and so any two iterators for an immutable finite stream should eventually return the same elements. Furthermore, any two iterators for an immutable finite stream should eventually return exactly the same total number of elements, which must be the `size` of the stream. For an immutable nonfinite stream, every element returned by a given iterator must eventually be returned by any other iterator of the stream.

A stream may be known to be nonempty:

- The type `Iterable<Element,Null>`, usually abbreviated `{Element*}`, represents a possibly-empty stream.
- The type `Iterable<Element,Nothing>`, usually abbreviated `{Element+}`, represents a nonempty stream.

Every iterator for a nonempty stream must produce at least one element.

A value list in braces produces a new instance of `Iterable`:

    {String+} words = { "hello", "world" };

An instance of `Iterable` may be iterated using a `for` loop:

    for (c in "hello world") { ... }

Comprehensions provide a convenient syntax for transforming streams:

    {Integer+} lengths = { for (w in words) w.size };

The `*.` operator may be used to evaluate an attribute or invoke a method of the elements of the stream, producing a new stream:

    {Integer+} lengths = words*.size;

`Iterable` and its subtypes define various operations that return other iterable objects. Such operations come in two flavors:

- Lazy operations return a view of the receiving iterable object. If the underlying iterable object is mutable, then changes to the underlying object will be reflected in the resulting view. Lazy operations are usually efficient, avoiding memory allocation or iteration of the receiving iterable object.
- Eager operations return an immutable object. If the receiving iterable object is mutable, changes to this object will not be reflected in the resulting immutable object. Eager operations are often expensive, involving memory allocation and iteration of the receiving iterable object.

Lazy operations are generally preferred, because they can be efficiently chained. For example:

    string.filter((c) => c.letter||c.digit)
          .map(Character.uppercased)

is much less expensive than:

    string.select((c) => c.letter||c.digit)
          .collect(Character.uppercased)

Furthermore, it is always easy to produce a new immutable iterable object given the view produced by a lazy operation. For example:

    [ *string.filter((c) => c.letter||c.digit)
             .map(Character.uppercased) ]

However, there are certain scenarios where an eager operation is more useful, more convenient, or no more expensive than a lazy operation, including:

- sorting operations, for example `sort()`, which are eager by nature,
- operations which result in a subset or subrange of the receiving stream, where structural sharing would or could result in unnecessary memory retention.

Certain operations come in both lazy and eager flavors, for example:

- `map()` vs `collect()`,
- `filter()` vs `select()`,
- `List.sublist()` vs `List.measure()`.

Lazy operations normally return an instance of `Iterable`, or even a `List`, `Map`, or `Set`. Eager operations usually return a sequence. The method `sequence()` materializes the current elements of a stream into a sequence.

There is no meaningful generic definition of equality for streams. For some streams—for example, `List`s—order is significant; for others—for example, `Set`s—order is not significant. Therefore, unlike `Collection` and its subtypes, `Iterable` does not define nor require any form of value equality, and some streams simply do not support value equality. It follows that the `==` operator should not be used to compare generic streams, unless the streams are known to share some additional structure.

To compare the elements of two streams, taking order into account, use the function `corresponding()`.

    {Float*} xs = ... ;
    {Float*} ys = ... ;
    Boolean same = corresponding(xs, ys);

By: Gavin
See also `Collection`, `corresponding()`, `Iterator`

no type hierarchy

- `Iterable`
  - `Category`

- `Iterable`
  - `Collection`
    - `List`
      - `SearchableList`
        - `Array`
        - `String`
        - `StringBuilder`
      - `Sequential`
        - `Empty`
          - `empty`
        - `Sequence`
          - `ArraySequence`
          - `Range`
          - `Singleton`
          - `Tuple`
    - `Map`
      - `emptyMap`
    - `Set`
      - `emptySet`
  - `Ranged`
    - `Array`
    - `Empty`
      - `empty`
    - `List`
      - `SearchableList`
        - `Array`
        - `String`
        - `StringBuilder`
      - `Sequential`
        - `Empty`
          - `empty`
        - `Sequence`
          - `ArraySequence`
          - `Range`
          - `Singleton`
          - `Tuple`
    - `Sequential`
      - `Empty`
        - `empty`
      - `Sequence`
        - `ArraySequence`
        - `Range`
        - `Singleton`
        - `Tuple`
    - `String`
    - `StringBuilder`
  - `References`
  - `Sequence`
    - `ArraySequence`
    - `Range`
    - `Singleton`
    - `Tuple`

Attributes
`coalesced` | Source Code `shared default {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 }`. See also `defaultNullElements()`
`cycled` | Source Code `shared default Iterable<Element,Absent> cycled` An infinite stream that produces the elements of this stream, repeatedly. For example, the expression
    {6, 9}.cycled.take(5)
evaluates to the stream `{ 6, 9, 6, 9, 6 }`. If this stream is empty, the resulting stream also empty. See also `repeat()`
`distinct` | Source Code `shared default Iterable<Element,Absent> distinct` A stream that produces every element produced by this stream exactly once. Duplicate elements of this stream are eliminated. Two elements are considered distinct unless they are both null, or unless they are both non-null and equal. For example:
    String("hello world".distinct)
is the string `"helo wrd"`. This is a lazy operation and the resulting stream reflects changes to this stream. See also `set()` Since 1.2.0
`empty` | Source Code `shared default Boolean empty` Determines if the stream is empty, that is to say, if the iterator returns no elements.
`exceptLast` | Source Code `shared default {Element*} exceptLast` A stream containing all but the last element of this stream. For a stream with an unstable iteration order, a different stream might be produced each time `exceptLast` is evaluated. Since 1.1.0
`first` | Source Code `shared default Absent|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.
`indexed` | Source Code `shared default Iterable<Integer->Element,Absent> 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" }`. See also `locations()`
`last` | Source Code `shared default Absent|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.
`paired` | Source Code `shared default {Element[2]*} paired` A stream containing whose elements are pairs (2-tuples) comprising an element of this stream paired with the next element in the stream. The resulting stream has one fewer elements than this stream. If this stream has exactly one element, the resulting stream is empty. For example, the expression
    (1..5).paired
results in the stream `{ [1, 2], [2, 3], [3, 4], [4, 5] }`. This expression determines if a stream is monotonically increasing:
    every { for ([x, y] in nums.paired) x < y }
For any stable `stream`, this operation is equivalent to `zipPairs(stream,stream.rest)`. If this is a stream with an unstable iteration order, the resulting stream produces a different set of pairs each time it is iterated, thus violating the general contract for an immutable finite stream. This is a lazy operation and the resulting stream reflects changes to this stream. Since 1.1.0
`rest` | Source Code `shared default {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`. See also `first`
`size` | Source Code `shared default Integer size` The number of elements returned by the `iterator()` of this stream, if the iterator terminates. In the case of an infinite stream, this operation never terminates.
`string` | Source Code `shared actual default String string` A string of form `"{ x, y, z }"` where `x`, `y`, and `z` are the `string` representations of the elements of this collection, as produced by the iterator of the stream, or the string `"{}"` if this stream is empty. If the stream is very long, the list of elements might be truncated, as indicated by an ellipse. Refines `Object.string`

Inherited Attributes
Attributes inherited from: `Object` `hash`, `string`

Methods
`any` | Source Code `shared default 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. Parameters: `selecting` The predicate that at least one element must satisfy. See also `every()`
`by` | Source Code `shared default Iterable<Element,Absent> 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. Parameters: `step` step size must be greater than zero Throws `AssertionError` if the given step size is nonpositive, i.e. `step<1`
`chain` | Source Code `shared default Iterable<Element|Other,Absent&OtherAbsent> 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' }`. See also `expand()`
`collect` | Source Code `shared default 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 `map()`. For any stream `it`, and mapping `f`:
    it.collect(f) == [*it.map(f)]
Parameters: `collecting` The transformation applied to the elements. See also `map()`
`contains` | Source Code `shared actual default Boolean contains(Object element)` Returns `true` if the iterator for this stream produces the given element, or `false` otherwise. In the case of an infinite stream, this operation might never terminate; furthermore, this default implementation iterates all the elements until found (or not), which might be very expensive. Refines `Category.contains`
`count` | Source Code `shared default 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. Parameters: `selecting` The predicate satisfied by the elements to be counted.
`defaultNullElements` | Source Code `shared default Iterable<Element&Object|Default,Absent> 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 }`. Parameters: `defaultValue` A default value that replaces `null` elements. See also `coalesced`
`each` | Source Code `shared default 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. Parameters: `step` The function to be called for each element in the stream. Since 1.2.0
`every` | Source Code `shared default 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. Parameters: `selecting` The predicate that all elements must satisfy. See also `any()`
`filter` | Source Code `shared default {Element*} filter(Boolean selecting(Element 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 }`. Parameters: `selecting` The predicate the elements must satisfy. The elements which satisfy the predicate are included in the resulting stream. See also `select()`
`find` | Source Code `shared default 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`. Parameters: `selecting` The predicate the element must satisfy. See also `findLast()`, `locate()`
`findLast` | Source Code `shared default 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`. Parameters: `selecting` The predicate the element must satisfy. See also `find()`, `locateLast()`
`flatMap` | Source Code `shared default Iterable<Result,Absent|OtherAbsent> flatMap<Result, OtherAbsent>(Iterable<Result,OtherAbsent> collecting(Element 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" }
Parameters: `collecting` The mapping function to apply to the elements of this stream, that produces a new stream of `Result`s. See also `expand()` Since 1.1.0
`fold` | Source Code `shared default Result fold<Result>(Result initial)(Result accumulating(Result partial, Element 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`. Parameters: `accumulating` The accumulating function that accepts an intermediate result, and the next element. See also `reduce()`, `scan()`
`follow` | Source Code `shared default {Element|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 }
See also `chain()` Since 1.1.0
`frequencies` | Source Code `shared Map<Element&Object,Integer> frequencies()` Produce a `Map` mapping elements to frequencies where each entry maps a distinct non-null element of this stream to the number of times the element was produced by the stream. Elements are considered distinct if they are not equal. Null elements of this stream are simply discarded. For example:
    "helloworld".frequencies()
produces the map `{ r->1, d->1, e->1, w->1, h->1, l->3, o->2 }`. This is an eager operation, and the resulting map does not reflect changes to this stream. Since 1.2.0
`getFromFirst` | Source Code `shared default 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`. Since 1.1.0
`group` | Source Code `shared Map<Group,[Element+]> group<Group>(Group? grouping(Element element)) given Group satisfies Object` Classifies the elements of this stream into a new immutable `Map` where each key is a value produced by the given grouping function and each corresponding item is sequence of all elements that produced the key when passed as arguments to the grouping function. Within each group, the sequence elements occur in the same order they occurred in this stream. For example:
    (0..10).group((i) => i.even then "even" else "odd")
produces the map `{ even->[0, 2, 4, 6, 8, 10], odd->[1, 3, 5, 7, 9] }`. This is an eager operation, and the resulting map does not reflect changes to this stream. Parameters: `grouping` The grouping function that assigns a key to the given `element`. Multiple elements may be assigned to the same key, indicating that they belong to the same `Group` in the resulting map. An element may be assigned no key by returning `null`, in which case it will be discarded. See also `summarize()` Since 1.2.0
`indexes` | Source Code `shared default Range<Integer>|[] indexes()` A `Range` containing all indexes of this stream, or `[]` if this list is empty. The resulting range is equal to `0:size`. Since 1.2.0
`interpose` | Source Code `shared default Iterable<Element|Other,Absent> interpose<Other>(Other element, Integer step = 1)` A stream that contains the given `element` interposed between blocks of `step` elements of this stream. The resulting stream starts with the `first` element of this stream and ends with the `last` element of this stream. Elements of this stream occur in the resulting stream in the same order they occur in this stream. For example, the expression
    String("hello".interpose(' '))
evaluates to the string `"h e l l o"`. This is a lazy operation and the resulting stream reflects changes to this stream. Parameters: `element` The value to interpose between blocks of elements of this stream. `step = 1` The step size that determines how often the given `element` occurs in the resulting stream. The `element` occurs after each block of size `step` of elements of this stream. If `step==1`, the `element` occurs at every second position. The step size must be strictly positive. step must be strictly positive Throws `AssertionError` if `step<1` See also `interleave()` Since 1.1.0
`iterator` | Source Code `shared formal 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.
`locate` | Source Code `shared default <Integer->Element&Object>? locate(Boolean selecting(Element&Object element))` The first element of this stream which is not null and satisfies the given predicate function, if any, together with its position in the stream, or `null` if there is no such element. For an infinite stream, this method might not terminate. For example, the expression
    (-10..10).locate(Integer.positive)
evaluates to `11->1`. Parameters: `selecting` The predicate the element must satisfy. See also `locateLast()`, `locations()`, `find()`, `List.firstIndexWhere()` Since 1.2.0
`locateLast` | Source Code `shared default <Integer->Element&Object>? locateLast(Boolean selecting(Element&Object element))` The last element of this stream which is not null and satisfies the given predicate function, if any, together with its position in the stream, or `null` if there is no such element. For an infinite stream, this method might not terminate. For example, the expression
    (-10..10).locateLast(3.divides)
evaluates to `19->9`. Parameters: `selecting` The predicate the element must satisfy. See also `locate()`, `locations()`, `findLast()`, `List.lastIndexWhere()` Since 1.2.0
`locations` | Source Code `shared default {<Integer->Element&Object>*} locations(Boolean selecting(Element&Object element))` A stream producing all elements of this stream which are not null and which satisfy the given predicate function, together with their positions in the stream. For example, the expression
    (-5..5).locations(3.divides)
evaluates to the stream `{ 2->-3, 5->0, 8->3 }`. Note that this method is more efficient than the alternative of applying `filter()` to an `indexed` stream. Parameters: `selecting` The predicate the element must satisfy. See also `locate()`, `locateLast()`, `List.indexesWhere()` Since 1.2.0
`longerThan` | Source Code `shared 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. See also `size`
`map` | Source Code `shared default Iterable<Result,Absent> map<Result>(Result collecting(Element 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 }`. Parameters: `collecting` The mapping to apply to the elements. See also `collect()`
`max` | Source Code `shared default Element|Absent max(Comparison comparing(Element x, Element y))` Return the largest value in the stream, as measured by the given comparator function imposing a partial order upon the elements of the stream, or `null` if this stream is empty. For example, the expression
    {-10.0, -1.0, 5.0}.max(byIncreasing(Float.magnitude))
evaluates to `-10`. For any nonempty stream `it`, and comparator function `c`, `it.max(c)` evaluates to the first element of `it` such that for every element `e` of `it`, `c(e, it.max(c)) != larger`. Note that the toplevel functions `max()` and `min()` may be used to find the largest and smallest values in a stream of `Comparable` values, according to the natural order of its elements. Parameters: `comparing` The function comparing pairs of elements. See also `max()`, `min()`, `byIncreasing()`, `byDecreasing()`, `comparing` Since 1.1.0
`narrow` | Source Code `shared default {Element&Type*} narrow<Type>()` Produces a stream containing the elements of this stream that are instances of the given Type. For example, the expression
    { 1, 2, null, 3 }.narrow<Object>()
results in the stream `{ 1, 2, 3 }` of type `{Integer*}`. If the type argument `Type` is not explicitly specified, `Nothing` is inferred, and the resulting stream is empty. Since 1.2.0
`partition` | Source Code `shared default Iterable<[Element+],Absent> partition(Integer length)` Produces a stream of sequences of the given `length`, containing elements of this stream. Each sequence in the stream contains the next `length` elements of this sequence that have not yet been assigned to a previous sequence, in the same order that they occur in this stream. The very last sequence in the stream may be shorter than the given `length`. For example, the expression
    "hello".partition(2)
results in the stream `{ ['h','e'], ['l','l'], ['o'] }.` For any `stream` and for any strictly positive integer `length`:
    expand { stream.partition(length) } == stream
If this is a stream with an unstable iteration order, the resulting stream produces a different set of pairs each time it is iterated, thus violating the general contract for an immutable finite stream. This is a lazy operation and the resulting stream reflects changes to this stream. Parameters: `length` The length of the sequences in the resulting stream, which must be strictly positive. length must be strictly positive Throws `AssertionError` if `length<=0` Since 1.1.0
`product` | Source Code `shared default Iterable<[Element, Other],Absent|OtherAbsent> product<Other, OtherAbsent>(Iterable<Other,OtherAbsent> other) given OtherAbsent satisfies Null` A stream of pairs of elements of this stream and the the given stream, where for each element `x` of this stream, and element `y` of the given stream, the pair `[x,y]` belongs to the resulting stream. The pairs are sorted first by the position of `x` in this stream, and then by the position of `y` in the given stream. For example, this expression
    (1..3).product("ab")
evaluates to the stream `{ [1,'a'], [1,'b'], [2,'a'], [2,'b'], [3,'a'], [3,'b'] }`. Since 1.1.0
`reduce` | Source Code `shared default Result|Element|Absent reduce<Result>(Result accumulating(Result|Element partial, Element element))` Beginning with the `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` The accumulating function that accepts an intermediate result, and the next element. See also `fold()` Since 1.1.0
`repeat` | Source Code `shared default {Element*} repeat(Integer times)` Produces a stream formed by repeating the elements of this stream the given number of times, or an empty stream if `times<=0`. For example, the expression
    { 1, 2 }.repeat(3)
evaluates to the stream `{ 1, 2, 1, 2, 1, 2 }`. If this is a stream with an unstable iteration order, the elements of the resulting stream do not occur in repeating order. This is a lazy operation and the resulting stream reflects changes to this stream. See also `cycled`
`scan` | Source Code `shared default {Result+} scan<Result>(Result initial)(Result accumulating(Result partial, Element element))` The stream of intermediate results obtained by beginning with a given initial value and iteratively applying the given combining function to each element of this stream in turn. For an empty stream, `scan()` returns a stream containing just the given initial value `z`:
    {}.scan(z)(f) == { z }
For a given nonempty stream `it`, initial value `z`, and combining function `f`, the result of `scan()` is obtained according to the following recursive definition:
    it.scan(z)(f).last == f(it.exceptLast.scan(z)(f).last, it.last)
    it.scan(z)(f).exceptLast == it.exceptLast.scan(z)(f)
The following identities explain the relationship between `scan` and `fold()`:
    it.scan(z)(f).getFromFirst(n) == it.take(n).fold(z)(f)
    it.scan(z)(f).last == it.fold(z)(f)
    it.scan(z)(f).first == {}.fold(z)(f) == z
For example, the expression
    (1..4).scan(0)(plus)
results in the stream `{ 0, 1, 3, 6, 10 }`. This is a lazy operation and the resulting stream reflects changes to this stream. Parameters: `accumulating` The accumulating function that accepts the running total and the next element. See also `fold()` Since 1.1.0
`select` | Source Code `shared default 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 `filter()`. For any stream `it`, and predicate `p`:
    it.select(p) == [*it.filter(p)]
Parameters: `selecting` The predicate the elements must satisfy. See also `filter()`
`sequence` | Source Code `shared default Element[] sequence()` A sequence containing all the elements of this stream, in the same order they occur in this stream. This operation eagerly evaluates and collects every element of the stream. Since 1.1.0
`shorterThan` | Source Code `shared 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. See also `size`
`skip` | Source Code `shared default {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. See also `List.sublistFrom()`, `skipWhile()`, `take()` Since 1.1.0
`skipWhile` | Source Code `shared default {Element*} skipWhile(Boolean skipping(Element element))` Produces a stream containing the elements of this stream, after skipping the leading elements until the given predicate function returns `false`. Parameters: `skipping` The function that returns `false` when the resulting stream should stop skipping elements from the stream. See also `skip()`, `takeWhile()` Since 1.1.0
`sort` | Source Code `shared default 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` The function comparing pairs of elements. See also `increasing()`, `decreasing()`, `byIncreasing()`, `byDecreasing()`, `comparing`
`spread` | Source Code `shared default Iterable<Result,Absent>(*Args) spread<Result, Args>(Result(*Args) method(Element 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 }
Since 1.1.0
`summarize` | Source Code `shared Map<Group,Result> summarize<Group, Result>(Group? grouping(Element element), Result accumulating(Result? partial, Element element)) given Group satisfies Object` Efficiently `group()` and `fold()` the elements of this stream in a single step. For example, the expression:
    (1..10)
       .summarize((i) => i%3,
           (Integer[2]? pair, i)
               => if (exists [sum, product] = pair)
                  then [sum+i, product*i] else [i,i])
produces the map `{ 0->[18, 162], 1->[22, 280], 2->[15, 80] }`, being equivalent to, but much more efficient than, the following expression written using `group()`, `mapItems()` and `fold()`:
    (1..10)
        .group((i) => i%3)
        .mapItems((_, item)
           => item.fold([0,1])
               (([sum, product], i)
                   => [sum+i, product*i]))
This is an eager operation, and the resulting map does not reflect changes to this stream. Parameters: `grouping` The grouping function that assigns a key to the given `element`. Multiple elements may be assigned to the same key, indicating that they should be aggregated by calling `accumulating()`. An element may be assigned no key by returning `null`, in which case it will be discarded. `accumulating` The accumulating function that accepts an intermediate result for a key, and the `next element` with that key. See also `group()`, `fold()` Since 1.2.0
`tabulate` | Source Code `shared Map<Element&Object,Result> tabulate<Result>(Result collecting(Element key))` Produces a `Map` mapping elements to items where each entry maps a distinct non-null element of this stream to the item produced by the given function. Elements are considered distinct if they are not equal. Null elements of this stream are simply discarded. For example:
    (1..5).tabulate(2.divides)
produces the map `{ 1->false, 2->true, 3->false, 4->true, 5->false }`. This is an eager operation, and the resulting map does not reflect changes to this stream. Parameters: `collecting` A function that produces an item for the given `key`, an element of this stream. Since 1.2.0
`take` | Source Code `shared default {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. See also `List.sublistTo()`, `List.initial()`, `takeWhile()`, `skip()` Since 1.1.0
`takeWhile` | Source Code `shared default {Element*} takeWhile(Boolean taking(Element element))` Produces a stream containing the leading elements of this stream until the given predicate function returns `false`. Parameters: `taking` The function that returns `false` when the resulting stream should stop taking elements from this stream. See also `take()`, `skipWhile()` Since 1.1.0

Inherited Methods
Methods inherited from: `Object` `equals()`
Methods inherited from: `Category<Element>` `contains()`, `containsAny()`, `containsEvery()`