Make Iterable more powerful (and lazy).

sdk/lib/core/queryable.dart

+// Copyright (c) 2012, 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.
+
+/**
+ * The [Queryable] interface extends the [Iterable] interface and adds
+ * functionality that can be expressed with iterators but does not necessarily
+ * make sense on collections that implement [Iterable].
+ */
+abstract class Queryable<E> extends Iterable<E> {
+  /**
+   * Returns a lazy [Queryable] with at most [count] elements.
+   *
+   * If [this] produces less than [count] elements, then the resulting
+   * [Queryable] will produce less than [count] elements, too.
+   */
+  Queryable<E> take(int count);
+
+  /**
+   * Returns a lazy [Queryable] that stops once [f] is not satisfied any more.
+   *
+   * When iterating over the new [Queryable], the iterator will pass through all
+   * elements of [this] while the predicate [f] is satisfied. When the iterator
+   * encounters an element [:e:] that does not satisfy [f] it discards [:e:]
+   * and will not provide any more elements.
+   */
+  Queryable<E> takeWhile(bool f(E element));
+
+  /**
+   * Returns a lazy [Queryable] where the first [count] elements are ignored.
+   *
+   * If [this] produces less than [count] elements, then the resulting
+   * [Queryable] will not produce any element at all.
+   */
+  Queryable<E> skip(int count);
+
+  /**
+   * Returns a lazy [Queryable] that discards the longest leading sequence of
+   * elements that all satisfy [f].
+   *
+   * When iterating over the new [Queryable], the iterator will skip all
+   * elements of [this] until the given predicate [f] is not satisfied. From
+   * that moment on, all elements are passed through.
+   */
+  Queryable<E> skipWhile(bool f(E element));
+
+  /**
+   * TODO(floitsch): can we have something like this? It would definitely be
+   * handy.
+   */
+  // Queryable<E> ofType(Type type);
+
+  /**
+   * Returns a lazy [Queryable] that ignores duplicates.
+   *
+   * When iterating over the return [Queryable] duplicate elements, determined
+   * by the given [compare] function, are ignored. That is, the iterator will
+   * pass through the first occurence of the duplicates but will skip the
+   * following ones.
+   */
+  Queryable<E> distinct([int compare = Compareable.compareTo]);
+
+  /**
+   * Returns the first element that satisfies the given predicate [f].
+   *
+   * If none matches the result of invoking the [defaultValue] function is
+   * returned. By default, without a given [defaultValue], an exception is
+   * thrown.
+   * TODO(floitsch): which one?
+   */
+  E firstMatching(bool f(E element), { E defaultValue() });
+
+  /**
+   * Returns the last element that satisfies the given predicate [f].
+   *
+   * If none matches the result of invoking the [defaultValue] function is
+   * returned. By default, without a given [defaultValue], an exception is
+   * thrown.
+   * TODO(floitsch): which one?
+   */
+  E lastMatching(bool f(E element), { E defaultValue() });
+
+  /**
+   * Returns the single element that satisfies [f]. If no or more than one
+   * element match an exception is thrown.
+   * TODO(floitsch): which one?
+   */
+  E single(bool f(E element));
+
+  /**
+   * Returns the [index]th element.
+   *
+   * Iterating over a queryable that has less than [index] elements will throw
+   * an exception.
+   * TODO(floitsch): which one?
+   */
+  E elementAt(int index);
+}