Commit 41878ce2 by Bryce McKinlay

[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
parent ffb5e2e2
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> 2001-10-15 Tom Tromey <tromey@redhat.com>
* java/lang/reflect/AccessibleObject.java (checkPermission): * java/lang/reflect/AccessibleObject.java (checkPermission):
...@@ -190,6 +219,7 @@ ...@@ -190,6 +219,7 @@
2001-10-03 Bryce McKinlay <bryce@waitaki.otago.ac.nz> 2001-10-03 Bryce McKinlay <bryce@waitaki.otago.ac.nz>
* resolve.cc (_Jv_PrepareClass): Fix typos in vtable layout. * resolve.cc (_Jv_PrepareClass): Fix typos in vtable layout.
* gij.cc (version): Use GCJVERSION.
2001-10-02 Mark Wielaard <mark@klomp.org> 2001-10-02 Mark Wielaard <mark@klomp.org>
......
...@@ -1089,6 +1089,7 @@ java/util/Hashtable.java \ ...@@ -1089,6 +1089,7 @@ java/util/Hashtable.java \
java/util/IdentityHashMap.java \ java/util/IdentityHashMap.java \
java/util/Iterator.java \ java/util/Iterator.java \
java/util/LinkedList.java \ java/util/LinkedList.java \
java/util/LinkedHashMap.java \
java/util/List.java \ java/util/List.java \
java/util/ListIterator.java \ java/util/ListIterator.java \
java/util/ListResourceBundle.java \ java/util/ListResourceBundle.java \
...@@ -1102,6 +1103,7 @@ java/util/Properties.java \ ...@@ -1102,6 +1103,7 @@ java/util/Properties.java \
java/util/PropertyPermission.java \ java/util/PropertyPermission.java \
java/util/PropertyResourceBundle.java \ java/util/PropertyResourceBundle.java \
java/util/Random.java \ java/util/Random.java \
java/util/RandomAccess.java \
java/util/ResourceBundle.java \ java/util/ResourceBundle.java \
java/util/Set.java \ java/util/Set.java \
java/util/SimpleTimeZone.java \ java/util/SimpleTimeZone.java \
......
/* Collection.java -- Interface that represents a collection of objects /* 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. This file is part of GNU Classpath.
...@@ -25,9 +25,6 @@ This exception does not however invalidate any other reasons why the ...@@ -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. */ executable file might be covered by the GNU General Public License. */
// TO DO:
// ~ Maybe some more @see clauses would be helpful.
package java.util; package java.util;
/** /**
...@@ -57,9 +54,23 @@ package java.util; ...@@ -57,9 +54,23 @@ package java.util;
* and returns a collection containing the same elements (that is, creates a * and returns a collection containing the same elements (that is, creates a
* copy of the argument using its own implementation). * copy of the argument using its own implementation).
* *
* @see java.util.List * @author Original author unknown
* @see java.util.Set * @author Eric Blake <ebb9@email.byu.edu>
* @see java.util.AbstractCollection * @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 public interface Collection
{ {
...@@ -67,12 +78,12 @@ public interface Collection ...@@ -67,12 +78,12 @@ public interface Collection
* Add an element to this collection. * Add an element to this collection.
* *
* @param o the object to add. * @param o the object to add.
* @returns true if the collection was modified as a result of this action. * @return true if the collection was modified as a result of this action.
* @exception UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the add operation. * 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. * 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. * collection for some other reason.
*/ */
boolean add(Object o); boolean add(Object o);
...@@ -81,12 +92,12 @@ public interface Collection ...@@ -81,12 +92,12 @@ public interface Collection
* Add the contents of a given collection to this collection. * Add the contents of a given collection to this collection.
* *
* @param c the collection to add. * @param c the collection to add.
* @returns true if the collection was modified as a result of this action. * @return true if the collection was modified as a result of this action.
* @exception UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the addAll operation. * 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. * 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. * to this collection for some other reason.
*/ */
boolean addAll(Collection c); boolean addAll(Collection c);
...@@ -95,7 +106,7 @@ public interface Collection ...@@ -95,7 +106,7 @@ public interface Collection
* Clear the collection, such that a subsequent call to isEmpty() would * Clear the collection, such that a subsequent call to isEmpty() would
* return true. * return true.
* *
* @exception UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the clear operation. * support the clear operation.
*/ */
void clear(); void clear();
...@@ -105,7 +116,7 @@ public interface Collection ...@@ -105,7 +116,7 @@ public interface Collection
* elements. * elements.
* *
* @param o the element to look for. * @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>. * <code>o == null ? e == null : o.equals(e)</code>.
*/ */
boolean contains(Object o); boolean contains(Object o);
...@@ -114,7 +125,7 @@ public interface Collection ...@@ -114,7 +125,7 @@ public interface Collection
* Test whether this collection contains every element in a given collection. * Test whether this collection contains every element in a given collection.
* *
* @param c the collection to test for. * @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); boolean containsAll(Collection c);
...@@ -132,7 +143,7 @@ public interface Collection ...@@ -132,7 +143,7 @@ public interface Collection
* preserve the symmetry of the relation. * preserve the symmetry of the relation.
* *
* @param o the object to compare to this collection. * @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); boolean equals(Object o);
...@@ -148,21 +159,21 @@ public interface Collection ...@@ -148,21 +159,21 @@ public interface Collection
* method renders it impossible to correctly implement both Set and List, as * method renders it impossible to correctly implement both Set and List, as
* the required implementations are mutually exclusive. * the required implementations are mutually exclusive.
* *
* @returns a hash code for this collection. * @return a hash code for this collection.
*/ */
int hashCode(); int hashCode();
/** /**
* Test whether this collection is empty, that is, if size() == 0. * 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(); boolean isEmpty();
/** /**
* Obtain an Iterator over this collection. * 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(); Iterator iterator();
...@@ -172,9 +183,9 @@ public interface Collection ...@@ -172,9 +183,9 @@ public interface Collection
* : o.equals(e)</code>. * : o.equals(e)</code>.
* *
* @param o the object to remove. * @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. * 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. * support the remove operation.
*/ */
boolean remove(Object o); boolean remove(Object o);
...@@ -183,8 +194,8 @@ public interface Collection ...@@ -183,8 +194,8 @@ public interface Collection
* Remove all elements of a given collection from this collection. That is, * Remove all elements of a given collection from this collection. That is,
* remove every element e such that c.contains(e). * remove every element e such that c.contains(e).
* *
* @returns true if this collection was modified as a result of this call. * @return true if this collection was modified as a result of this call.
* @exception UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the removeAll operation. * support the removeAll operation.
*/ */
boolean removeAll(Collection c); boolean removeAll(Collection c);
...@@ -193,8 +204,8 @@ public interface Collection ...@@ -193,8 +204,8 @@ public interface Collection
* Remove all elements of this collection that are not contained in a given * 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). * 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. * @return true if this collection was modified as a result of this call.
* @exception UnsupportedOperationException if this collection does not * @throws UnsupportedOperationException if this collection does not
* support the retainAll operation. * support the retainAll operation.
*/ */
boolean retainAll(Collection c); boolean retainAll(Collection c);
...@@ -202,14 +213,14 @@ public interface Collection ...@@ -202,14 +213,14 @@ public interface Collection
/** /**
* Get the number of elements in this 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(); int size();
/** /**
* Copy the current contents of this collection into an array. * 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 * collection, containing the elements currently in this collection, in
* any order. * any order.
*/ */
...@@ -227,9 +238,9 @@ public interface Collection ...@@ -227,9 +238,9 @@ public interface Collection
* if it is known that this collection does not contain any null elements. * if it is known that this collection does not contain any null elements.
* *
* @param a the array to copy this collection into. * @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. * 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. * collection is not a subtype of the element type of a.
*/ */
Object[] toArray(Object[] a); Object[] toArray(Object[] a);
......
...@@ -29,36 +29,67 @@ package java.util; ...@@ -29,36 +29,67 @@ package java.util;
/** /**
* Interface for objects that specify an ordering between objects. The ordering * 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 * should be <em>total</em>, such that any two objects of the correct type
* equal by the equals method, or <EM>partial</EM> such that this is not * can be compared, and the comparison is reflexive, anti-symmetric, and
* necessarily true. For example, a case-sensitive dictionary order comparison * transitive. It is also recommended that the comparator be <em>consistent
* of Strings is total, but if it is case-insensitive it is partial, because * with equals</em>, although this is not a strict requirement. A relation
* "abc" and "ABC" compare as equal even though "abc".equals("ABC") returns * is consistent with equals if these two statements always have the same
* false. * 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> * <P>
* In general, Comparators should be Serializable, because when they are passed * In general, Comparators should be Serializable, because when they are passed
* to Serializable data structures such as SortedMap or SortedSet, the entire * to Serializable data structures such as SortedMap or SortedSet, the entire
* data structure will only serialize correctly if the comparator is * data structure will only serialize correctly if the comparator is
* Serializable. * 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 public interface Comparator
{ {
/** /**
* Return an integer that is negative, zero or positive depending on whether * 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 * the first argument is less than, equal to or greater than the second
* according to this ordering. This method should obey the following contract: * according to this ordering. This method should obey the following
* <UL> * contract:
* <LI>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</LI> * <ul>
* <LI>if compare(a, b) throws an exception, so does compare(b, a)</LI> * <li>if compare(a, b) &lt; 0 then compare(b, a) &gt; 0</li>
* <LI>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c) * <li>if compare(a, b) throws an exception, so does compare(b, a)</li>
* &lt; 0</LI> * <li>if compare(a, b) &lt; 0 and compare(b, c) &lt; 0 then compare(a, c)
* <LI>if a.equals(b) or both a and b are null, then compare(a, b) == 0. * &lt; 0</li>
* The converse need not be true, but if it is, this Comparator * <li>if compare(a, b) == 0 then compare(a, c) and compare(b, c) must
* specifies a <EM>total</EM> ordering.</LI> * have the same sign</li
* </UL> * </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 * @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); int compare(Object o1, Object o2);
...@@ -66,8 +97,12 @@ public interface Comparator ...@@ -66,8 +97,12 @@ public interface Comparator
* Return true if the object is equal to this object. To be * Return true if the object is equal to this object. To be
* considered equal, the argument object must satisfy the constraints * considered equal, the argument object must satisfy the constraints
* of <code>Object.equals()</code>, be a Comparator, and impose the * 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 * @param obj The object
* @return true if it is a Comparator that imposes the same order
* @see Object#equals(Object)
*/ */
boolean equals(Object obj); boolean equals(Object obj);
} }
...@@ -42,7 +42,12 @@ package java.util; ...@@ -42,7 +42,12 @@ package java.util;
* be obtained by the enumeration method in class Collections. * be obtained by the enumeration method in class Collections.
* *
* @author Warren Levy <warrenl@cygnus.com> * @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 public interface Enumeration
{ {
...@@ -50,8 +55,8 @@ public interface Enumeration ...@@ -50,8 +55,8 @@ public interface Enumeration
* Tests whether there are elements remaining in the enumeration. * Tests whether there are elements remaining in the enumeration.
* *
* @return true if there is at least one more element 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 * that is, if the next call to nextElement will not throw a
* NoSuchElementException. * NoSuchElementException.
*/ */
boolean hasMoreElements(); boolean hasMoreElements();
...@@ -59,7 +64,7 @@ public interface Enumeration ...@@ -59,7 +64,7 @@ public interface Enumeration
* Obtain the next element in the enumeration. * Obtain the next element in the enumeration.
* *
* @return 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();
} }
/* Iterator.java -- Interface for iterating over collections /* 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. This file is part of GNU Classpath.
...@@ -28,20 +28,28 @@ executable file might be covered by the GNU General Public License. */ ...@@ -28,20 +28,28 @@ executable file might be covered by the GNU General Public License. */
package java.util; package java.util;
/** /**
* An object which iterates over a collection. An Iterator is used to return the * An object which iterates over a collection. An Iterator is used to return
* items once only, in sequence, by successive calls to the next method. It is * the items once only, in sequence, by successive calls to the next method.
* also possible to remove elements from the underlying collection by using the * It is also possible to remove elements from the underlying collection by
* optional remove method. Iterator is intended as a replacement for the * using the optional remove method. Iterator is intended as a replacement
* Enumeration interface of previous versions of Java, which did not have the * for the Enumeration interface of previous versions of Java, which did not
* remove method and had less conveniently named methods. * 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 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, * @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.
*/ */
boolean hasNext(); boolean hasNext();
...@@ -49,20 +57,20 @@ public interface Iterator ...@@ -49,20 +57,20 @@ public interface Iterator
* Obtain the next element in the collection. * Obtain the next element in the collection.
* *
* @return 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(); Object next();
/** /**
* Remove from the underlying collection the last element returned by 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 * (optional operation). This method can be called only once after each
* affect what will be returned by subsequent calls to next. This operation is * call to <code>next()</code>. It does not affect what will be returned
* optional, it may throw an UnsupportedOperationException. * by subsequent calls to next.
* *
* @exception IllegalStateException if next has not yet been called or remove * @throws IllegalStateException if next has not yet been called or remove
* has already been called since the last call to next. * has already been called since the last call to next.
* @exception UnsupportedOperationException if this Iterator does not support * @throws UnsupportedOperationException if this Iterator does not support
* the remove operation. * the remove operation.
*/ */
void remove(); void remove();
} }
/* ListIterator.java -- Extended Iterator for iterating over ordered lists /* 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. This file is part of GNU Classpath.
...@@ -32,116 +32,128 @@ package java.util; ...@@ -32,116 +32,128 @@ package java.util;
* elements may be accessed in forward or reverse order, elements may be * 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 * replaced as well as removed, and new elements may be inserted, during the
* traversal of the list. * 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 public interface ListIterator extends Iterator
{ {
/** /**
* Tests whether there are elements remaining in the list in the forward * 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 * @return true if the list continues in the forward direction
* forward direction, that is, if the next call to next will not throw
* NoSuchElementException.
*/ */
boolean hasNext(); boolean hasNext();
/** /**
* Tests whether there are elements remaining in the list in the reverse * 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 * @return true if the list continues in the reverse direction
* reverse direction, that is, if the next call to previous will not throw
* NoSuchElementException.
*/ */
boolean hasPrevious(); boolean hasPrevious();
/** /**
* Obtain the next element in the list in the forward direction. Repeated * 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 * calls to next may be used to iterate over the entire list, or calls to
* and previous may be used together to go forwards and backwards. Alternating * next and previous may be used together to go forwards and backwards.
* calls to next and previous will return the same element. * Alternating calls to next and previous will return the same element.
* *
* @return the next element in the list in the forward direction * @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(); Object next();
/** /**
* Obtain the next element in the list in the reverse direction. Repeated * 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 previous may be used to iterate backwards over the entire list,
* calls to next and previous may be used together to go forwards and * 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 * backwards. Alternating calls to next and previous will return the same
* element. * element.
* *
* @return the next element in the list in the reverse direction * @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(); Object previous();
/** /**
* Find the index of the element that would be returned by a call to next. * 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, * @return the index of the element that would be returned by next()
* or list.size() if the iterator is at the end of the list.
*/ */
int nextIndex(); 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 * @return the index of the element that would be returned by previous()
* previous, or -1 if the iterator is at the beginning of the list.
*/ */
int previousIndex(); int previousIndex();
/** /**
* Insert an element into the list at the current position of the iterator. * 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 * (optional operation). The element is inserted in between the element that
* previous and the element that would be returned by next. After the * would be returned by previous and the element that would be returned by
* insertion, a subsequent call to next is unaffected, but a call to * next. After the insertion, a subsequent call to next is unaffected, but
* previous returns the item that was added. This operation is optional, it * a call to previous returns the item that was added. The values returned
* may throw an UnsupportedOperationException. * by nextIndex() and previousIndex() are incremented.
* *
* @param o the object to insert into the list * @param o the object to insert into the list
* @exception ClassCastException the object is of a type which cannot be added * @throws ClassCastException the object is of a type which cannot be added
* to this list * to this list
* @exception IllegalArgumentException some other aspect of the object stops * @throws IllegalArgumentException some other aspect of the object stops
* it being added to this list * it being added to this list
* @exception UnsupportedOperationException if this ListIterator does not * @throws UnsupportedOperationException if this ListIterator does not
* support the add operation * support the add operation
*/ */
void add(Object o); void add(Object o);
/** /**
* Remove from the list the element last returned by a call to next or * 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 * previous (optional operation). This method may only be called if neither
* been called since the last call to next or previous. This operation is * add nor remove have been called since the last call to next or previous.
* optional, it may throw an UnsupportedOperationException.
* *
* @exception IllegalStateException if neither next or previous have been * @throws IllegalStateException if neither next or previous have been
* called, or if add or remove has been called since the last call to next * called, or if add or remove has been called since the last call
* or previous. * to next or previous
* @exception UnsupportedOperationException if this ListIterator does not * @throws UnsupportedOperationException if this ListIterator does not
* support the remove operation. * support the remove operation
*/ */
void remove(); void remove();
/** /**
* Replace the element last returned by a call to next or previous with a * 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 * given object (optional operation). This method may only be called if
* been called since the last call to next or previous. This operation is * neither add nor remove have been called since the last call to next or
* optional, it may throw an UnsupportedOperationException. * previous.
* *
* @param o the object to replace the element with * @param o the object to replace the element with
* @exception ClassCastException the object is of a type which cannot be added * @throws ClassCastException the object is of a type which cannot be added
* to this list * to this list
* @exception IllegalArgumentException some other aspect of the object stops * @throws IllegalArgumentException some other aspect of the object stops
* it being added to this list * it being added to this list
* @exception IllegalStateException if neither next or previous have been * @throws IllegalStateException if neither next or previous have been
* called, or if add or remove has been called since the last call to next * called, or if add or remove has been called since the last call
* or previous. * to next or previous
* @exception UnsupportedOperationException if this ListIterator does not * @throws UnsupportedOperationException if this ListIterator does not
* support the set operation. * support the set operation
*/ */
void set(Object o); void set(Object o);
} }
/* 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.
}
/* Set.java -- A collection that prohibits duplicates /* 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. This file is part of GNU Classpath.
...@@ -25,25 +25,208 @@ This exception does not however invalidate any other reasons why the ...@@ -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. */ executable file might be covered by the GNU General Public License. */
// TO DO:
// ~ Doc comments for everything.
package java.util; 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 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); 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); 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(); 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); 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); 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); 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(); int hashCode();
/**
* Returns true if the set contains no elements.
*
* @return true if the set is empty
*/
boolean isEmpty(); boolean isEmpty();
/**
* Returns an iterator over the set. The iterator has no specific order,
* unless further specified.
*
* @return a set iterator
*/
Iterator 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); 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); 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); 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(); 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(); 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);
} }
/* SortedMap.java -- A map that makes guarantees about the order of its keys /* 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. This file is part of GNU Classpath.
...@@ -25,17 +25,135 @@ This exception does not however invalidate any other reasons why the ...@@ -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. */ executable file might be covered by the GNU General Public License. */
// TO DO:
// ~ Doc comments for everything.
package java.util; 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 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(); Comparator comparator();
/**
* Returns the first (lowest sorted) key in the map.
*
* @return the first key
*/
Object firstKey(); 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); SortedMap headMap(Object toKey);
/**
* Returns the last (highest sorted) key in the map.
*
* @return the last key
*/
Object lastKey(); 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); 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); SortedMap tailMap(Object fromKey);
} }
/* 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 elements
Copyright (C) 1998 Free Software Foundation, Inc. Copyright (C) 1998, 2001 Free Software Foundation, Inc.
This file is part of GNU Classpath. This file is part of GNU Classpath.
...@@ -26,17 +26,137 @@ This exception does not however invalidate any other reasons why the ...@@ -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. */ executable file might be covered by the GNU General Public License. */
// TO DO:
// ~ Doc comments for everything.
package java.util; 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 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(); Comparator comparator();
/**
* Returns the first (lowest sorted) element in the map.
*
* @return the first element
*/
Object first(); 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); SortedSet headSet(Object toElement);
/**
* Returns the last (highest sorted) element in the map.
*
* @return the last element
*/
Object last(); 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); 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); SortedSet tailSet(Object fromElement);
} }
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment