Add Future.doWhile to dart:async.

sdk/lib/async/future.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.
 
 part of dart.async;
 
 /**
  * An object representing a delayed computation.
  *
  * A [Future] is used to represent a potential value, or error,
@@ skipping 273 matching lines @@
 
   /**
    * Perform an async operation for each element of the iterable, in turn.
    *
    * Runs [f] for each element in [input] in order, moving to the next element
    * only when the [Future] returned by [f] completes. Returns a [Future] that
    * completes when all elements have been processed.
    *
    * The return values of all [Future]s are discarded. Any errors will cause the
    * iteration to stop and will be piped through the returned [Future].
+   *
+   * [f] may return a [Future] or a non-[Future] value.

[Lasse Reichstein Nielsen, 2014/06/26 06:26:49]

Add "The function " first, to not begin the sentence with a lower-case letter.

A "Future or a non-Future" sounds like it can just return anything (well, it
can), but doesn't say what difference it makes.
How about:

If [f] returns a non-future, iteration continues immediately, otherwise it waits
for the returned future to complete.

[nweiz, 2014/06/26 19:48:11]

Done.

    */
-  static Future forEach(Iterable input, Future f(element)) {
+  static Future forEach(Iterable input, f(element)) {
+    Iterator iterator = input.iterator;
+    return doWhile(() {
+      if (!iterator.moveNext()) return false;
+      return new Future.sync(() => f(iterator.current)).then((_) => true);

[Lasse Reichstein Nielsen, 2014/06/26 06:26:49]

Maybe:
  return new Future.sync(() { f(iterator.current); return true; });

You can even move this function outside the doWhile, so you don't need to create
a new closure for each element:

Iterator iterator = input.iterator;
var callback = () { f(iterator.current); return true; };
return doWhile(() {
  if (!iterator.moveNext()) return false;
  return new Future.sync(callback);
};

[nweiz, 2014/06/26 19:48:11]

That doesn't handle the case where f returns a Future.
This seems like premature optimization.

+    });
+  }
+
+  /**
+   * Perform an async operation repeatedly until it returns `false`.
+   *
+   * Runs [f] repeatedly, starting the next iteration only when the [Future]
+   * returned by [f] completes to `true`. Returns a [Future] that completes once
+   * [f] returns `false`.
+   *
+   * The return values of all [Future]s are discarded. Any errors will cause the
+   * iteration to stop and will be piped through the returned [Future].
+   *
+   * [f] may return a [Future<bool>] or a non-[Future] [bool].

[Lasse Reichstein Nielsen, 2014/06/26 06:26:49]

It can return Future<dynamic> or Future<Object> as well, as long as the result
is a bool.
How about:

The function [f] must return either a [bool] value or a [Future] that will
complete with a [bool] value.

[nweiz, 2014/06/26 19:48:11]

Done.

+   */
+  static Future doWhile(f()) {
     _Future doneSignal = new _Future();
-    Iterator iterator = input.iterator;
-    void nextElement(_) {
-      if (iterator.moveNext()) {
-        new Future.sync(() => f(iterator.current))
-            .then(nextElement, onError: doneSignal._completeError);
+    var nextIteration;
+    // Bind this callback explicitly so that each iteration isn't bound in the
+    // context of all the previous iterations' callbacks.
+    nextIteration = Zone.current.bindUnaryCallback((bool keepGoing) {
+      if (keepGoing) {
+        new Future.sync(f).then(nextIteration,
+            onError: doneSignal._completeError);

[Lasse Reichstein Nielsen, 2014/06/26 06:26:49]

Maybe indent this line to the '('?

[nweiz, 2014/06/26 19:48:11]

Done.

       } else {
         doneSignal._complete(null);
       }
-    }
-    nextElement(null);
+    }, runGuarded: true);
+    nextIteration(keepGoing);

[Lasse Reichstein Nielsen, 2014/06/26 06:26:49]

keepGoing -> true ?
Tests? :)

[nweiz, 2014/06/26 19:48:11]

Done.

     return doneSignal;
   }
 
   /**
    * Register callbacks to be called when this future completes.
    *
    * When this future completes with a value,
    * the [onValue] callback will be called with that value.
    * If this future is already completed, the callback will not be called
    * immediately, but will be scheduled in a later microtask.
@@ skipping 298 matching lines @@
    *     theFuture.catchError(thisCompleter.completeError);
    *
    */
   void completeError(Object error, [StackTrace stackTrace]);
 
   /**
    * Whether the future has been completed.
    */
   bool get isCompleted;
 }