Make Iterable more powerful (and lazy).

sdk/lib/core/queryable.dart

Index: sdk/lib/core/queryable.dart
diff --git a/sdk/lib/core/queryable.dart b/sdk/lib/core/queryable.dart
new file mode 100644
index 0000000000000000000000000000000000000000..634846227cde53fdc5792569f83ed6e6471dc333
--- /dev/null
+++ b/sdk/lib/core/queryable.dart
@@ -0,0 +1,104 @@
+// 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.
+
+abstract class Queryable<E> extends Iterable<E> {

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

Needs a description on the class. What is it?

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

Done.

+  /**
+   * 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] until the given predicate [f] is not satisfied. From
+   * that moment on no other elements are passed through.

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

Is the first non-matching element included?
(I assume not, but it's not clear).

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

Yes, but the comments need to be improved by a lot. It is difficult to express
an iterable in terms of the behavior of their iterators.
Also it needs to be clear that no further elements will be iterated over.
Slightly improved the doc.

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

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

We don't have an easy way to test if an object is a Type, so this would require
mirroring.
For now: No.
I wouldn't mind if Type had a "isInstance(Object v)". Perhaps a Type could be a
Type<T> for the type (but maybe I'm being too Java'ish).

+   */
+  // 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 a lazy [Queryable] that skips all elements except the first
+   * matching one.
+   *
+   * This method is equivalent to [:this.where(f).take(1):].
+   *
+   * TODO(floitsch): C# throws an exception if none matches. Not sure if that
+   * helps.
+   */
+  Queryable<E> firstMatching(bool f(E element));

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

Why is this a Queryable if it only returns one element?
Shouldn't it just eagerly return the value?

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

doh. yes.
fixed and all the others below.

+
+  /**
+   * Returns a lazy [Queryable] that skips all elements except the first
+   * matching one. If no element matches, then the [defaultValue] is returned.
+   */
+  Queryable<E> firstMatchingOrDefault(bool f(E element), E defaultValue);

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

Make the defaultValue a closure returning the value, then make it optional (and
don't provide a default it if omitted), and rename to firstMatching (and remove
the one above).

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

Done.

+
+  /**
+   * Returns a lazy [Queryable] that skips all elements except the last
+   * matching one.
+   *
+   * TODO(floitsch): C# throws an exception if none matches. Not sure if that
+   * helps.
+   */
+  Queryable<E> lastMatching(bool f(E element));

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

Why not eager and returning a value?
This queryable can't return a value until the entire source has been iterated
anyway.

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

Done.

+
+  /**
+   * Returns a lazy [Queryable] that skips all elements except the last
+   * matching one. If no element matches, then the [defaultValue] is returned.
+   */
+  Queryable<E> lastMatchingOrDefault(bool f(E element), E defaultValue);

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

As above, make defaultValue an optional function that returns the default value.

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

Done.

+
+  /**
+   * Returns a lazy [Queryable] that skips all elements except the one
+   * satisfying [f]. If no or more than one element match, then an exception

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

"If no element match, or if more than one element match, then ..."
Is it an exception, or an error? If it's an exception, you should say which one.

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

added TODO.

+   * is thrown.
+   */
+  Queryable<E> single(bool f(E element));
+
+  /**
+   * Returns a lazy [Queryable] that returns the [index]th element.
+   *
+   * Iterating over a queryable that has less than [index] elements will throw
+   * an error. This method is thus not equivalent to

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

Have you considered which error? Seems like a RangeError.

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

No. Added TODO.

+   * [:this.skip(index - 1).take(1):].
+   */
+  Queryable<E> elementAt(int index);
+}