Encounter order

[Brian Goetz]

>> void forEach(Block<? super T> block);
>>
>> This is only about side effects, so encounter order shouldn't enter
>> into the calculation.  Elements are fed to the block in whatever order
>> and thread they are available.
> But do we guarantee the ordering of effects for sequential
> implementation? Just curious about what would the JavaDoc say for this
> method.

Good question.  What do you think we should guarantee here?  (Its pretty 
hard to imagine an implementation that doesn't do this, but that's a 
different consideration.)  I do think it is reasonable for us to say 
that the effects are predictable in serial and not predictable in 
parallel -- this is different from the *result*.

>> Given this, my recommendation is:
>>  - Have all the problematic (sort, uniqueElements, groupBy, reduceBy)
>> ops respect encounter order even though it may be expensive
>>  - Provide an .unordered() op for people to opt out of the encounter
>> order when they know they don't care.
>>  - Impute encounter order if we need one and there isn't one (rather
>> than throwing)
> Overall, looks good to me.
>
> Maybe groupBy and reduceBy aren't worth the trouble: at least if
> something returns a Map, IMO nobody expects ordering in this map.
> Collections in groupBy are a different story: this is very much like
> stable sorting.

People don't expect ordering of the *keys*, and that's fine.  What I was 
talking about was ordering of the values, since the Map returned is a 
Map<K, Collection<V>>.

For example:

   list = [ 1..10 ]
   Map<Boolean, Collection<Integer>> map = list.groupBy(e -> e % 2 == 0);

Should the map be
{ true: [ 2, 4, 6, 8, 10 ], false: [ 1, 3, 5, 7, 9] } // respect order
or
{ true: [ random evens ], false: [ random odds] } // ignore order

That's the choice I think we face in groupBy and reduceBy.