Add a Futures.forEach function for asynchronously iterating over a collection.

sdk/lib/core/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.
 
 /**
  * A [Future] is used to obtain a value sometime in the future.  Receivers of a
  * [Future] can obtain the value by passing a callback to [then]. For example:
  *
  *     Future<int> future = getFutureFromSomewhere();
  *     future.then((value) {
@@ skipping 241 matching lines @@
       });
       future.handleException((exception) {
         if (!result.isComplete) {
           completer.completeException(exception, future.stackTrace);
         }
         return true;
       });
     }
     return result;
   }
+
+  /// Runs [fn] for each element in [input] in order, moving to the next element

[Siggi Cherem (dart-lang), 2012/11/06 23:23:51]

nit: use /** */ docs (for consistency)

[nweiz, 2012/11/07 20:50:07]

Done.

+  /// only when the [Future] returned by [fn] 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

[Siggi Cherem (dart-lang), 2012/11/06 23:23:51]

nit 80 col

[Bob Nystrom, 2012/11/07 01:09:43]

Pub doesn't need a return value, but to be more generally useful, it would be
good to not drop it. How about making this complete with the list of values?

Then, given that, how about calling this map() instead?

[nweiz, 2012/11/07 20:50:07]

Done.

[nweiz, 2012/11/07 20:50:07]

I liked this idea when you first proposed it, but upon thinking about it more I
don't think it's the right way to go. This method is explicitly procedural and
side-effect based, whereas mapping is much more functional. I don't think it
makes sense to conflate the two; I think the situations where the order of
execution of the futures matters is going to be largely disjoint from the
situations where the return values matter. 

[Bob Nystrom, 2012/11/07 21:34:05]

SGTM.

+  /// iteration to stop and will be piped through the return value.

[Siggi Cherem (dart-lang), 2012/11/06 23:23:51]

to avoid confusion with the returned values above, maybe rephrase as 'through
the returned future'?

[nweiz, 2012/11/07 20:50:07]

Done.

+  static Future forEach(Iterable input, Future fn(element)) {

[Siggi Cherem (dart-lang), 2012/11/06 23:23:51]

nit: rename fn as f? (trying to match the signature used in collection.forEach

[nweiz, 2012/11/07 20:50:07]

Done.

+    var iterator = input.iterator();
+    Future nextElement(_) {
+      if (!iterator.hasNext) return new Future.immediate(null);
+      return fn(iterator.next()).chain(nextElement);
+    }
+    return nextElement(null);
+  }
 }