Arrays.parallel vs Arrays.asStream

[Brian Goetz]

Yes, the naming of these methods is a rats nest of inconsistency.

When converting a Foo to a Bar, there are three naming conventions (all 
of which are used in the JDK):

   foo.toBar()
   foo.asBar()
   foo.bar()

Traditionally, the choice of which to use is a fuzzy one, but between 
to/as mostly centers around the conceptual weight of the transformation; 
converting a List to an array is a deep-copy operation, and hence is 
called toArray, while converting an array to a List is a simple wrapper, 
and hence is called asList.  However it is not a difficult search 
problem to find inconsistencies (or examples where something started out 
as one but morphed to the other), so these rules are simply suggestions 
and approximations.

The "naked" bar() approach works seems to work well with aggregates, 
such as:

   Reader.lines()   // returns Stream<String>
   String.chars()   // returns IntStream

The Arrays.asStream() example is a good example of being caught in 
existing inconsistencies; while we'd like that to be Arrays.stream() (to 
be consistent with our desired naming for collections), then we're 
inconsistent with Arrays.asList.

Similarly, while sequential() seems a more obvious counterpart to 
parallel() from the perspective of the stream framework, it is not 
necessarily the best counterpart from the perspective of the user. 
After all, most Java collections are already sequential; calling 
"collection.sequential()" does not make it obvious what the point of 
calling sequential() is.

Our plan with naming is to do a more global review at the point where 
we've fleshed out the functionality; these things are best done globally 
rather than locally.

On 8/31/2012 12:14 PM, Aleksey Shipilev wrote:
> Hi,
>
> I found the inconsistency in API for Arrays in it2 branch:
>    Arrays.asList(T... t)   // returns List<T>
>    Arrays.parallel(T[] t)  // returns Stream<T> (parallel)
>    Arrays.asStream(T... t) // returns Stream<T> (sequential?)
>
> Two basic options:
>   - rename parallel() to asParallel() or asParallelStream().
>   - rename asStream() to sequential()
>
> Also can be the mixture of both.
>
> -Aleksey.
>