# ListIterator

public interface **ListIterator** implements [Iterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html)\<E\> An iterator for lists that allows the programmer
to traverse the list in either direction, modify
the list during iteration, and obtain the iterator's
current position in the list. A `ListIterator`
has no current element; its *cursor position* always
lies between the element that would be returned by a call
to `previous()` and the element that would be
returned by a call to `next()`.
An iterator for a list of length `n` has `n+1` possible
cursor positions, as illustrated by the carets (`^`) below:

```
                      Element(0)   Element(1)   Element(2)   ... Element(n-1)
 cursor positions:  ^            ^            ^            ^                  ^
 
```
Note that the `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#remove()` and `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#set(E)` methods are *not* defined in terms of the cursor position; they are defined to operate on the last element returned by a call to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` or `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()`.

This interface is a member of the
[Java Collections Framework](https://developers.google.com/j2objc/javadoc/jre/technotes/guides/collections/index.html).

##### See Also

- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Collection.html`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/List.html`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Enumeration.html`
- `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/List.html#listIterator()`

### Public Method Summary

|---|---|
| abstract void | [add](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#add(E))(E e) Inserts the specified element into the list (optional operation). |
| abstract boolean | [hasNext](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#hasNext())() Returns `true` if this list iterator has more elements when traversing the list in the forward direction. |
| abstract boolean | [hasPrevious](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#hasPrevious())() Returns `true` if this list iterator has more elements when traversing the list in the reverse direction. |
| abstract E | [next](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next())() Returns the next element in the list and advances the cursor position. |
| abstract int | [nextIndex](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#nextIndex())() Returns the index of the element that would be returned by a subsequent call to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()`. |
| abstract E | [previous](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous())() Returns the previous element in the list and moves the cursor position backwards. |
| abstract int | [previousIndex](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previousIndex())() Returns the index of the element that would be returned by a subsequent call to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()`. |
| abstract void | [remove](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#remove())() Removes from the list the last element that was returned by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` or `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()` (optional operation). |
| abstract void | [set](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#set(E))(E e) Replaces the last element returned by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` or `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()` with the specified element (optional operation). |

### Inherited Method Summary

From interface [java.util.Iterator](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html)

|---|---|
| void | [forEachRemaining](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html#forEachRemaining(java.util.function.Consumer<?%20super%20E>))([Consumer](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/function/Consumer.html)\<? super E\> action) Performs the given action for each remaining element until all elements have been processed or the action throws an exception. |
| abstract boolean | [hasNext](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html#hasNext())() Returns `true` if the iteration has more elements. |
| abstract E | [next](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html#next())() Returns the next element in the iteration. |
| void | [remove](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/Iterator.html#remove())() Removes from the underlying collection the last element returned by this iterator (optional operation). |

## Public Methods

#### public abstract void
**add**
(E e)

Inserts the specified element into the list (optional operation).
The element is inserted immediately before the element that
would be returned by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()`, if any, and after the element
that would be returned by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()`, if any. (If the
list contains no elements, the new element becomes the sole element
on the list.) The new element is inserted before the implicit
cursor: a subsequent call to `next` would be unaffected, and a
subsequent call to `previous` would return the new element.
(This call increases by one the value that would be returned by a
call to `nextIndex` or `previousIndex`.)

##### Parameters

| e | the element to insert |
|---|---|

##### Throws

| [UnsupportedOperationException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/UnsupportedOperationException.html) | if the `add` method is not supported by this list iterator |
| [ClassCastException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/ClassCastException.html) | if the class of the specified element prevents it from being added to this list |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if some aspect of this element prevents it from being added to this list |
|---|---|

#### public abstract boolean
**hasNext**
()

Returns `true` if this list iterator has more elements when
traversing the list in the forward direction. (In other words,
returns `true` if `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` would return an element rather
than throwing an exception.)

##### Returns

- `true` if the list iterator has more elements when traversing the list in the forward direction

#### public abstract boolean
**hasPrevious**
()

Returns `true` if this list iterator has more elements when
traversing the list in the reverse direction. (In other words,
returns `true` if `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()` would return an element
rather than throwing an exception.)

##### Returns

- `true` if the list iterator has more elements when traversing the list in the reverse direction

#### public abstract E
**next**
()

Returns the next element in the list and advances the cursor position.
This method may be called repeatedly to iterate through the list,
or intermixed with calls to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()` to go back and forth.
(Note that alternating calls to `next` and `previous`
will return the same element repeatedly.)

##### Returns

- the next element in the list

##### Throws

| [NoSuchElementException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/NoSuchElementException.html) | if the iteration has no next element |
|---|---|

#### public abstract int
**nextIndex**
()

Returns the index of the element that would be returned by a
subsequent call to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()`. (Returns list size if the list
iterator is at the end of the list.)

##### Returns

- the index of the element that would be returned by a subsequent call to `next`, or list size if the list iterator is at the end of the list

#### public abstract E
**previous**
()

Returns the previous element in the list and moves the cursor
position backwards. This method may be called repeatedly to
iterate through the list backwards, or intermixed with calls to
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` to go back and forth. (Note that alternating calls
to `next` and `previous` will return the same
element repeatedly.)

##### Returns

- the previous element in the list

##### Throws

| [NoSuchElementException](https://developers.google.com/j2objc/javadoc/jre/reference/java/util/NoSuchElementException.html) | if the iteration has no previous element |
|---|---|

#### public abstract int
**previousIndex**
()

Returns the index of the element that would be returned by a
subsequent call to `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()`. (Returns -1 if the list
iterator is at the beginning of the list.)

##### Returns

- the index of the element that would be returned by a subsequent call to `previous`, or -1 if the list iterator is at the beginning of the list

#### public abstract void
**remove**
()

Removes from the list the last element that was returned by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` or `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()` (optional operation). This call can
only be made once per call to `next` or `previous`.
It can be made only if `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#add(E)` has not been
called after the last call to `next` or `previous`.

##### Throws

| [UnsupportedOperationException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/UnsupportedOperationException.html) | if the `remove` operation is not supported by this list iterator |
| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if neither `next` nor `previous` have been called, or `remove` or `add` have been called after the last call to `next` or `previous` |
|---|---|

#### public abstract void
**set**
(E e)

Replaces the last element returned by `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#next()` or
`https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#previous()` with the specified element (optional operation).
This call can be made only if neither `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#remove()` nor `https://developers.google.com/j2objc/javadoc/jre/reference/java/util/ListIterator.html#add(E)` have been called after the last call to `next` or
`previous`.

##### Parameters

| e | the element with which to replace the last element returned by `next` or `previous` |
|---|---|

##### Throws

| [UnsupportedOperationException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/UnsupportedOperationException.html) | if the `set` operation is not supported by this list iterator |
| [ClassCastException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/ClassCastException.html) | if the class of the specified element prevents it from being added to this list |
| [IllegalArgumentException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalArgumentException.html) | if some aspect of the specified element prevents it from being added to this list |
| [IllegalStateException](https://developers.google.com/j2objc/javadoc/jre/reference/java/lang/IllegalStateException.html) | if neither `next` nor `previous` have been called, or `remove` or `add` have been called after the last call to `next` or `previous` |
|---|---|