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..4983580ce0400087b075514248cc919a1781aad7 100644
--- a/sdk/lib/core/iterable.dart
+++ b/sdk/lib/core/iterable.dart
@@ -3,20 +3,114 @@
 // 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> {
   /**
    * Returns an [Iterator] that iterates over this [Iterable] object.
    */
-  Iterator<E> iterator();
+  Iterator<E> get iterator;
+
+  /**
+   * Returns a [Queryable] view of [this].
+   */
+   Queryable<E> query();

[Lasse Reichstein Nielsen, 2012/11/12 09:38:03]

Make it a getter. Even if it returns a new Queryable every time, they are for
all purposes equivalent.

[floitsch, 2012/11/16 22:31:07]

the name is a verb. -> no getter. But if we change the name it can become a
getter.

[Lasse Reichstein Nielsen, 2012/11/19 13:36:09]

But it IS a noun ?!? :)

+
+  /**
+   * Returns a lazy [Queryable] 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 [Queryable] 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 [Queryable] will invoke the supplied
+   * function [f] multiple times on the same element.
+   */
+  Queryable mappedBy(f(E element));
+
+  /**
+   * Returns a lazy [Queryable] with all elements [:e:] that satisfy the

[Lasse Reichstein Nielsen, 2012/11/12 09:38:03]

You don't need to name 'e' if you don't use it later. Either remove "[:e:]" or
change to "predicate [:f(e):]".

[floitsch, 2012/11/16 22:31:07]

Done.

+   * predicate [f].
+   *
+   * This method returns a view of the mapped elements. As long as the
+   * returned [Queryable] 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 [Queryable] will invoke the supplied
+   * function [f] multiple times on the same element.
+   */
+  Queryable<E> where(bool f(E element));
+
+  /**
+   * Checks whether [this] contains an element equal to [element]. This
+   * operation can be slow if [this] needs to iterate over all elements.
+   */
+  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 [this] 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 an [Iterable]:
+   *
+   *   collection.reduce(0, (prev, element) => prev + element);
+   */
+  dynamic reduce(var initialValue,
+                 dynamic combine(var previousValue, E element)) {
+    var value = initialValue;
+    for (E element in this) value = combine(value, element);
+    return value;
+  }

[Lasse Reichstein Nielsen, 2012/11/12 09:38:03]

You often want a reduction that uses the first value as initial and then
iterates on the remaining. It'll have to throw on empty iterables, and I don't
have a good name for it, but I think we should have it.

[floitsch, 2012/11/16 22:31:07]

if we find a good way, why not.

+
+  /**
+   * 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;

[Lasse Reichstein Nielsen, 2012/11/12 09:38:03]

Consider adding 'hasElements' that has the opposite value. It's often useful and
more readable.

[floitsch, 2012/11/16 22:31:07]

hasElements is imho a bad name. I would prefer isNotEmpty. That's what we use in
real world when we speak of collections.

 }