8181175 Stream.concat behaves like terminal operation

[Stuart Marks]

On 11/20/17 10:34 AM, Paul Sandoz wrote:
> 
> 
>> On 17 Nov 2017, at 17:18, Stuart Marks <stuart.marks at oracle.com> wrote:
>> The normative text about binding to the source and subsequent modifications to the source possibly not being reflected in the stream makes sense.
>>
>> I'm having trouble understanding the API note though. What does "optimal" mean? What about concatenating multiple streams would not be optimal?
> 
> I updated to:
> 
> * @apiNote
> * To preserve optimization opportunities this method binds each stream to
> * its source and accepts only two streams as parameters.  For example, the
> * exact size of the concatenated stream source can be computed if the exact
> * size of each input stream source is known.
> * To concatenate more streams without binding, or nested calls to this
> * method, try creating a stream of streams and flat-mapping with the
> * identity function, for example:
> * <pre>{@code
> *     Stream<T> concat = Stream.of(s1, s2, s3, s4).flatMap(s -> s);
> * }</pre>
> 
> We could support three or more streams while preserving some characteristics, that complicates the concatenating spliterator a little bit. Each stream would still need to be bound.
> 
> Patch updated to include the primitive streams:
> 
>    http://cr.openjdk.java.net/~psandoz/jdk10/JDK-8181175-concat-eager-binding/webrev/

OK, this makes a lot more sense. Just a small wording change:

1361      * To concatenate more streams without binding, or nested calls to this
1362      * method, try creating a stream of streams and flat-mapping with the
1363      * identity function, for example:

I think this would read more clearly if it were changed to "... without binding, 
or without nested calls to this method, ...." I think this applies in all four 
occurrences.

Thanks,

s'marks