Add Iterable.fold (and Stream.fold) which replace `reduce`.

sdk/lib/core/iterable.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * The [Iterable] interface allows to get an [Iterator] out of an
  * [Iterable] object.
  *
@@ skipping 80 matching lines @@
   void forEach(void f(E element)) {
     for (E element in this) f(element);
   }
 
   /**
    * Reduce a collection to a single value by iteratively combining each element
    * of the collection with an existing value using the provided function.
    * Use [initialValue] as the initial value, and the function [combine] to
    * create a new value from the previous one and an element.
    *
-   * Example of calculating the sum of a collection:
+   * Example of calculating the sum of an iterable:
    *
-   *   collection.reduce(0, (prev, element) => prev + element);
+   *   iterable.reduce((prev, element) => prev + element);
+   *
+   * *UPCOMING API-CHANGE*: this method will soon be changed to not take
+   * an initial value: `iterable.reduce(min)`. Use [fold] instead.

[kevmoo-old, 2013/04/03 17:45:51]

I'd actually mark this API as @deprecated.

It cannot be used in its new form yet.
The current form is going to die, breaking current users in the process.
Better for current users to get the deprecation warnings in editor/analyzer.
This comment will be easy to miss for folks w/ big libraries.

Although keep the comment that reduce will be reborn w/ a new behavior. That's
goodness.

[Lasse Reichstein Nielsen, 2013/04/04 08:35:18]

Agree. Mark as deprecated. Anyone using the current version is doing it wrong.

[floitsch, 2013/04/05 16:10:03]

Done.

    */
   dynamic reduce(var initialValue,
                  dynamic combine(var previousValue, E element)) {
+    return fold(initialValue, combine);
+  }
+
+  /**
+   * Reduce a collection to a single value by iteratively combining each element
+   * of the collection with an existing value using the provided function.
+   * Use [initialValue] as the initial value, and the function [combine] to
+   * create a new value from the previous one and an element.
+   *
+   * Example of calculating the sum of an iterable:
+   *
+   *   iterable.fold(0, (prev, element) => prev + element);
+   */
+  dynamic fold(var initialValue,
+               dynamic combine(var previousValue, E element)) {
     var value = initialValue;
     for (E element in this) value = combine(value, element);
     return value;
   }
 
   /**
    * Returns true if every elements of this collection satisify the
    * predicate [f]. Returns false otherwise.
    */
   bool every(bool f(E element)) {
@@ skipping 322 matching lines @@
  */
 abstract class BidirectionalIterator<T> extends Iterator<T> {
   /**
    * Move back to the previous element.
    *
    * Returns true and updates [current] if successful. Returns false
    * and sets [current] to null if there is no previous element.
    */
   bool movePrevious();
 }