Name: jl125535 Date: 03/11/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)


FULL OPERATING SYSTEM VERSION :
n/a



A DESCRIPTION OF THE PROBLEM :
We should revisit our use of the term "index" in the
java.util.ListIterator javadoc (at
http://java.sun.com/j2se/1.4/docs/api/java/util/ListIterator.html).
Currently, the diagram in the class description implies that
"index" refers to positions between list elements. However, this
definition conflicts with the nextIndex() and previousIndex()
methods, which imply that "index" refers to the positions of the
elements themselves.

The original submission (below) describes the resulting confusion.
The submitter suggests the term "cursor" for the positions between
list elements.

--- Original Submission ---

In the API description of ListIterator, there is a
sentence:
"In a list of length n, there are n+1 valid index values,
from 0 to n, inclusive."

That is wrong. It should read:
"In a list of length n, there are n valid index values,
from 0 to n-1, inclusive."

The line labeled "Index:" in the diagram incorrectly shows
"n+1". n+1 is a cursor position, which is not the same as
an index.

For example, in a list of length 20, the indexes are 0
through 19. According to the (incorrect) API, the indexes
would be 0 through 20. There is no method in the
ListIterator class that will ever return an index of 20.
The method nextIndex() says:
"Return: the index of the element that would be returned
by a subsequent call to next, or list size if list iterator
is at end of list". In other words, the 20 that would be
returned by this method is the list size, not an index.

(Review ID: 143893)
======================================================================