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

[Andrei Mouravski, 2012/11/19 21:32:59]

Should this be "[f]"?

[nweiz, 2012/11/19 22:30:08]

Yes. 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
+   * iteration to stop and will be piped through the returned [Future].
+   */
+  static Future forEach(Iterable input, Future f(element)) {

[floitsch, 2012/11/19 10:05:42]

I don't think we need/want this function. We should rather write:
list.mappedBy(f).foldX(Future.wait)

foldX (still looking for a name) would take the first value from the iterable
and then combine it with the remaining elements.
Future.wait (still looking for a name) would take two futures and produce a
future when both are finished.

Now this is not yet perfect (empty lists...), and even when writing this comment
I have already better ideas of doing this, but the general idea is there.

[Bob Nystrom, 2012/11/19 19:55:07]

How about reduce() for the operation that takes a seed and fold() for the one
that uses the first element as the seed?

[nweiz, 2012/11/19 21:08:15]

That wouldn't do the same thing as this function. It would start running each
future immediately in parallel, rather than running them in sequence. To do this
function, you'd need to do something like:

    list.foldX((element, future) {
      return future.chain((_) => f(element));
    }, new Future.immediate());

I think that's complicated enough that it's worth adding a helper function.

[nweiz, 2012/11/19 21:08:15]

In terms of naming, I'd rather see the operation have the same name for both
taking a seed and not taking a seed. I think reduce() and fold() are both
reasonable names; they're both common in other languages.

This is somewhat off-topic, but I don't like how much longer "mappedBy" is than
"map". I'm not sure the extra length is worth having it be adjective-form,
especially if there are other method names that are verb-form like "fold".

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