Stream (Groovy JDK enhancements)

Package: java.util.stream

## Interface Stream

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `Stream` | `from(EmptyRange range)` Returns an empty stream.
    `Stream` | `from(IntRange range)` Returns a (possibly empty) stream.
    `List` | `getAt(EmptyRange range)` Returns an empty list.
    `List` | `getAt(IntRange range)` Returns element(s) in `range` or an empty list.
    `Object` | `getAt(int index)` Returns element at `index` or `null`.
    `Stream` | `plus(Iterable rhs)` Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the Iterable object.
    `Stream` | `plus(Collection rhs)` Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the Collection object.
    `Stream` | `plus(Stream rhs)` Returns a lazily concatenated stream whose elements are all the elements of this stream followed by all the elements of the second stream.
    `long` | `size()` An alias for `count`.
    `Object[]` | `toArray(Class type)` Returns an array containing the elements of the stream.
    `List` | `toList()` Accumulates the elements of stream into a new List.
    `Set` | `toSet()` Accumulates the elements of stream into a new Set.

  - #### Methods inherited from interface java.util.stream.BaseStream

    `toList`, `toSet`

- - ### Methods Detail

    - #### public Stream 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()

      Parameters:
      Since:
        5.0.0

    - #### public Stream 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']

      Parameters:
      Since:
        5.0.0

    - #### public List getAt(EmptyRange range)

      Returns an empty list.

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

      Parameters:
      Since:
        5.0.0

    - #### public List 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']

      Parameters:
      Since:
        5.0.0

    - #### public Object 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

      Parameters:
      Since:
        5.0.0

    - #### public Stream plus(Iterable 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]

      Parameters:
      Since:
        4.0.0

    - #### public Stream plus(Collection 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]

      Parameters:
      Since:
        4.0.0

    - #### public Stream plus(Stream 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]

      Parameters:
      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
      Since:
        5.0.0
      See Also:
        Stream#count()

    - #### public Object[] toArray(Class 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

    - #### public List toList()

      Accumulates the elements of stream into a new List.

      Returns:
        a new `java.util.List` instance
      Since:
        2.5.0

    - #### public Set toSet()

      Accumulates the elements of stream into a new Set.

      Returns:
        a new `java.util.Set` instance
      Since:
        2.5.0