java容器 接口ListIterator源码分析

目录

 

简介

查询操作（与next，prev相关的6个方法）

修改操作（add，set，remove）

---

简介

/**
 * 一个对于列表的迭代器，允许编程者无论以哪个方向遍历列表，在迭代中修改列表，获取迭代器在列表中的实时位置。
 * 一个ListIterator总是处于一个由 previous()返回的元素和next()返回的元素中间。
 * 一个对于长度为n的列表，迭代器有n+1个可能的游标位置，以下面的^符号说明：
 * 
 * 
 *                      Element(0)   Element(1)   Element(2)   ... Element(n-1)
 * cursor positions:  ^            ^            ^            ^                  ^
 * 
 * 注意：remove和set方法没有按照游标位置定义，它们以最后一次调用next或者previous返回的元素定义。
 *
 *
 * @author  Josh Bloch
 * @see Collection
 * @see List
 * @see Iterator
 * @see Enumeration
 * @see List#listIterator()
 * @since   1.2
 */
public interface ListIterator extends Iterator

查询操作（与next，prev相关的6个方法）

    // Query Operations

    /**
     * 如果列表迭代器当以前进的方向遍历列表时，有更多的元素，返回true。
     * （换言而之，如果next方法返回一个元素，而不是抛出异常，返回true）
     *
     * @return {@code true} if the list iterator has more elements when
     *         traversing the list in the forward direction
     */
    boolean hasNext();

    /**
     * 返回列表中的下一个元素，并前进游标位置。
     * 这个方法可以被重复调用，来迭代列表，或者中间夹杂着调用previous来后退和前进。
     * （注意：交替调用next和previous会重复地返回相同的结果。
     *
     * @return the next element in the list
     * @throws NoSuchElementException if the iteration has no next element
     */
    E next();

    /**
     * 如果列表迭代器当以后退的方向遍历列表时，有更多的元素，返回true。
     * （换言而之，如果previous方法返回一个元素，而不是抛出异常，返回true）
     *
     * @return {@code true} if the list iterator has more elements when
     *         traversing the list in the reverse direction
     */
    boolean hasPrevious();

    /**
     * 返回列表中的上一个元素，并后退游标位置。
     * 这个方法可以被重复调用，来向后迭代列表，或者中间夹杂着调用next来后退和前进。
     * （注意：交替调用next和previous会重复地返回相同的结果。
     *
     * @return the previous element in the list
     * @throws NoSuchElementException if the iteration has no previous
     *         element
     */
    E previous();

    /**
     * 返回接下来调用next返回的元素的index。（如果迭代器处于列表末尾，返回列表大小）
     *
     * @return the index of the element that would be returned by a
     *         subsequent call to {@code next}, or list size if the list
     *         iterator is at the end of the list
     */
    int nextIndex();

    /**
     * 返回接下来调用previous返回的元素的index。（如果迭代器处于列表开始，返回-1）
     *
     * @return the index of the element that would be returned by a
     *         subsequent call to {@code previous}, or -1 if the list
     *         iterator is at the beginning of the list
     */
    int previousIndex();

修改操作（add，set，remove）

    // Modification Operations

    /**
     * 移除由next或previous返回的最后元素。
     * 对于一次next或previous，仅仅调用一次这个方法。
     * 当且仅当next或previous调用后，没有调用add方法，才能使用remove方法。
     *
     * @throws UnsupportedOperationException if the {@code remove}
     *         operation is not supported by this list iterator
     * @throws IllegalStateException if neither {@code next} nor
     *         {@code previous} have been called, or {@code remove} or
     *         {@code add} have been called after the last call to
     *         {@code next} or {@code previous}
     */
    void remove();

    /**
     * 将由next或previous返回的最后元素替换为指定元素（可选操作）。
     * 当且仅当next或previous调用后，没有调用remove和add方法，才能使用set方法。
     *
     * @param e the element with which to replace the last element returned by
     *          {@code next} or {@code previous}
     * @throws UnsupportedOperationException if the {@code set} operation
     *         is not supported by this list iterator
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this list
     * @throws IllegalArgumentException if some aspect of the specified
     *         element prevents it from being added to this list
     * @throws IllegalStateException if neither {@code next} nor
     *         {@code previous} have been called, or {@code remove} or
     *         {@code add} have been called after the last call to
     *         {@code next} or {@code previous}
     */
    void set(E e);

    /**
     * 插入指定元素到列表（可选操作）
     * 元素被迅速地插入，在next返回的元素之前，在previous返回的元素之后，
     * （如果列表没有元素，新的元素成为列表唯一一个元素）
     * 新的元素被插入到隐藏的游标前，接下来调用next不会被影响，接下来调用previous回访一个新的元素
     * （这个调用增加了nextIndex或previousIndex返回的值）
     *
     * @param e the element to insert
     * @throws UnsupportedOperationException if the {@code add} method is
     *         not supported by this list iterator
     * @throws ClassCastException if the class of the specified element
     *         prevents it from being added to this list
     * @throws IllegalArgumentException if some aspect of this element
     *         prevents it from being added to this list
     */
    void add(E e);