Add Iterable.empty constructor.

sdk/lib/core/iterable.dart

 // Copyright (c) 2011, 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.core;
 
 /**
  * A collection of values, or "elements", that can be accessed sequentially.
  *
  * The elements of the iterable are accessed by getting an [Iterator]
@@ skipping 84 matching lines @@
    *
    * As an `Iterable`, `new Iterable.generate(n, generator))` is equivalent to
    * `const [0, ..., n - 1].map(generator)`.
    */
   factory Iterable.generate(int count, [E generator(int index)]) {
     if (count <= 0) return new EmptyIterable<E>();
     return new _GeneratorIterable<E>(count, generator);
   }
 
   /**
+   * Creates an empty iterable.
+   *
+   * The empty iterable has no elements, and iterating it always stops
+   * immediately.
+   *
+   * An empty iterable can be used in places where you always know that
+   * the iterable you would otherwise is always empty.

[Søren Gjesse, 2015/05/21 09:10:06]

Seems like there is a word missing after "otherwise".

+   */
+  const factory Iterable.empty() = EmptyIterable<E>;

[kevmoo, 2015/05/21 15:07:06]

Why is this useful over using `const []`?

[Lasse Reichstein Nielsen, 2015/05/21 15:16:51]

Because const[] is a List, not just an Iterable.
You shouldn't return a class that is more capable than our interface requires,
at least not in library code, because sooner or later someone is going to rely
on it.

I was about to do a new DelegatingIterable(const []) when I decided that I
should just get around to add this constructor (which I had plans for before I
even started working on the libraries :).

And the class already existed, so it was either moving it to a public library
(from dart:_internal) or giving access to it like this.

+
+  /**
    * Returns a new `Iterator` that allows iterating the elements of this
    * `Iterable`.
    *
    * Iterable classes may specify the iteration order of their elements
    * (for example [List] always iterate in index order),
    * or they may leave it unspecified (for example a hash-based [Set]
    * may iterate in any order).
    *
    * Each time `iterator` is read, it returns a new iterator,
    * which can be used to iterate through all the elements again.
@@ skipping 539 matching lines @@
  */
 abstract class BidirectionalIterator<E> implements Iterator<E> {
   /**
    * Move back to the previous element.
    *
    * Returns true and updates [current] if successful. Returns false
    * and sets [current] to null if there is no previous element.
    */
   bool movePrevious();
 }