This page contains an archived post to the Java Answers Forum made prior to February 25, 2002. If you wish to participate in discussions, please visit the new Artima Forums.

Message:

JavaDoc Gives the Proper Semantics

Posted by Bill Venners on April 26, 2000 at 3:55 AM

> Exactly which element is affected by remove()?
> The tutorial
> http://java.sun.com/docs/books/tutorial/collections/interfaces/collection.html
> says "The remove method removes from the underlying Collection the
> last element that was returned by next." But this seems wrong. In
> fact I may nave started at the end of the list and only said previous,
> never next at all. Suppose I start at the beginning of the list [a, b,
> c, d, e] and say next, next, next, previous, previous. The cursor is
> between a and b. I believe that remove() will remove b. This is the
> element that the cursor "moved over" most recently. Is this correct?

The text in the tutorial is talking about the behavior of the
remove() method in interface Iterator, which doesn't have a
previous() method, just a next() method. It is ListIterator,
a subinterface of Iterator, that adds the previous() method.
JavaDoc for ListIterator says what you'd expect:

Removes from the list the last element that was returned by next or previous (optional operation). This call can only be
made once per call to next or previous. It can be made only if ListIterator.add has not been called after the last
call to next or previous.

Note that the semantics of remove() from JavaDoc of interface
ListIterator is incompatible with the tutorial text. If you
look at the semantics of remove() from JavaDoc for interface
Iterator, however, you find that the semantics are compatible,
as they should be. Here's the JavaDoc description for remove()
in interface Iterator:

Removes from the underlying collection the last element
returned by the iterator (optional operation).

bv