Forms for reduce() -- part 1

[Raab, Donald]

> Open question: do we keep the name mutableReduce to make it clear what
> is going on?

If you went without the name, I'm not sure how clear it will be with the existing types that one is mutating or non mutating.  Would this make sense, or not so much?

      <U> U reduce(U zero,
                   BiFunction<U, T, U> nonMutatingAccumulator,
                   BinaryOperator<U> nonMutatingReducer);
 
      <R> R reduce(Supplier<R> seedFactory,
                   BiBlock<R, T> mutatingAccumulator,
                   BiBlock<R, R> mutatingReducer);

These are APIs we've had in a separate library for several years that we've moved into GS Collections RichIterable interface and which will become available in our 3.0 release.  They are a combination of groupBy/injectInto so certainly have some differences to reduce, but they also have some similarities in terms of supporting mutating/non-mutating versions.  We chose not to go with the name mutableAggregateBy, but instead named the parameter mutatingAggregator or nonMutatingAggregator.  We felt the difference in type made it pretty clear (Function2 vs. Procedure2).

    /**
     * Applies an aggregate procedure over the iterable grouping results into a Map based on the specific groupBy function.
     * Aggregate results are required to be mutable as they will be changed in place by the procedure.  A second function
     * specifies the initial "zero" aggregate value to work with (e.g. new AtomicInteger(0)).
     *
     * @since 3.0
     */
    <K, V> MapIterable<K, V> aggregateBy(
		Function<? super T, ? extends K> groupBy, 
		Function0<? extends V> zeroValueFactory, 
		Procedure2<? super V, ? super T> mutatingAggregator);

    /**
     * Applies an aggregate function over the iterable grouping results into a map based on the specific groupBy function.
     * Aggregate results are allowed to be immutable as they will be replaced in place in the map.  A second function
     * specifies the initial "zero" aggregate value to work with (e.g. new Integer(0)).
     *
     * @since 3.0
     */
    <K, V> MapIterable<K, V> aggregateBy(
		Function<? super T, ? extends K> groupBy, 
		Function0<? extends V> zeroValueFactory, 
		Function2<? super V, ? super T, ? extends V> nonMutatingAggregator);