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

sdk/lib/core/iterable.dart

Index: sdk/lib/core/iterable.dart
diff --git a/sdk/lib/core/iterable.dart b/sdk/lib/core/iterable.dart
index 604c4a88940ff9bbe8cf1dc08cd88ded2e160531..65bd21ef71edef9d42596744329ebde1eb474ab7 100644
--- a/sdk/lib/core/iterable.dart
+++ b/sdk/lib/core/iterable.dart
@@ -98,12 +98,30 @@ abstract class Iterable<E> {
    * 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;