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 }.

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.

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.

Determines if the stream is empty, that is to say, if the iterator returns no elements.

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.

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.

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" }.

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.

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.

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.

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.

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.

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.

Produces a stream containing every stepth 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.

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' }.

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)]

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.

Produces the number of elements in this stream that satisfy the given predicate function. For an infinite stream, this method never terminates.

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 }.

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.

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.

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 }.

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.

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.

Given a mapping function that accepts an Element and returns a stream of Results, 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" }

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.

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 }

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.

The indexth 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.

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.

A Range containing all indexes of this stream, or [] if this list is empty. The resulting range is equal to 0:size.

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.

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.

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.

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.

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.

Determines if this stream has more elements than the given length. This is an efficient operation for streams with many elements.

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 }.

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.

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.

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.

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'] }.

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.

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.

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.

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)]

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.

If this stream is known to be nonempty, that is, if it is an instance of {Anything+}, then this operation has a nonempty return type, that is, a subtype of [Anything+]. For example:

[String+] bits = "hello world".split().sequence();

Determines if this stream has fewer elements than the given length. This is an efficient operation for streams with many elements.

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.

Produces a stream containing the elements of this stream, after skipping the leading elements until the given predicate function returns false.

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.

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 }

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.

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.

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.

Produces a stream containing the leading elements of this stream until the given predicate function returns false.