// 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.core;

/**
 * An interface for getting items, one at a time, from an object.
 *
 * The for-in construct transparently uses `Iterator` to test for the end
 * of the iteration, and to get each item (or _element_).
 *
 * If the object iterated over is changed during the iteration, the
 * behavior is unspecified.
 *
 * The `Iterator` is initially positioned before the first element.
 * Before accessing the first element the iterator must thus be advanced using
 * [moveNext] to point to the first element.
 * If no element is left, then [moveNext] returns false, [current]
 * returns `null`, and all further calls to [moveNext] will also return false.
 *
 * A typical usage of an Iterator looks as follows:
 *
 *     var it = obj.iterator;
 *     while (it.moveNext()) {
 *       use(it.current);
 *     }
 *
 * **See also:** [Iteration]
 * (http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-iteration)
 * in the [library tour]
 * (http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
 */
abstract class Iterator<E> {
  /**
   * Moves to the next element.
   *
   * Returns true if [current] contains the next element.
   * Returns false if no elements are left.
   *
   * It is safe to invoke [moveNext] even when the iterator is already
   * positioned after the last element.
   * In this case [moveNext] returns false again and has no effect.
   *
   * A call to `moveNext` may throw if iteration has been broken by
   * changing the underlying collection.
   */
  bool moveNext();

  /**
   * Returns the current element.
   *
   * Returns `null` if the iterator has not yet been moved to the first
   * element, or if the iterator has been moved past the last element of the
   * [Iterable].
   *
   * The `current` getter should keep its value until the next call to
   * [moveNext], even if an underlying collection changes.
   * After a successful call to `moveNext`, the user doesn't need to cache
   * the current value, but can keep reading it from the iterator.
   */
  E get current;
}