Make Iterable more powerful (and lazy).

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 19972c12fd94c46ef1e36b2a13e5140d46624d91..a10922d1efa2661ae9b0d13806d369994ead9fc6 100644
--- a/sdk/lib/core/iterable.dart
+++ b/sdk/lib/core/iterable.dart
@@ -3,20 +3,109 @@
 // BSD-style license that can be found in the LICENSE file.
 
 /**
- * The [Iterable] interface allows to get an [Iterator] out of an
- * [Iterable] object.
+ * The [Iterable] interface groups functionality that can be expressed on top
+ * of [Iterator]s.
  *
- * This interface is used by the for-in construct to iterate over an
- * [Iterable] object.
- * The for-in construct takes an [Iterable] object at the right-hand
- * side, and calls its [iterator] method to get an [Iterator] on it.
- *
- * A user-defined class that implements the [Iterable] interface can
- * be used as the right-hand side of a for-in construct.
+ * [Iterable]s provide an [iterator] getter and can thus be used as the
+ * right-hand side of a for-in construct.
  */
 abstract class Iterable<E> {

[Anders Johnsen, 2012/11/06 17:51:47]

I think this would be a good time to introduce

 Iterable expand(Iterable f(E element));

   /**
    * Returns an [Iterator] that iterates over this [Iterable] object.
    */
   Iterator<E> iterator();
+
+  /**
+   * Returns a lazy [Iterable] where each element [:e:] of [this] is replaced
+   * by the result of [:f(e):].
+   *
+   * This method returns a view of the mapped elements. As long as the
+   * returned [Iterable] is not iterated over, the supplied function [f] will
+   * not be invoked. The transformed elements will not be cached. Iterating
+   * multiple times over the the returned [Iterable] will invoke the supplied
+   * function [f] multiple times on the same element.
+   */
+  Iterable map(f(E element));
+
+  /**
+   * Returns a lazy [Iterable] with all elements [:e:] that satisfy the
+   * predicate [f].
+   *
+   * This method returns a view of the mapped elements. As long as the
+   * returned [Iterable] is not iterated over, the supplied function [f] will
+   * not be invoked. Iterating will not cache results, and thus iterating
+   * multiple times over the the returned [Iterable] will invoke the supplied
+   * function [f] multiple times on the same element.
+   */
+  Iterable<E> filter(bool f(E element));
+
+  /**
+   * Checks whether [this] contains an element equal to [element] by
+   * iterating over it.
+   */
+  bool contains(E element) {
+    for (E e in this) {
+      if (e == element) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Applies the function [f] to each element of [this] by iterating over it.
+   */
+  void forEach(void f(E element)) {
+    for (E element in this) f(element);
+  }
+
+  /**
+   * Reduces this [Iterable] to a single value by iterating over [this] and
+   * iteratively combining each element of the collection with an existing
+   * value using the provided function.
+   *
+   * Uses [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:
+   *
+   *   collection.reduce(0, (prev, element) => prev + element);
+   */
+  Dynamic reduce(var initialValue,
+                 Dynamic combine(var previousValue, E element)) {

[Mads Ager (google), 2012/11/07 07:13:19]

Dynamic -> dynamic

+    var value = initialValue;
+    for (E element in this) value = combine(value, element);
+    return value;
+  }
+
+  /**
+   * Returns true if every element of [this] satisifies the predicate [f].
+   * Returns false otherwise.
+   *
+   * The iteration of [this] is stopped as soon as one non-satisfying element is
+   * found.
+   */
+  bool every(bool f(E element)) {
+    for (E element in this) {
+      if (!f(element)) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Returns true if at least one element of [this] satisfies the predicate [f].
+   * Returns false otherwise.
+   *
+   * The iteration of [this] is stopped as soon as one satisfying element is
+   * found.
+   */
+  bool any(bool f(E element)) {
+    for (E element in this) {
+      if (f(element)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Returns true if there is no element in [this].
+   */
+  bool get isEmpty => !iterator().hasNext;
 }