Add Stream.drain() method.

sdk/lib/async/stream.dart

 // Copyright (c) 2013, 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;
 
 // -------------------------------------------------------------------
 // Core Stream types
 // -------------------------------------------------------------------
 
@@ skipping 481 matching lines @@
       },
       onError: future._setError,
       onDone: () {
         future._setValue(result);
       },
       cancelOnError: true);
     return future;
   }
 
   /**
+   * Discards all data on the stream, but signals when it's done or an error
+   * occured.
+   *
+   * When subscribing using [drain], cancelOnError will be true. This means
+   * that the future will complete with the first error on the stream and then
+   * cancel the subscription.
+   *
+   * In case of a `done` event the future completes with the given
+   * [futureValue].
+   */
+  Future drain([var futureValue]) => listen(null, cancelOnError: true)
+      .asFuture(futureValue);
+
+  /**
    * Provides at most the first [n] values of this stream.
    *
    * Forwards the first [n] data events of this stream, and all error
    * events, to the returned stream, and ends with a done event.
    *
    * If this stream produces fewer than [count] values before it's done,
    * so will the returned stream.
    */
   Stream<T> take(int count) {
     return new _TakeStream(this, count);
@@ skipping 700 matching lines @@
 }
 
 class _EventOutputSinkWrapper<T> extends EventSink<T> {
   _EventOutputSink _sink;
   _EventOutputSinkWrapper(this._sink);
 
   void add(T data) { _sink._sendData(data); }
   void addError(error) { _sink._sendError(error); }
   void close() { _sink._sendDone(); }
 }