package java.util;

/**
 * An iterator over a collection. {@code Iterator} takes the place of {@link Enumeration} in the
 * Java Collections Framework. Iterators differ from enumerations in two ways:
 *
 * <ul>
 * <li>Iterators allow the caller to remove elements from the underlying collection during the
 * iteration with well-defined semantics.
 * <li>Method names have been improved.
 * </ul>
 *
 * <p>
 * This interface is a member of the Java Collections Framework
 *
 * @param <E>
 *        the type of elements returned by this iterator
 */
public interface Iterator<E> {

    /**
     * Returns {@code true} if the iteration has more elements. (In other words, returns {@code true} if
     * {@link #next} would return an element rather than throwing an exception.)
     *
     * @return {@code true} if the iteration has more elements
     */
    boolean hasNext();

    /**
     * Returns the next element in the iteration.
     *
     * @return the next element in the iteration
     * @throws NoSuchElementException
     *         if the iteration has no more elements
     */
    E next();

    /**
     * Removes from the underlying collection the last element returned by this iterator (optional
     * operation). This method can be called only once per call to {@link #next}. The behavior of an
     * iterator is unspecified if the underlying collection is modified while the iteration is in
     * progress in any way other than by calling this method.
     *
     * @throws UnsupportedOperationException
     *         if the {@code remove} operation is not supported by this iterator
     *
     * @throws IllegalStateException
     *         if the {@code next} method has not yet been called, or the {@code remove} method has
     *         already been called after the last call to the {@code next} method
     */
    void remove();
}