Dividing Streams.java

[Sam Pullara]

I think it is a good idea to move all of them to their interfaces. Much easier to find.

Sam

On Apr 18, 2013, at 7:18 PM, Brian Goetz <brian.goetz at oracle.com> wrote:

> Now that we've cleared away the spliterator methods from Streams, all, or nearly all, of the remaining methods in Streams are candidates for moving to the respective interfaces.  And in many ways get nicer when they do.
> 
> We've got:
> 
>  builder()
>  emptyStream()
>  singletonStream()
>  iterate()
>  generate()
> 
> for all the types (so emptyStream(), emptyIntStream(), etc), plus ranges for the numeric types.  Plus
> 
>  concat()
>  zip()
> 
> for ref streams.
> 
> All of these are good candidate for statics in their respective interfaces:
> 
>  Stream.builder()
>  Stream.emptyStream();
>  IntStream.generate(f);
>  IntStream.range(f);
> 
> They read well, most are "important" enough to live with the main interface, and the names get less redundant since we don't have to say "intRange" but just "range".
> 
> All of them?  Most of them?  None of them?
> 
> On 4/11/2013 1:51 PM, Brian Goetz wrote:
>> Joe quite correctly pointed out in the survey that Streams.java is a mix
>> of two things for two audiences:
>> 
>>  - Utility methods for users to generate streams, like intRange()
>>  - Low level methods for library writers to generate streams from
>> things like iterators or spliterators.
>> 
>> Merging them in one file is confusing, because users come away with the
>> idea that writing spliterators is something they're supposed to do,
>> whereas in reality, if we've done our jobs, they should never even be
>> aware that spliterators exist.  So I think we should separate them into
>> a "high level" and "low level" bag of tricks.
>> 
>> Since today, Paul has added some new ones:
>>  - singletonStream(v) (four flavors)
>>  - builder() (four flavors)
>> 
>> So, we have to identify appropriate homes for the two groupings, and
>> separate them.  Here's a first cut at separating them:
>> 
>> High level:
>>   xxxRange
>>   xxxBuilder
>>   emptyXxxStream
>>   singletonXxxStream
>>   concat
>>   zip
>> 
>> Low level:
>>   all spliterator-related stream building methods
>> 
>> Not sure where (or even if):
>>   iterate (given T0 and f, infinite stream of T0, f(T0), f(f(T0)), ...)
>>   generate (infinite stream of independent applications of a generator,
>> good for infinite constant and random streams, though not much else,
>> used by impl of Random.{ints,longs,gaussians}).
>> 
>> Others that we've talked about adding:
>>   ints(), longs()  // to enable things like ints().filter(...).limit(n)
>>   indexedGenerate(i -> T)
>> 
>> 
>> 
>> I think the high-level stuff should stay in Streams.  So we need a name
>> for the low-level stuff.  (Which also then becomes the right home for
>> "how do I turn my data sturcture into a stream" doc.)
>> 
>> What should we call that?