Package: java.util.stream

## [Java] Interface Stream

-     public interface Stream

  GDK enhancements for Stream.

  displayName:
    Stream
  receiverFqcn:
    java.util.stream.Stream

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T>` | `public Stream<T>` | `from(IntRange range)` Returns a (possibly empty) stream.
    `<T>` | `public Stream<T>` | `from(EmptyRange range)` Returns an empty stream.
    `<T>` | `public T` | `getAt(int index)` Returns element at `index` or `null`.
    `<T>` | `public List<T>` | `getAt(IntRange range)` Returns element(s) in `range` or an empty list.
    `<T>` | `public List<T>` | `getAt(EmptyRange range)` Returns an empty list.
    `<T>` | `public Stream<T>` | `plus(Collection<? extends T> rhs)` Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the Collection object.
    `<T>` | `public Stream<T>` | `plus(Iterable<? extends T> rhs)` Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the Iterable object.
    `<T>` | `public Stream<T>` | `plus(Stream<? extends T> rhs)` Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the second stream.
    `` | `public long` | `size()` An alias for `count`.
    `<T>` | `public T[]` | `toArray(Class<T> type)` Returns an array containing the elements of the stream.
    `<T>` | `public Set<T>` | `toImmutableSet()` Accumulates the elements of stream into an immutable Set.
    `<T>` | `public List<T>` | `toMutableList()` Accumulates the elements of stream into a new mutable List.
    `<T>` | `public Set<T>` | `toMutableSet()` Accumulates the elements of stream into a new mutable Set.
    `<T>` | `public Set<T>` | `toSet()` Accumulates the elements of stream into a new Set.

- - ### Method Detail

    - #### <T> public Stream<T> from(IntRange range)

      Returns a (possibly empty) stream.

      This is a short-circuiting intermediate operation.

           import java.util.stream.Stream
           import static groovy.test.GroovyAssert.shouldFail

           Stream<String> stream = ['foo','bar','baz'].stream()
           shouldFail(IllegalArgumentException) { stream.from(-1..0) }

           stream = ['foo','bar','baz'].stream()
           shouldFail(IllegalArgumentException) { stream.from(0..-1) }

           stream = ['foo','bar','baz'].stream()
           assert stream.from(0..<1).toList() == ['foo']

           stream = ['foo','bar','baz'].stream()
           assert stream.from(1..<2).toList() == ['bar']

           stream = ['foo','bar','baz'].stream()
           assert stream.from(2..<3).toList() == ['baz']

           stream = ['foo','bar','baz'].stream()
           assert stream.from(3..<4).toList() == []

           stream = ['foo','bar','baz'].stream()
           assert stream.from(0<..2).toList() == ['bar','baz']

           stream = ['foo','bar','baz'].stream()
           assert stream.from(0<..<2).toList() == ['bar']

           stream = ['foo','bar','baz'].stream()
           assert stream.from(0..99).toList() == ['foo','bar','baz']

      throws:
        IllegalArgumentException for negative index or reverse range
      Since:
        5.0.0

    - #### <T> public Stream<T> from(EmptyRange range)

      Returns an empty stream.

           import java.util.stream.Stream
           Stream<String> stream = ['foo','bar','baz'].stream()
           assert !stream.from(1..<1).findAny().isPresent()

      Since:
        5.0.0

    - #### <T> public T getAt(int index)

      Returns element at `index` or `null`.

      This is a short-circuiting terminal operation.

           import java.util.stream.Stream
           import static groovy.test.GroovyAssert.shouldFail

           Stream stream = ['foo','bar','baz'].stream()
           shouldFail(IllegalArgumentException) { stream[-1] }

           stream = ['foo','bar','baz'].stream()
           assert stream[0] == 'foo'

           stream = ['foo','bar','baz'].stream()
           assert stream[1] == 'bar'

           stream = ['foo','bar','baz'].stream()
           assert stream[2] == 'baz'

           stream = ['foo','bar','baz'].stream()
           assert stream[3] === null

      throws:
        IllegalArgumentException if `index` is negative
      Since:
        5.0.0

    - #### <T> public List<T> getAt(IntRange range)

      Returns element(s) in `range` or an empty list.

      This is a short-circuiting terminal operation.

           import java.util.stream.Stream
           import static groovy.test.GroovyAssert.shouldFail

           Stream<String> stream = ['foo','bar','baz'].stream()
           shouldFail(IllegalArgumentException) { stream[-1..0] }

           stream = ['foo','bar','baz'].stream()
           shouldFail(IllegalArgumentException) { stream[0..-1] }

           stream = ['foo','bar','baz'].stream()
           assert stream[0..<1] == ['foo']

           stream = ['foo','bar','baz'].stream()
           assert stream[1..<2] == ['bar']

           stream = ['foo','bar','baz'].stream()
           assert stream[2..<3] == ['baz']

           stream = ['foo','bar','baz'].stream()
           assert stream[3..<4] == []

           stream = ['foo','bar','baz'].stream()
           assert stream[0<..2] == ['bar','baz']

           stream = ['foo','bar','baz'].stream()
           assert stream[0..99] == ['foo','bar','baz']

      throws:
        IllegalArgumentException for negative index or reverse range
      Since:
        5.0.0

    - #### <T> public List<T> getAt(EmptyRange range)

      Returns an empty list.

           import java.util.stream.Stream
           Stream<String> stream = ['foo','bar','baz'].stream()
           assert stream[1..<1].isEmpty()

      Since:
        5.0.0

    - #### <T> public Stream<T> plus(Collection<? extends T> rhs)

      Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the Collection object.

           import java.util.stream.Stream
           assert (Stream.of(1) + [2]).toList() == [1,2]
           assert (Stream.of(1) + []).toList() == [1]

      Since:
        4.0.0

    - #### <T> public Stream<T> plus(Iterable<? extends T> rhs)

      Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the Iterable object.

           import java.util.stream.Stream
           assert (Stream.of(1) + [2]).toList() == [1,2]
           assert (Stream.of(1) + []).toList() == [1]

      Since:
        4.0.0

    - #### <T> public Stream<T> plus(Stream<? extends T> rhs)

      Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the second stream.

           import java.util.stream.Stream
           assert (Stream.of(1) + Stream.<Integer>empty()).toList() == [1]
           assert (Stream.of(1) + Stream.of(2)).toList() == [1,2]
           assert (Stream.of(1) + [2].stream()).toList() == [1,2]

      Since:
        4.0.0

    - #### public long size()

      An alias for `count`. Returns the count of elements for this stream. This is a terminal operator and, depending on the underlying stream, may invoke the stream pipeline, leaving it empty after this call. Care should be taken with stream pipelines that have side effects. This method should not be called on an infinite stream.

           assert [1, 2, 3].stream().size() == 3

      Returns:
        the count of elements in this stream
      See Also:
        Stream.count
      Since:
        5.0.0

    - #### <T> public T[] toArray(Class<T> type)

      Returns an array containing the elements of the stream.

           import static groovy.test.GroovyAssert.shouldFail

           assert Arrays.equals([].stream().toArray(Object), new Object[0])
           assert Arrays.equals([].stream().toArray(String), new String[0])
           assert Arrays.equals([].stream().toArray(String[]), new String[0][])
           assert Arrays.equals(['x'].stream().toArray(Object), ['x'].toArray())
           assert Arrays.equals(['x'].stream().toArray(String), ['x'] as String[])
           assert Arrays.deepEquals([['x'] as String[]].stream().toArray(String[]), [['x'] as String[]] as String[][])
           assert Arrays.equals(['x'].stream().toArray(CharSequence), ['x'] as CharSequence[])

           shouldFail(ArrayStoreException) {
               ['x'].stream().toArray(Thread)
           }

           shouldFail(IllegalArgumentException) {
               ['x'].stream().toArray((Class) null)
           }

           // Stream#toArray(IntFunction) should still be used for closure literal:
           assert Arrays.equals(['x'].stream().toArray { n -> new String[n] }, ['x'] as String[])

           // Stream#toArray(IntFunction) should still be used for method reference:
           assert Arrays.equals(['x'].stream().toArray(String[]::new), ['x'] as String[])

      Parameters:
        `type` - the array element type
      Since:
        3.0.4

    - #### <T> public Set<T> toImmutableSet()

      Accumulates the elements of stream into an immutable Set.

      No native `Stream.toSet()` exists, so this provides the immutable counterpart to Stream.toSet. Null elements are preserved (unlike Collectors.toUnmodifiableSet which rejects nulls); the returned set is unmodifiable and mutation attempts throw UnsupportedOperationException. Returns the canonical empty set (Collections.emptySet) when the stream is empty.

           import java.util.stream.Stream
           import static groovy.test.GroovyAssert.shouldFail
           import static org.codehaus.groovy.runtime.StreamGroovyMethods.toImmutableSet
           def set = toImmutableSet(Stream.of('a', null, 'b', 'a'))
           assert set == ['a', null, 'b'] as Set
           shouldFail(UnsupportedOperationException) { set << 'c' }
           assert toImmutableSet(Stream.<String>empty()) === Collections.emptySet()

      Type Parameters:
        `T` - the type of element
      Returns:
        an immutable `java.util.Set` instance
      Since:
        6.0.0

    - #### <T> public List<T> toMutableList()

      Accumulates the elements of stream into a new mutable List.

      Explicit alternative to the native Stream.toList (which returns an unmodifiable list since JDK 16). Use this when you need to add to, remove from, or sort the returned list. The returned list is a concrete ArrayList — the cached collector pins the supplier so this is contract, not happenstance.

           import java.util.stream.Stream
           import org.codehaus.groovy.runtime.StreamGroovyMethods
           def list = StreamGroovyMethods.toMutableList(Stream.of('a', 'b'))
           assert list == ['a', 'b']
           list << 'c'   // mutable — no UnsupportedOperationException
           assert list == ['a', 'b', 'c']

      Type Parameters:
        `T` - the type of element
      Returns:
        a new mutable `java.util.List` instance
      Since:
        6.0.0

    - #### <T> public Set<T> toMutableSet()

      Accumulates the elements of stream into a new mutable Set.

      Explicit-mutability alias for Stream.toSet. Provided defensively so user intent stays unambiguous if a future JDK release adds a native `Stream.toSet()` (which would shadow the GDK extension the way native Stream.toList did in JDK 16).

      Type Parameters:
        `T` - the type of element
      Returns:
        a new mutable `java.util.Set` instance
      Since:
        6.0.0

    - #### <T> public Set<T> toSet()

      Accumulates the elements of stream into a new Set.

      Type Parameters:
        `T` - the type of element
      Returns:
        a new `java.util.Set` instance
      Since:
        2.5.0