Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8256441

Add Stream.toList() method



    • CSR
    • Resolution: Approved
    • P3
    • 16
    • core-libs
    • None
    • source, binary
    • minimal
    • It's possible that an alternative streams library has provided its own toList() method, which would cause a conflict. There are very few alternative streams libraries. StreamEx and ProtonPack in particular don't seem to have a conflict.
    • Java API
    • SE



      There needs to be a convenient and optimized way to create a List from the contents of a Stream.


      Given a stream, it's possible to collect the elements into a List using a Collector:


      This works, but it runs through the Collector interface, which does accumulation and merging. There is no way for a stream (particularly a parallel stream) of known size to deposit results directly into a List without extra allocation and copying.


      Add a new method toList() directly to the Stream interface. This allows the streams machinery to deposit the results directly into a destination array which can then be wrapped safely in an unmodifiable List. Not only does this avoid copying and allocation, it's quite convenient.

      Although it's not specified explicitly, the streams implementation tolerates null elements in most cases. The default and optimized implementations of toList() tolerate nulls, but this is also not specified explicitly. A general statement about null handling in streams may be the subject of a future specification revision.


      Add the following method to the java.util.stream.Stream interface:

       * Accumulates the elements of this stream into a {@code List}. The elements in
       * the list will be in this stream's encounter order, if one exists. The returned List
       * is unmodifiable; calls to any mutator method will always cause
       * {@code UnsupportedOperationException} to be thrown. There are no
       * guarantees on the implementation type or serializability of the returned List.
       * <p>The returned instance may be <a href="../lang/doc-files/ValueBased.html">value-based</a>.
       * Callers should make no assumptions about the identity of the returned instances.
       * Identity-sensitive operations on these instances (reference equality ({@code ==}),
       * identity hash code, and synchronization) are unreliable and should be avoided.
       * <p>This is a <a href="package-summary.html#StreamOps">terminal operation</a>.
       * @apiNote If more control over the returned object is required, use
       * {@link Collectors#toCollection(Supplier)}.
       * @implSpec The implementation in this interface returns a List produced as if by the following:
       * <pre>{@code
       * Collections.unmodifiableList(new ArrayList<>(Arrays.asList(this.toArray())))
       * }</pre>
       * @implNote Most instances of Stream will override this method and provide an implementation
       * that is highly optimized compared to the implementation in this interface.
       * @return a List containing the stream elements
       * @since 16
      default List<T> toList() { ... }


        Issue Links



              smarks Stuart Marks
              webbuggrp Webbug Group
              Paul Sandoz
              0 Vote for this issue
              2 Start watching this issue