[multiple changes]

2001-10-15  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>

	* java/util/HashMap.java (HashEntry.clone): Removed.
	(HashMap(Map)): Use putAllInternal.
	(clone): Likewise.
	(putAllInternal): New method. Efficient counterpart to putAll which
	does not call put().
	* java/util/LinkedHashMap.java (rethread): Removed.
	(putAllInternal): New method. Clear "head" and "tail".
	(addEntry): New argument "callRemove". Don't call removeEldestEntry()
	if callRemove == false.

	* Makefile.am: Add new classes RandomAccess and LinkedHashMap.
	* Makefile.in: Rebuilt.

2001-10-15  Eric Blake  <ebb9@email.byu.edu>

	* java/util/Collection.java: Updated javadoc.
	* java/util/Comparator.java: Updated javadoc.
	* java/util/Enumeration.java: Updated javadoc.
	* java/util/Iterator.java: Updated javadoc.
	* java/util/List.java: Updated javadoc.
	* java/util/ListIterator.java: Updated javadoc.
	* java/util/Map.java: Updated javadoc.
	* java/util/RandomAccess.java: New file.
	* java/util/Set.java: Updated javadoc.
	* java/util/SortedMap.java: Updated javadoc.
	* java/util/SortedSet.java: Updated javadoc.

From-SVN: r46277

libjava/ChangeLog

+2001-10-15  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>
+
+	* java/util/HashMap.java (HashEntry.clone): Removed.
+	(HashMap(Map)): Use putAllInternal.
+	(clone): Likewise.
+	(putAllInternal): New method. Efficient counterpart to putAll which 
+	does not call put().	
+	* java/util/LinkedHashMap.java (rethread): Removed.
+	(putAllInternal): New method. Clear "head" and "tail".
+	(addEntry): New argument "callRemove". Don't call removeEldestEntry()
+	if callRemove == false. 
+
+	* Makefile.am: Add new classes RandomAccess and LinkedHashMap.
+	* Makefile.in: Rebuilt.
+
+2001-10-15  Eric Blake  <ebb9@email.byu.edu>
+
+	* java/util/Collection.java: Updated javadoc.
+	* java/util/Comparator.java: Updated javadoc.
+	* java/util/Enumeration.java: Updated javadoc.
+	* java/util/Iterator.java: Updated javadoc.
+	* java/util/List.java: Updated javadoc.
+	* java/util/ListIterator.java: Updated javadoc.
+	* java/util/Map.java: Updated javadoc.
+	* java/util/RandomAccess.java: New file.
+	* java/util/Set.java: Updated javadoc.
+	* java/util/SortedMap.java: Updated javadoc.
+	* java/util/SortedSet.java: Updated javadoc.
+
 2001-10-15  Tom Tromey  <tromey@redhat.com>
 
 	* java/lang/reflect/AccessibleObject.java (checkPermission):
@@ -190,6 +219,7 @@
 2001-10-03  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>
 
 	* resolve.cc (_Jv_PrepareClass): Fix typos in vtable layout.
+	* gij.cc (version): Use GCJVERSION.
 
 2001-10-02  Mark Wielaard  <mark@klomp.org>
 

libjava/Makefile.am

@@ -1089,6 +1089,7 @@ java/util/Hashtable.java \
 java/util/IdentityHashMap.java \
 java/util/Iterator.java	\
 java/util/LinkedList.java \
+java/util/LinkedHashMap.java \
 java/util/List.java \
 java/util/ListIterator.java \
 java/util/ListResourceBundle.java \
@@ -1102,6 +1103,7 @@ java/util/Properties.java \
 java/util/PropertyPermission.java \
 java/util/PropertyResourceBundle.java \
 java/util/Random.java \
+java/util/RandomAccess.java \
 java/util/ResourceBundle.java \
 java/util/Set.java \
 java/util/SimpleTimeZone.java \

libjava/java/util/Collection.java

 /* Collection.java -- Interface that represents a collection of objects
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,9 +25,6 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Maybe some more @see clauses would be helpful.
-
 package java.util;
 
 /**
@@ -57,9 +54,23 @@ package java.util;
  * and returns a collection containing the same elements (that is, creates a
  * copy of the argument using its own implementation).
  *
- * @see java.util.List
- * @see java.util.Set
- * @see java.util.AbstractCollection
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see List
+ * @see Set
+ * @see Map
+ * @see SortedSet
+ * @see SortedMap
+ * @see HashSet
+ * @see TreeSet
+ * @see ArrayList
+ * @see LinkedList
+ * @see Vector
+ * @see Collections
+ * @see Arrays
+ * @see AbstractCollection
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Collection
 {
@@ -67,12 +78,12 @@ public interface Collection
    * Add an element to this collection.
    *
    * @param o the object to add.
-   * @returns true if the collection was modified as a result of this action.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if the collection was modified as a result of this action.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the add operation.
-   * @exception ClassCastException if o cannot be added to this collection due
+   * @throws ClassCastException if o cannot be added to this collection due
    *   to its type.
-   * @exception IllegalArgumentException if o cannot be added to this
+   * @throws IllegalArgumentException if o cannot be added to this
    *   collection for some other reason.
    */
   boolean add(Object o);
@@ -81,12 +92,12 @@ public interface Collection
    * Add the contents of a given collection to this collection.
    *
    * @param c the collection to add.
-   * @returns true if the collection was modified as a result of this action.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if the collection was modified as a result of this action.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the addAll operation.
-   * @exception ClassCastException if some element of c cannot be added to this
+   * @throws ClassCastException if some element of c cannot be added to this
    *   collection due to its type.
-   * @exception IllegalArgumentException if some element of c cannot be added
+   * @throws IllegalArgumentException if some element of c cannot be added
    *   to this collection for some other reason.
    */
   boolean addAll(Collection c);
@@ -95,7 +106,7 @@ public interface Collection
    * Clear the collection, such that a subsequent call to isEmpty() would
    * return true.
    *
-   * @exception UnsupportedOperationException if this collection does not
+   * @throws UnsupportedOperationException if this collection does not
    *   support the clear operation.
    */
   void clear();
@@ -105,7 +116,7 @@ public interface Collection
    * elements.
    *
    * @param o the element to look for.
-   * @returns true if this collection contains at least one element e such that
+   * @return true if this collection contains at least one element e such that
    *   <code>o == null ? e == null : o.equals(e)</code>.
    */
   boolean contains(Object o);
@@ -114,7 +125,7 @@ public interface Collection
    * Test whether this collection contains every element in a given collection.
    *
    * @param c the collection to test for.
-   * @returns true if for every element o in c, contains(o) would return true.
+   * @return true if for every element o in c, contains(o) would return true.
    */
   boolean containsAll(Collection c);
 
@@ -132,7 +143,7 @@ public interface Collection
    * preserve the symmetry of the relation.
    *
    * @param o the object to compare to this collection.
-   * @returns true if the o is equal to this collection.
+   * @return true if the o is equal to this collection.
    */
   boolean equals(Object o);
 
@@ -148,21 +159,21 @@ public interface Collection
    * method renders it impossible to correctly implement both Set and List, as
    * the required implementations are mutually exclusive.
    *
-   * @returns a hash code for this collection.
+   * @return a hash code for this collection.
    */
   int hashCode();
 
   /**
    * Test whether this collection is empty, that is, if size() == 0.
    *
-   * @returns true if this collection contains no elements.
+   * @return true if this collection contains no elements.
    */
   boolean isEmpty();
 
   /**
    * Obtain an Iterator over this collection.
    *
-   * @returns an Iterator over the elements of this collection, in any order.
+   * @return an Iterator over the elements of this collection, in any order.
    */
   Iterator iterator();
 
@@ -172,9 +183,9 @@ public interface Collection
    *   : o.equals(e)</code>.
    *
    * @param o the object to remove.
-   * @returns true if the collection changed as a result of this call, that is,
+   * @return true if the collection changed as a result of this call, that is,
    *   if the collection contained at least one occurrence of o.
-   * @exception UnsupportedOperationException if this collection does not
+   * @throws UnsupportedOperationException if this collection does not
    *   support the remove operation.
    */
   boolean remove(Object o);
@@ -183,8 +194,8 @@ public interface Collection
    * Remove all elements of a given collection from this collection. That is,
    * remove every element e such that c.contains(e).
    *
-   * @returns true if this collection was modified as a result of this call.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if this collection was modified as a result of this call.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the removeAll operation.
    */
   boolean removeAll(Collection c);
@@ -193,8 +204,8 @@ public interface Collection
    * Remove all elements of this collection that are not contained in a given
    * collection. That is, remove every element e such that !c.contains(e).
    *
-   * @returns true if this collection was modified as a result of this call.
-   * @exception UnsupportedOperationException if this collection does not
+   * @return true if this collection was modified as a result of this call.
+   * @throws UnsupportedOperationException if this collection does not
    *   support the retainAll operation.
    */
   boolean retainAll(Collection c);
@@ -202,14 +213,14 @@ public interface Collection
   /**
    * Get the number of elements in this collection.
    *
-   * @returns the number of elements in the collection.
+   * @return the number of elements in the collection.
    */
   int size();
 
   /**
    * Copy the current contents of this collection into an array.
    *
-   * @returns an array of type Object[] and length equal to the size of this
+   * @return an array of type Object[] and length equal to the size of this
    *   collection, containing the elements currently in this collection, in
    *   any order.
    */
@@ -227,9 +238,9 @@ public interface Collection
    * if it is known that this collection does not contain any null elements.
    *
    * @param a the array to copy this collection into.
-   * @returns an array containing the elements currently in this collection, in
+   * @return an array containing the elements currently in this collection, in
    *   any order.
-   * @exception ArrayStoreException if the type of any element of the
+   * @throws ArrayStoreException if the type of any element of the
    *   collection is not a subtype of the element type of a.
    */
   Object[] toArray(Object[] a);

libjava/java/util/Comparator.java

@@ -29,36 +29,67 @@ package java.util;
 
 /**
  * Interface for objects that specify an ordering between objects. The ordering
- * can be <EM>total</EM>, such that two objects only compare equal if they are
- * equal by the equals method, or <EM>partial</EM> such that this is not
- * necessarily true. For example, a case-sensitive dictionary order comparison
- * of Strings is total, but if it is case-insensitive it is partial, because
- * "abc" and "ABC" compare as equal even though "abc".equals("ABC") returns
- * false.
+ * should be <em>total</em>, such that any two objects of the correct type
+ * can be compared, and the comparison is reflexive, anti-symmetric, and
+ * transitive.  It is also recommended that the comparator be <em>consistent
+ * with equals</em>, although this is not a strict requirement. A relation
+ * is consistent with equals if these two statements always have the same
+ * results (if no exceptions occur):<br>
+ * <code>compare((Object) e1, (Object) e2) == 0</code> and
+ * <code>e1.equals((Object) e2)</code><br>
+ * Comparators that violate consistency with equals may cause strange behavior
+ * in sorted lists and sets.  For example, a case-sensitive dictionary order
+ * comparison of Strings is consistent with equals, but if it is
+ * case-insensitive it is not, because "abc" and "ABC" compare as equal even
+ * though "abc".equals("ABC") returns false.
  * <P>
  * In general, Comparators should be Serializable, because when they are passed
  * to Serializable data structures such as SortedMap or SortedSet, the entire
  * data structure will only serialize correctly if the comparator is
  * Serializable.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Comparable
+ * @see TreeMap
+ * @see TreeSet
+ * @see SortedMap
+ * @see SortedSet
+ * @see Arrays#sort(Object[], Comparator)
+ * @see java.io.Serializable
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Comparator
 {
   /**
    * Return an integer that is negative, zero or positive depending on whether
    * the first argument is less than, equal to or greater than the second
-   * according to this ordering. This method should obey the following contract:
-   * <UL>
-   *   <LI>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</LI>
-   *   <LI>if compare(a, b) throws an exception, so does compare(b, a)</LI>
-   *   <LI>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)
-   *       &lt; 0</LI>
-   *   <LI>if a.equals(b) or both a and b are null, then compare(a, b) == 0.
-   *       The converse need not be true, but if it is, this Comparator
-   *       specifies a <EM>total</EM> ordering.</LI>
-   * </UL>
+   * according to this ordering. This method should obey the following
+   * contract:
+   * <ul>
+   *   <li>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</li>
+   *   <li>if compare(a, b) throws an exception, so does compare(b, a)</li>
+   *   <li>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)
+   *       &lt; 0</li>
+   *   <li>if compare(a, b) == 0 then compare(a, c) and compare(b, c) must
+   *       have the same sign</li
+   * </ul>
+   * To be consistent with equals, the following additional constraint is
+   * in place:
+   * <ul>
+   *   <li>if a.equals(b) or both a and b are null, then
+   *       compare(a, b) == 0.</li>
+   * </ul><p>
    *
+   * Although it is permissible for a comparator to provide an order
+   * inconsistent with equals, that should be documented.
+   *
+   * @param o1 the first object
+   * @param o2 the second object
+   * @return the comparison
    * @throws ClassCastException if the elements are not of types that can be
-   *   compared by this ordering.
+   *         compared by this ordering.
    */
   int compare(Object o1, Object o2);
 
@@ -66,8 +97,12 @@ public interface Comparator
    * Return true if the object is equal to this object.  To be
    * considered equal, the argument object must satisfy the constraints
    * of <code>Object.equals()</code>, be a Comparator, and impose the
-   * same ordering as this Comparator.
+   * same ordering as this Comparator. The default implementation
+   * inherited from Object is usually adequate.
+   *
    * @param obj The object
+   * @return true if it is a Comparator that imposes the same order
+   * @see Object#equals(Object)
    */
   boolean equals(Object obj);
 }

libjava/java/util/Enumeration.java

@@ -42,7 +42,12 @@ package java.util;
  * be obtained by the enumeration method in class Collections.
  *
  * @author Warren Levy <warrenl@cygnus.com>
- * @date August 25, 1998.
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Iterator
+ * @see Hashtable
+ * @see Vector
+ * @since 1.0
+ * @status updated to 1.4
  */
 public interface Enumeration
 {
@@ -50,8 +55,8 @@ public interface Enumeration
    * Tests whether there are elements remaining in the enumeration.
    *
    * @return true if there is at least one more element in the enumeration,
-   *   that is, if the next call to nextElement will not throw a
-   *   NoSuchElementException.
+   *         that is, if the next call to nextElement will not throw a
+   *         NoSuchElementException.
    */
   boolean hasMoreElements();
 
@@ -59,7 +64,7 @@ public interface Enumeration
    * Obtain the next element in the enumeration.
    *
    * @return the next element in the enumeration
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
-  Object nextElement() throws NoSuchElementException;
+  Object nextElement();
 }

libjava/java/util/Iterator.java

 /* Iterator.java -- Interface for iterating over collections
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -28,20 +28,28 @@ executable file might be covered by the GNU General Public License. */
 package java.util;
 
 /**
- * An object which iterates over a collection. An Iterator is used to return the
- * items once only, in sequence, by successive calls to the next method. It is
- * also possible to remove elements from the underlying collection by using the
- * optional remove method. Iterator is intended as a replacement for the
- * Enumeration interface of previous versions of Java, which did not have the
- * remove method and had less conveniently named methods.
+ * An object which iterates over a collection. An Iterator is used to return
+ * the items once only, in sequence, by successive calls to the next method.
+ * It is also possible to remove elements from the underlying collection by
+ * using the optional remove method. Iterator is intended as a replacement
+ * for the Enumeration interface of previous versions of Java, which did not
+ * have the remove method and had less conveniently named methods.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see ListIterator
+ * @see Enumeration
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Iterator
 {
   /**
-   * Tests whether there are elements remaining in the collection.
+   * Tests whether there are elements remaining in the collection. In other
+   * words, calling <code>next()</code> will not throw an exception.
    *
-   * @return true if there is at least one more element in the collection,
-   *   that is, if the next call to next will not throw NoSuchElementException.
+   * @return true if there is at least one more element in the collection
    */
   boolean hasNext();
 
@@ -49,20 +57,20 @@ public interface Iterator
    * Obtain the next element in the collection.
    *
    * @return the next element in the collection
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
   Object next();
 
   /**
-   * Remove from the underlying collection the last element returned by next.
-   * This method can be called only once after each call to next. It does not
-   * affect what will be returned by subsequent calls to next. This operation is
-   * optional, it may throw an UnsupportedOperationException.
+   * Remove from the underlying collection the last element returned by next
+   * (optional operation). This method can be called only once after each
+   * call to <code>next()</code>. It does not affect what will be returned
+   * by subsequent calls to next.
    *
-   * @exception IllegalStateException if next has not yet been called or remove
-   *   has already been called since the last call to next.
-   * @exception UnsupportedOperationException if this Iterator does not support
-   *   the remove operation.
+   * @throws IllegalStateException if next has not yet been called or remove
+   *         has already been called since the last call to next.
+   * @throws UnsupportedOperationException if this Iterator does not support
+   *         the remove operation.
    */
   void remove();
 }

libjava/java/util/ListIterator.java

 /* ListIterator.java -- Extended Iterator for iterating over ordered lists
-   Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -32,116 +32,128 @@ package java.util;
  * elements may be accessed in forward or reverse order, elements may be
  * replaced as well as removed, and new elements may be inserted, during the
  * traversal of the list.
+ * <p>
+ *
+ * A list with n elements provides n+1 iterator positions (the front, the end,
+ * or between two elements). Note that <code>remove</code> and <code>set</code>
+ * operate on the last element returned, whether it was by <code>next</code>
+ * or <code>previous</code>.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see List
+ * @see Iterator
+ * @see Enumeration
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface ListIterator extends Iterator
 {
   /**
    * Tests whether there are elements remaining in the list in the forward
-   * direction.
+   * direction. In other words, next() will not fail with a
+   * NoSuchElementException.
    *
-   * @return true if there is at least one more element in the list in the
-   *   forward direction, that is, if the next call to next will not throw
-   *   NoSuchElementException.
+   * @return true if the list continues in the forward direction
    */
   boolean hasNext();
 
   /**
    * Tests whether there are elements remaining in the list in the reverse
-   * direction.
+   * direction. In other words, previous() will not fail with a
+   * NoSuchElementException.
    *
-   * @return true if there is at least one more element in the list in the
-   *   reverse direction, that is, if the next call to previous will not throw
-   *   NoSuchElementException.
+   * @return true if the list continues in the reverse direction
    */
   boolean hasPrevious();
 
   /**
    * Obtain the next element in the list in the forward direction. Repeated
-   * calls to next may be used to iterate over the entire list, or calls to next
-   * and previous may be used together to go forwards and backwards. Alternating
-   * calls to next and previous will return the same element.
+   * calls to next may be used to iterate over the entire list, or calls to
+   * next and previous may be used together to go forwards and backwards.
+   * Alternating calls to next and previous will return the same element.
    *
    * @return the next element in the list in the forward direction
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
   Object next();
 
   /**
    * Obtain the next element in the list in the reverse direction. Repeated
-   * calls to previous may be used to iterate backwards over the entire list, or
-   * calls to next and previous may be used together to go forwards and
+   * calls to previous may be used to iterate backwards over the entire list,
+   * or calls to next and previous may be used together to go forwards and
    * backwards. Alternating calls to next and previous will return the same
    * element.
    *
    * @return the next element in the list in the reverse direction
-   * @exception NoSuchElementException if there are no more elements
+   * @throws NoSuchElementException if there are no more elements
    */
   Object previous();
 
   /**
    * Find the index of the element that would be returned by a call to next.
+   * If hasNext() returns false, this returns the list size.
    *
-   * @return the index of the element that would be returned by a call to next,
-   *   or list.size() if the iterator is at the end of the list.
+   * @return the index of the element that would be returned by next()
    */
   int nextIndex();
 
   /**
-   * Find the index of the element that would be returned by a call to previous.
+   * Find the index of the element that would be returned by a call to
+   * previous. If hasPrevious() returns false, this returns -1.
    *
-   * @return the index of the element that would be returned by a call to
-   *   previous, or -1 if the iterator is at the beginning of the list.
+   * @return the index of the element that would be returned by previous()
    */
   int previousIndex();
 
   /**
-   * Insert an element into the list at the current position of the iterator.
-   * The element is inserted in between the element that would be returned by
-   * previous and the element that would be returned by next. After the
-   * insertion, a subsequent call to next is unaffected, but a call to
-   * previous returns the item that was added. This operation is optional, it
-   * may throw an UnsupportedOperationException.
+   * Insert an element into the list at the current position of the iterator
+   * (optional operation). The element is inserted in between the element that
+   * would be returned by previous and the element that would be returned by
+   * next. After the insertion, a subsequent call to next is unaffected, but
+   * a call to previous returns the item that was added. The values returned
+   * by nextIndex() and previousIndex() are incremented.
    *
    * @param o the object to insert into the list
-   * @exception ClassCastException the object is of a type which cannot be added
-   *   to this list
-   * @exception IllegalArgumentException some other aspect of the object stops
-   *   it being added to this list
-   * @exception UnsupportedOperationException if this ListIterator does not
-   *   support the add operation
+   * @throws ClassCastException the object is of a type which cannot be added
+   *         to this list
+   * @throws IllegalArgumentException some other aspect of the object stops
+   *         it being added to this list
+   * @throws UnsupportedOperationException if this ListIterator does not
+   *         support the add operation
    */
   void add(Object o);
 
   /**
    * Remove from the list the element last returned by a call to next or
-   * previous. This method may only be called if neither add nor remove have
-   * been called since the last call to next or previous. This operation is
-   * optional, it may throw an UnsupportedOperationException.
+   * previous (optional operation). This method may only be called if neither
+   * add nor remove have been called since the last call to next or previous.
    *
-   * @exception IllegalStateException if neither next or previous have been
-   *   called, or if add or remove has been called since the last call to next
-   *   or previous.
-   * @exception UnsupportedOperationException if this ListIterator does not
-   *   support the remove operation.
+   * @throws IllegalStateException if neither next or previous have been
+   *         called, or if add or remove has been called since the last call
+   *         to next or previous
+   * @throws UnsupportedOperationException if this ListIterator does not
+   *         support the remove operation
    */
   void remove();
 
   /**
    * Replace the element last returned by a call to next or previous with a
-   * given object. This method may only be called if neither add nor remove have
-   * been called since the last call to next or previous. This operation is
-   * optional, it may throw an UnsupportedOperationException.
+   * given object (optional operation). This method may only be called if
+   * neither add nor remove have been called since the last call to next or
+   * previous.
    *
    * @param o the object to replace the element with
-   * @exception ClassCastException the object is of a type which cannot be added
-   *   to this list
-   * @exception IllegalArgumentException some other aspect of the object stops
-   *   it being added to this list
-   * @exception IllegalStateException if neither next or previous have been
-   *   called, or if add or remove has been called since the last call to next
-   *   or previous.
-   * @exception UnsupportedOperationException if this ListIterator does not
-   *   support the set operation.
+   * @throws ClassCastException the object is of a type which cannot be added
+   *         to this list
+   * @throws IllegalArgumentException some other aspect of the object stops
+   *         it being added to this list
+   * @throws IllegalStateException if neither next or previous have been
+   *         called, or if add or remove has been called since the last call
+   *         to next or previous
+   * @throws UnsupportedOperationException if this ListIterator does not
+   *         support the set operation
    */
   void set(Object o);
 }

libjava/java/util/RandomAccess.java

+/* RandomAccess.java -- A tagging interface that lists can use to tailor
+   operations to the correct algorithm
+   Copyright (C) 2001 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+As a special exception, if you link this library with other files to
+produce an executable, this library does not by itself cause the
+resulting executable to be covered by the GNU General Public License.
+This exception does not however invalidate any other reasons why the
+executable file might be covered by the GNU General Public License. */
+
+
+package java.util;
+
+/**
+ * Marker interface used to inform <code>List</code> implementations that
+ * they support fast (usually constant time) random access. This allows
+ * generic list algorithms to tailor their behavior based on the list
+ * type.
+ * <p>
+ *
+ * For example, some sorts are n*log(n) on an array, but decay to quadratic
+ * time on a linked list.  As a rule of thumb, this interface should be
+ * used is this loop:<br>
+ * <code>for (int i = 0, n = list.size(); i &lt; n; i++) list.get(i);</code>
+ * <br>runs faster than this loop:<br>
+ * <code>for (Iterator i = list.iterator(); i.hasNext(); ) i.next();</code>
+ *
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see List
+ * @since 1.4
+ * @status updated to 1.4
+ */
+public interface RandomAccess
+{
+  // Tagging interface only.
+}

libjava/java/util/Set.java

 /* Set.java -- A collection that prohibits duplicates
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,25 +25,208 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * A collection that contains no duplicates. In other words, for two set
+ * elements e1 and e2, <code>e1.equals(e2)</code> returns false. There
+ * are additional stipulations on <code>add</code>, <code>equals</code>
+ * and <code>hashCode</code>, as well as the requirements that constructors
+ * do not permit duplicate elements. The Set interface is incompatible with
+ * List; you cannot implement both simultaneously.
+ * <p>
+ *
+ * Note: Be careful about using mutable objects in sets.  In particular,
+ * if a mutable object changes to become equal to another set element, you
+ * have violated the contract.  As a special case of this, a Set is not
+ * allowed to be an element of itself, without risking undefined behavior.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Collection
+ * @see List
+ * @see SortedSet
+ * @see HashSet
+ * @see TreeSet
+ * @see LinkedHashSet
+ * @see AbstractSet
+ * @see Collections#singleton(Object)
+ * @see Collections#EMPTY_SET
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface Set extends Collection
 {
+  /**
+   * Adds the specified element to the set if it is not already present
+   * (optional operation). In particular, the comparison algorithm is
+   * <code>o == null ? e == null : o.equals(e)</code>. Sets need not permit
+   * all values, and may document what exceptions will be thrown if
+   * a value is not permitted.
+   *
+   * @param o the object to add
+   * @return true if the object was not previously in the set
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws ClassCastException if the class of o prevents it from being added
+   * @throws IllegalArgumentException if some aspect of o prevents it from
+   *         being added
+   * @throws NullPointerException if null is not permitted in this set
+   */
   boolean add(Object o);
+
+  /**
+   * Adds all of the elements of the given collection to this set (optional
+   * operation). If the argument is also a Set, this returns the mathematical
+   * <i>union</i> of the two. The behavior is unspecified if the set is
+   * modified while this is taking place.
+   *
+   * @param c the collection to add
+   * @return true if the set changed as a result
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws ClassCastException if the class of an element prevents it from
+   *         being added
+   * @throws IllegalArgumentException if something about an element prevents
+   *         it from being added
+   * @throws NullPointerException if null is not permitted in this set, or
+   *         if the argument c is null
+   * @see #add(Object)
+   */
   boolean addAll(Collection c);
+
+  /**
+   * Removes all elements from this set (optional operation). This set will
+   * be empty afterwords, unless an exception occurs.
+   *
+   * @throws UnsupportedOperationException if this operation is not allowed
+   */
   void clear();
+
+  /**
+   * Returns true if the set contains the specified element. In other words,
+   * this looks for <code>o == null ? e == null : o.equals(e)</code>.
+   *
+   * @param o the object to look for
+   * @return true if it is found in the set
+   */
   boolean contains(Object o);
+
+  /**
+   * Returns true if this set contains all elements in the specified
+   * collection. If the argument is also a set, this is the <i>subset</i>
+   * relationship.
+   *
+   * @param c the collection to check membership in
+   * @return true if all elements in this set are in c
+   * @throws NullPointerException if c is null
+   * @see #contains(Object)
+   */
   boolean containsAll(Collection c);
+
+  /**
+   * Compares the specified object to this for equality. For sets, the object
+   * must be a set, the two must have the same size, and every element in
+   * one must be in the other.
+   *
+   * @param o the object to compare to
+   * @return true if it is an equal set
+   */
   boolean equals(Object o);
+
+  /**
+   * Returns the hash code for this set. In order to satisfy the contract of
+   * equals, this is the sum of the hashcode of all elements in the set.
+   *
+   * @return the sum of the hashcodes of all set elements
+   */
   int hashCode();
+
+  /**
+   * Returns true if the set contains no elements.
+   *
+   * @return true if the set is empty
+   */
   boolean isEmpty();
+
+  /**
+   * Returns an iterator over the set.  The iterator has no specific order,
+   * unless further specified.
+   *
+   * @return a set iterator
+   */
   Iterator iterator();
+
+  /**
+   * Removes the specified element from this set (optional operation). If
+   * an element e exists, <code>o == null ? e == null : o.equals(e)</code>,
+   * it is removed from the set.
+   *
+   * @param o the object to remove
+   * @return true if the set changed (an object was removed)
+   * @throws UnsupportedOperationException if this operation is not allowed
+   */
   boolean remove(Object o);
+
+  /**
+   * Removes from this set all elements contained in the specified collection
+   * (optional operation). If the argument is a set, this returns the
+   * <i>asymmetric set difference</i> of the two sets.
+   *
+   * @param c the collection to remove from this set
+   * @return true if this set changed as a result
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws NullPointerException if c is null
+   * @see #remove(Object)
+   */
   boolean removeAll(Collection c);
+
+  /**
+   * Retains only the elements in this set that are also in the specified
+   * collection (optional operation). If the argument is also a set, this
+   * performs the <i>intersection</i> of the two sets.
+   *
+   * @param c the collection to keep
+   * @return true if this set was modified
+   * @throws UnsupportedOperationException if this operation is not allowed
+   * @throws NullPointerException if c is null
+   * @see #remove(Object)
+   */
   boolean retainAll(Collection c);
+
+  /**
+   * Returns the number of elements in the set. If there are more
+   * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE. This is
+   * the <i>cardinality</i> of the set.
+   *
+   * @return the number of elements
+   */
   int size();
+
+  /**
+   * Returns an array containing the elements of this set. If the set
+   * makes a guarantee about iteration order, the array has the same
+   * order. The array is distinct from the set; modifying one does not
+   * affect the other.
+   *
+   * @return an array of this set's elements
+   * @see #toArray(Object[])
+   */
   Object[] toArray();
+
+  /**
+   * Returns an array containing the elements of this set, of the same runtime
+   * type of the argument. If the given set is large enough, it is reused,
+   * and null is inserted in the first unused slot. Otherwise, reflection
+   * is used to build a new array. If the set makes a guarantee about iteration
+   * order, the array has the same order. The array is distinct from the set;
+   * modifying one does not affect the other.
+   *
+   * @param a the array to determine the return type; if it is big enough
+   *        it is used and returned
+   * @return an array holding the elements of the set
+   * @throws ArrayStoreException if the runtime type of a is not a supertype
+   *         of all elements in the set
+   * @throws NullPointerException if a is null
+   * @see #toArray()
+   */
+  Object[] toArray(Object[] a);
 }

libjava/java/util/SortedMap.java

 /* SortedMap.java -- A map that makes guarantees about the order of its keys
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -25,17 +25,135 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * A map which guarantees its key's iteration order. The entries in the
+ * map are related by the <i>natural ordering</i> of the keys if they
+ * are Comparable, or by the provided Comparator.  Additional operations
+ * take advantage of the sorted nature of the map.
+ * <p>
+ *
+ * All keys entered in the map must be mutually comparable; in other words,
+ * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
+ * must not throw a ClassCastException. The ordering must be <i>consistent
+ * with equals</i> (see {@link Comparator} for this definition), if the
+ * map is to obey the general contract of the Map interface.  If not,
+ * the results are well-defined, but probably not what you wanted.
+ * <p>
+ *
+ * It is recommended that all implementing classes provide four constructors:
+ * 1) one that takes no arguments and builds an empty map sorted by natural
+ * order of the keys; 2) one that takes a Comparator for the sorting order;
+ * 3) one that takes a Map and sorts according to the natural order of its
+ * keys; and 4) one that takes a SortedMap and sorts by the same comparator.
+ * Unfortunately, the Java language does not provide a way to enforce this.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Map
+ * @see TreeMap
+ * @see SortedSet
+ * @see Comparable
+ * @see Comparator
+ * @see Collection
+ * @see ClassCastException
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface SortedMap extends Map
 {
+  /**
+   * Returns the comparator used in sorting this map, or null if it is
+   * the keys' natural ordering.
+   *
+   * @return the sorting comparator
+   */
   Comparator comparator();
+
+  /**
+   * Returns the first (lowest sorted) key in the map.
+   *
+   * @return the first key
+   */
   Object firstKey();
+
+  /**
+   * Returns a view of the portion of the map strictly less than toKey. The
+   * view is backed by this map, so changes in one show up in the other.
+   * The submap supports all optional operations of the original.
+   * <p>
+   *
+   * The returned map throws an IllegalArgumentException any time a key is
+   * used which is out of the range of toKey. Note that the endpoint is not
+   * included; if you want the endpoint, pass the successor object in to
+   * toKey.  For example, for Strings, you can request
+   * <code>headMap(limit + "\0")</code>.
+   *
+   * @param toKey the exclusive upper range of the submap
+   * @return the submap
+   * @throws ClassCastException if toKey is not comparable to the map contents
+   * @throws IllegalArgumentException if this is a subMap, and toKey is out
+   *         of range
+   * @throws NullPointerException if toKey is null but the map does not allow
+   *         null keys
+   */
   SortedMap headMap(Object toKey);
+
+  /**
+   * Returns the last (highest sorted) key in the map.
+   *
+   * @return the last key
+   */
   Object lastKey();
+
+  /**
+   * Returns a view of the portion of the map greater than or equal to
+   * fromKey, and strictly less than toKey. The view is backed by this map,
+   * so changes in one show up in the other. The submap supports all
+   * optional operations of the original.
+   * <p>
+   *
+   * The returned map throws an IllegalArgumentException any time a key is
+   * used which is out of the range of fromKey and toKey. Note that the
+   * lower endpoint is included, but the upper is not; if you want to
+   * change the inclusion or exclusion of an endpoint, pass the successor
+   * object in instead.  For example, for Strings, you can request
+   * <code>subMap(lowlimit + "\0", highlimit + "\0")</code> to reverse
+   * the inclusiveness of both endpoints.
+   *
+   * @param fromKey the inclusive lower range of the submap
+   * @param toKey the exclusive upper range of the submap
+   * @return the submap
+   * @throws ClassCastException if fromKey or toKey is not comparable to
+   *         the map contents
+   * @throws IllegalArgumentException if this is a subMap, and fromKey or
+   *         toKey is out of range
+   * @throws NullPointerException if fromKey or toKey is null but the map
+   *         does not allow null keys
+   */
   SortedMap subMap(Object fromKey, Object toKey);
+
+  /**
+   * Returns a view of the portion of the map greater than or equal to
+   * fromKey. The view is backed by this map, so changes in one show up
+   * in the other. The submap supports all optional operations of the original.
+   * <p>
+   *
+   * The returned map throws an IllegalArgumentException any time a key is
+   * used which is out of the range of fromKey. Note that the endpoint is
+   * included; if you do not want the endpoint, pass the successor object in
+   * to fromKey.  For example, for Strings, you can request
+   * <code>tailMap(limit + "\0")</code>.
+   *
+   * @param fromKey the inclusive lower range of the submap
+   * @return the submap
+   * @throws ClassCastException if fromKey is not comparable to the map
+   *         contents
+   * @throws IllegalArgumentException if this is a subMap, and fromKey is out
+   *         of range
+   * @throws NullPointerException if fromKey is null but the map does not allow
+   *         null keys
+   */
   SortedMap tailMap(Object fromKey);
 }

libjava/java/util/SortedSet.java

-/* SortedSet.java -- A set that makes guarantees about the order of its 
+/* SortedSet.java -- A set that makes guarantees about the order of its
    elements
-   Copyright (C) 1998 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -26,17 +26,137 @@ This exception does not however invalidate any other reasons why the
 executable file might be covered by the GNU General Public License. */
 
 
-// TO DO:
-// ~ Doc comments for everything.
-
 package java.util;
 
+/**
+ * A set which guarantees its iteration order. The elements in the set
+ * are related by the <i>natural ordering</i> if they are Comparable, or
+ * by the provided Comparator.  Additional operations take advantage of
+ * the sorted nature of the set.
+ * <p>
+ *
+ * All elements entered in the set must be mutually comparable; in other words,
+ * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
+ * must not throw a ClassCastException. The ordering must be <i>consistent
+ * with equals</i> (see {@link Comparator} for this definition), if the
+ * map is to obey the general contract of the Set interface.  If not,
+ * the results are well-defined, but probably not what you wanted.
+ * <p>
+ *
+ * It is recommended that all implementing classes provide four constructors:
+ * 1) one that takes no arguments and builds an empty set sorted by natural
+ * order of the elements; 2) one that takes a Comparator for the sorting order;
+ * 3) one that takes a Set and sorts according to the natural order of its
+ * elements; and 4) one that takes a SortedSet and sorts by the same
+ * comparator. Unfortunately, the Java language does not provide a way to
+ * enforce this.
+ *
+ * @author Original author unknown
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see Set
+ * @see TreeSet
+ * @see SortedMap
+ * @see Collection
+ * @see Comparable
+ * @see Comparator
+ * @see ClassCastException
+ * @since 1.2
+ * @status updated to 1.4
+ */
 public interface SortedSet extends Set
 {
+  /**
+   * Returns the comparator used in sorting this set, or null if it is
+   * the elements' natural ordering.
+   *
+   * @return the sorting comparator
+   */
   Comparator comparator();
+
+  /**
+   * Returns the first (lowest sorted) element in the map.
+   *
+   * @return the first element
+   */
   Object first();
+
+  /**
+   * Returns a view of the portion of the set strictly less than toElement. The
+   * view is backed by this set, so changes in one show up in the other.
+   * The subset supports all optional operations of the original.
+   * <p>
+   *
+   * The returned set throws an IllegalArgumentException any time an element is
+   * used which is out of the range of toElement. Note that the endpoint is not
+   * included; if you want the endpoint, pass the successor object in to
+   * toElement.  For example, for Strings, you can request
+   * <code>headSet(limit + "\0")</code>.
+   *
+   * @param toElement the exclusive upper range of the subset
+   * @return the subset
+   * @throws ClassCastException if toElement is not comparable to the set
+   *         contents
+   * @throws IllegalArgumentException if this is a subSet, and toElement is out
+   *         of range
+   * @throws NullPointerException if toElement is null but the map does not
+   *         allow null elements
+   */
   SortedSet headSet(Object toElement);
+
+  /**
+   * Returns the last (highest sorted) element in the map.
+   *
+   * @return the last element
+   */
   Object last();
+
+  /**
+   * Returns a view of the portion of the set greater than or equal to
+   * fromElement, and strictly less than toElement. The view is backed by
+   * this set, so changes in one show up in the other. The subset supports all
+   * optional operations of the original.
+   * <p>
+   *
+   * The returned set throws an IllegalArgumentException any time an element is
+   * used which is out of the range of fromElement and toElement. Note that the
+   * lower endpoint is included, but the upper is not; if you want to
+   * change the inclusion or exclusion of an endpoint, pass the successor
+   * object in instead.  For example, for Strings, you can request
+   * <code>subSet(lowlimit + "\0", highlimit + "\0")</code> to reverse
+   * the inclusiveness of both endpoints.
+   *
+   * @param fromElement the inclusive lower range of the subset
+   * @param toElement the exclusive upper range of the subset
+   * @return the subset
+   * @throws ClassCastException if fromElement or toElement is not comparable
+   *         to the set contents
+   * @throws IllegalArgumentException if this is a subSet, and fromElement or
+   *         toElement is out of range
+   * @throws NullPointerException if fromElement or toElement is null but the
+   *         set does not allow null elements
+   */
   SortedSet subSet(Object fromElement, Object toElement);
+
+  /**
+   * Returns a view of the portion of the set greater than or equal to
+   * fromElement. The view is backed by this set, so changes in one show up
+   * in the other. The subset supports all optional operations of the original.
+   * <p>
+   *
+   * The returned set throws an IllegalArgumentException any time an element is
+   * used which is out of the range of fromElement. Note that the endpoint is
+   * included; if you do not want the endpoint, pass the successor object in
+   * to fromElement.  For example, for Strings, you can request
+   * <code>tailSet(limit + "\0")</code>.
+   *
+   * @param fromElement the inclusive lower range of the subset
+   * @return the subset
+   * @throws ClassCastException if fromElement is not comparable to the set
+   *         contents
+   * @throws IllegalArgumentException if this is a subSet, and fromElement is
+   *         out of range
+   * @throws NullPointerException if fromElement is null but the set does not
+   *         allow null elements
+   */
   SortedSet tailSet(Object fromElement);
 }