Add Future.of that calls a function and captures the result

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;
 
 /**
  * A [Future] represents a delayed computation. It is used to obtain a not-yet
  * available value, or error, sometime in the future.  Receivers of a
  * [Future] can register callbacks that handle the value or error once it is
@@ skipping 67 matching lines @@
  * [catchError]) is handling the errors for exceptions coming from calls to
  * 'foo', as well as 'bar'. This would not be the case if the error-handler was
  * registered at the same time as the value-handler.
  *
  * Futures can have more than one callback-pairs registered. Each successor is
  * treated independently and is handled as if it was the only successor.
  */
 // TODO(floitsch): document chaining.
 abstract class Future<T> {
   /**
+   * Creates a future containing the result of calling [function].
+   *
+   * The result of computing [:function():] is used to return
+   * a completed future with that result.
+   * If [function] returns a [Future], this will create a future that
+   * will eventually complete with the same result.

[floitsch, 2013/02/01 12:44:11]

Maybe explain it in contrast to "immediate".
This constructor is similar to [Futureimmediate] but behaves differently, if the
result of invoking [function] returns a [Future] or throws.
If the first case the result of the factory is the result of the invocation, and
in the latter the error is caught and the returned future fails.

Or something similar.

Maybe explain the motivations when someone should use this constructor.

[Lasse Reichstein Nielsen, 2013/02/01 13:16:50]

I think I'll do it the opposite way:
 new Future.immediate(v) 
where v is not a Future, is equivalent to:
 new Future.of(() => v);

+   */
+  factory Future.of(function()) {
+    try {
+      var result = function();
+      if (result is Future) return new _FutureWrapper<T>(result);

[floitsch, 2013/02/01 12:44:11]

should we wrap?

[Lasse Reichstein Nielsen, 2013/02/01 13:16:50]

That was my question too. I decided to do it just to be safe, but I can, easily,
be convinced not to.

+      return new _FutureImpl<T>.immediate(result);
+    } catch (error, stackTrace) {
+      return new _FutureImpl<T>.immediateError(error, stackTrace);
+    }
+  }
+
+  /**
    * A future whose value is available in the next event-loop iteration.
    *
    * See [Completer]s, for futures with values that are computed asynchronously.
    */
   factory Future.immediate(T value) => new _FutureImpl<T>.immediate(value);
 
   /**
    * A future that completes with an error in the next event-loop iteration.
    *
    * See [Completer]s, for futures with values that are computed asynchronously.
@@ skipping 210 matching lines @@
    * The argument [exception] should not be `null`.
    *
    * If [exception] is an [AsyncError], it is used directly as the error
    * message sent to the future's listeners, and [stackTrace] is ignored.
    *
    * Otherwise the [exception] and an optional [stackTrace] is combined into an
    * [AsyncError] and sent to this future's listeners.
    */
   void completeError(Object exception, [Object stackTrace]);
 }