FreeChainXenon/gcc
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

AbstractCollection.java, [...]: Added additional exceptions to documentation...

Browse source 
2004-08-29  Andrew John Hughes  <gnu_andrew@member.fsf.org>

	* java/util/AbstractCollection.java, java/util/AbstractList.java,
	java/util/AbstractMap.java, java/util/AbstractSequentialList.java,
	java/util/ArrayList.java, java/util/Arrays.java,
	java/util/BitSet.java, java/util/Calendar.java,
	java/util/Collection.java, java/util/ListIterator.java,
	java/util/Map.java, java/util/SortedSet.java:
	Added additional exceptions to documentation, along
	with some additions and corrections.

From-SVN: r86730
This commit is contained in:
Andrew John Hughes 2004-08-29 17:28:09 +00:00 • committed by Andreas Tobler
parent 294fbfc89f
commit 477a21f7f9
13 changed files with 568 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
libjava/ChangeLog
View file

@ -1,3 +1,14 @@
2004-08-29 Andrew John Hughes <gnu_andrew@member.fsf.org>
* java/util/AbstractCollection.java, java/util/AbstractList.java,
java/util/AbstractMap.java, java/util/AbstractSequentialList.java,
java/util/ArrayList.java, java/util/Arrays.java,
java/util/BitSet.java, java/util/Calendar.java,
java/util/Collection.java, java/util/ListIterator.java,
java/util/Map.java, java/util/SortedSet.java:
Added additional exceptions to documentation, along
with some additions and corrections.
2004-08-27 Hans Boehm <Hans.Boehm@hp.com>
* configure.ac: Handle --enable-gc-debug.

18
libjava/java/util/AbstractCollection.java
View file

@ -129,11 +129,13 @@ public abstract class AbstractCollection implements Collection
* @return true if the add operation caused the Collection to change
* @throws UnsupportedOperationException if the add operation is not
* supported on this collection
* @throws NullPointerException if this collection does not support null,
* or if the specified collection is null
* @throws ClassCastException if an object in c is of the wrong type
* @throws IllegalArgumentException if some aspect of an object in c prevents
* it from being added
* @throws NullPointerException if the specified collection is null
* @throws ClassCastException if the type of any element in c is
* not a valid type for addition.
* @throws IllegalArgumentException if some aspect of any element
* in c prevents it being added.
* @throws NullPointerException if any element in c is null and this
* collection doesn't allow null values.
* @see #add(Object)
*/
public boolean addAll(Collection c)
@ -268,6 +270,7 @@ public abstract class AbstractCollection implements Collection
* @return true if the remove operation caused the Collection to change
* @throws UnsupportedOperationException if this collection's Iterator
* does not support the remove method
* @throws NullPointerException if the collection, c, is null.
* @see Iterator#remove()
*/
public boolean removeAll(Collection c)
@ -288,8 +291,10 @@ public abstract class AbstractCollection implements Collection
* @return true if the remove operation caused the Collection to change
* @throws UnsupportedOperationException if this collection's Iterator
* does not support the remove method
* @throws NullPointerException if the collection, c, is null.
* @see Iterator#remove()
*/
// Package visible for use throughout java.util.
boolean removeAllInternal(Collection c)
{
Iterator itr = iterator();
@ -316,6 +321,7 @@ public abstract class AbstractCollection implements Collection
* @return true if the remove operation caused the Collection to change
* @throws UnsupportedOperationException if this collection's Iterator
* does not support the remove method
* @throws NullPointerException if the collection, c, is null.
* @see Iterator#remove()
*/
public boolean retainAll(Collection c)
@ -337,8 +343,10 @@ public abstract class AbstractCollection implements Collection
* @return true if the remove operation caused the Collection to change
* @throws UnsupportedOperationException if this collection's Iterator
* does not support the remove method
* @throws NullPointerException if the collection, c, is null.
* @see Iterator#remove()
*/
// Package visible for use throughout java.util.
boolean retainAllInternal(Collection c)
{
Iterator itr = iterator();

298
libjava/java/util/AbstractList.java
View file

@ -85,7 +85,7 @@ public abstract class AbstractList extends AbstractCollection implements List
* <code>add(int, Object)</code> and <code>remove(int)</code> methods.
* Otherwise, this field may be ignored.
*/
protected int modCount;
protected transient int modCount;
/**
* The main constructor, for use by subclasses.
@ -308,18 +308,43 @@ while (i.hasNext())
private int knownMod = modCount;
// This will get inlined, since it is private.
/**
* Checks for modifications made to the list from
* elsewhere while iteration is in progress.
*
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
private void checkMod()
{
if (knownMod != modCount)
throw new ConcurrentModificationException();
}
/**
* Tests to see if there are any more objects to
* return.
*
* @return True if the end of the list has not yet been
* reached.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public boolean hasNext()
{
checkMod();
return pos < size;
}
/**
* Retrieves the next object from the list.
*
* @return The next object.
* @throws NoSuchElementException if there are
* no more objects to retrieve.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public Object next()
{
checkMod();
@ -329,6 +354,18 @@ while (i.hasNext())
return get(pos++);
}
/**
* Removes the last object retrieved by <code>next()</code>
* from the list, if the list supports object removal.
*
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
* @throws IllegalStateException if the iterator is positioned
* before the start of the list or the last object has already
* been removed.
* @throws UnsupportedOperationException if the list does
* not support removing elements.
*/
public void remove()
{
checkMod();
@ -405,24 +442,58 @@ while (i.hasNext())
private int size = size();
// This will get inlined, since it is private.
/**
* Checks for modifications made to the list from
* elsewhere while iteration is in progress.
*
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
private void checkMod()
{
if (knownMod != modCount)
throw new ConcurrentModificationException();
}
/**
* Tests to see if there are any more objects to
* return.
*
* @return True if the end of the list has not yet been
* reached.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public boolean hasNext()
{
checkMod();
return position < size;
}
/**
* Tests to see if there are objects prior to the
* current position in the list.
*
* @return True if objects exist prior to the current
* position of the iterator.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public boolean hasPrevious()
{
checkMod();
return position > 0;
}
/**
* Retrieves the next object from the list.
*
* @return The next object.
* @throws NoSuchElementException if there are no
* more objects to retrieve.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public Object next()
{
checkMod();
@ -432,6 +503,15 @@ while (i.hasNext())
return get(position++);
}
/**
* Retrieves the previous object from the list.
*
* @return The next object.
* @throws NoSuchElementException if there are no
* previous objects to retrieve.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public Object previous()
{
checkMod();
@ -441,18 +521,47 @@ while (i.hasNext())
return get(lastReturned);
}
/**
* Returns the index of the next element in the
* list, which will be retrieved by <code>next()</code>
*
* @return The index of the next element.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public int nextIndex()
{
checkMod();
return position;
}
/**
* Returns the index of the previous element in the
* list, which will be retrieved by <code>previous()</code>
*
* @return The index of the previous element.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public int previousIndex()
{
checkMod();
return position - 1;
}
/**
* Removes the last object retrieved by <code>next()</code>
* or <code>previous()</code> from the list, if the list
* supports object removal.
*
* @throws IllegalStateException if the iterator is positioned
* before the start of the list or the last object has already
* been removed.
* @throws UnsupportedOperationException if the list does
* not support removing elements.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public void remove()
{
checkMod();
@ -465,6 +574,24 @@ while (i.hasNext())
knownMod = modCount;
}
/**
* Replaces the last object retrieved by <code>next()</code>
* or <code>previous</code> with o, if the list supports object
* replacement and an add or remove operation has not already
* been performed.
*
* @throws IllegalStateException if the iterator is positioned
* before the start of the list or the last object has already
* been removed.
* @throws UnsupportedOperationException if the list doesn't support
* the addition or removal of elements.
* @throws ClassCastException if the type of o is not a valid type
* for this list.
* @throws IllegalArgumentException if something else related to o
* prevents its addition.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public void set(Object o)
{
checkMod();
@ -473,6 +600,20 @@ while (i.hasNext())
AbstractList.this.set(lastReturned, o);
}
/**
* Adds the supplied object before the element that would be returned
* by a call to <code>next()</code>, if the list supports addition.
*
* @param o The object to add to the list.
* @throws UnsupportedOperationException if the list doesn't support
* the addition of new elements.
* @throws ClassCastException if the type of o is not a valid type
* for this list.
* @throws IllegalArgumentException if something else related to o
* prevents its addition.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public void add(Object o)
{
checkMod();
@ -519,6 +660,8 @@ while (i.hasNext())
*
* @param fromIndex the index, inclusive, to remove from.
* @param toIndex the index, exclusive, to remove to.
* @throws UnsupportedOperationException if the list does
* not support removing elements.
*/
protected void removeRange(int fromIndex, int toIndex)
{
@ -663,7 +806,7 @@ class SubList extends AbstractList
* it is not, an exception is thrown.
*
* @param index the value to check
* @throws IndexOutOfBoundsException if the value is out of range
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
*/
// This will get inlined, since it is private.
private void checkBoundsInclusive(int index)
@ -678,7 +821,7 @@ class SubList extends AbstractList
* (exclusive). If it is not, an exception is thrown.
*
* @param index the value to check
* @throws IndexOutOfBoundsException if the value is out of range
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
*/
// This will get inlined, since it is private.
private void checkBoundsExclusive(int index)
@ -692,6 +835,8 @@ class SubList extends AbstractList
* Specified by AbstractList.subList to return the private field size.
*
* @return the sublist size
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
*/
public int size()
{
@ -705,6 +850,15 @@ class SubList extends AbstractList
* @param index the location to modify
* @param o the new value
* @return the old value
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws UnsupportedOperationException if the backing list does not
* support the set operation
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
* @throws ClassCastException if o cannot be added to the backing list due
* to its type
* @throws IllegalArgumentException if o cannot be added to the backing list
* for some other reason
*/
public Object set(int index, Object o)
{
@ -718,6 +872,9 @@ class SubList extends AbstractList
*
* @param index the location to get from
* @return the object at that location
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
*/
public Object get(int index)
{
@ -731,6 +888,15 @@ class SubList extends AbstractList
*
* @param index the index to insert at
* @param o the object to add
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
* @throws UnsupportedOperationException if the backing list does not
* support the add operation.
* @throws ClassCastException if o cannot be added to the backing list due
* to its type.
* @throws IllegalArgumentException if o cannot be added to the backing
* list for some other reason.
*/
public void add(int index, Object o)
{
@ -746,6 +912,11 @@ class SubList extends AbstractList
*
* @param index the index to remove
* @return the removed object
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt;= size()
* @throws UnsupportedOperationException if the backing list does not
* support the remove operation
*/
public Object remove(int index)
{
@ -764,6 +935,10 @@ class SubList extends AbstractList
*
* @param fromIndex the lower bound, inclusive
* @param toIndex the upper bound, exclusive
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws UnsupportedOperationException if the backing list does
* not support removing elements.
*/
protected void removeRange(int fromIndex, int toIndex)
{
@ -780,6 +955,16 @@ class SubList extends AbstractList
* @param index the location to insert at
* @param c the collection to insert
* @return true if this list was modified, in other words, c is non-empty
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws IndexOutOfBoundsException if index &lt; 0 || index &gt; size()
* @throws UnsupportedOperationException if this list does not support the
* addAll operation
* @throws ClassCastException if some element of c cannot be added to this
* list due to its type
* @throws IllegalArgumentException if some element of c cannot be added
* to this list for some other reason
* @throws NullPointerException if the specified collection is null
*/
public boolean addAll(int index, Collection c)
{
@ -797,6 +982,15 @@ class SubList extends AbstractList
*
* @param c the collection to insert
* @return true if this list was modified, in other words, c is non-empty
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws UnsupportedOperationException if this list does not support the
* addAll operation
* @throws ClassCastException if some element of c cannot be added to this
* list due to its type
* @throws IllegalArgumentException if some element of c cannot be added
* to this list for some other reason
* @throws NullPointerException if the specified collection is null
*/
public boolean addAll(Collection c)
{
@ -819,6 +1013,9 @@ class SubList extends AbstractList
*
* @param index the start location of the iterator
* @return a list iterator over the sublist
* @throws ConcurrentModificationException if the backing list has been
* modified externally to this sublist
* @throws IndexOutOfBoundsException if the value is out of range
*/
public ListIterator listIterator(final int index)
{
@ -830,18 +1027,45 @@ class SubList extends AbstractList
private final ListIterator i = backingList.listIterator(index + offset);
private int position = index;
/**
* Tests to see if there are any more objects to
* return.
*
* @return True if the end of the list has not yet been
* reached.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public boolean hasNext()
{
checkMod();
return position < size;
}
/**
* Tests to see if there are objects prior to the
* current position in the list.
*
* @return True if objects exist prior to the current
* position of the iterator.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public boolean hasPrevious()
{
checkMod();
return position > 0;
}
/**
* Retrieves the next object from the list.
*
* @return The next object.
* @throws NoSuchElementException if there are no
* more objects to retrieve.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public Object next()
{
if (position == size)
@ -850,6 +1074,15 @@ class SubList extends AbstractList
return i.next();
}
/**
* Retrieves the previous object from the list.
*
* @return The next object.
* @throws NoSuchElementException if there are no
* previous objects to retrieve.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public Object previous()
{
if (position == 0)
@ -858,16 +1091,42 @@ class SubList extends AbstractList
return i.previous();
}
/**
* Returns the index of the next element in the
* list, which will be retrieved by <code>next()</code>
*
* @return The index of the next element.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public int nextIndex()
{
return i.nextIndex() - offset;
}
/**
* Returns the index of the previous element in the
* list, which will be retrieved by <code>previous()</code>
*
* @return The index of the previous element.
* @throws ConcurrentModificationException if the
* list has been modified elsewhere.
*/
public int previousIndex()
{
return i.previousIndex() - offset;
}
/**
* Removes the last object retrieved by <code>next()</code>
* from the list, if the list supports object removal.
*
* @throws IllegalStateException if the iterator is positioned
* before the start of the list or the last object has already
* been removed.
* @throws UnsupportedOperationException if the list does
* not support removing elements.
*/
public void remove()
{
i.remove();
@ -876,11 +1135,44 @@ class SubList extends AbstractList
modCount = backingList.modCount;
}
/**
* Replaces the last object retrieved by <code>next()</code>
* or <code>previous</code> with o, if the list supports object
* replacement and an add or remove operation has not already
* been performed.
*
* @throws IllegalStateException if the iterator is positioned
* before the start of the list or the last object has already
* been removed.
* @throws UnsupportedOperationException if the list doesn't support
* the addition or removal of elements.
* @throws ClassCastException if the type of o is not a valid type
* for this list.
* @throws IllegalArgumentException if something else related to o
* prevents its addition.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public void set(Object o)
{
i.set(o);
}
/**
* Adds the supplied object before the element that would be returned
* by a call to <code>next()</code>, if the list supports addition.
*
* @param o The object to add to the list.
* @throws UnsupportedOperationException if the list doesn't support
* the addition of new elements.
* @throws ClassCastException if the type of o is not a valid type
* for this list.
* @throws IllegalArgumentException if something else related to o
* prevents its addition.
* @throws ConcurrentModificationException if the list
* has been modified elsewhere.
*/
public void add(Object o)
{
i.add(o);

145
libjava/java/util/AbstractMap.java
View file

@ -91,6 +91,21 @@ public abstract class AbstractMap implements Map
{
}
/**
* Returns a set view of the mappings in this Map. Each element in the
* set must be an implementation of Map.Entry. The set is backed by
* the map, so that changes in one show up in the other. Modifications
* made while an iterator is in progress cause undefined behavior. If
* the set supports removal, these methods must be valid:
* <code>Iterator.remove</code>, <code>Set.remove</code>,
* <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
* Element addition is not supported via this set.
*
* @return the entry set
* @see Map.Entry
*/
public abstract Set entrySet();
/**
* Remove all entries from this Map (optional operation). This default
* implementation calls entrySet().clear(). NOTE: If the entry set does
@ -153,8 +168,9 @@ public abstract class AbstractMap implements Map
* This implementation does a linear search, O(n), over the
* <code>entrySet()</code>, returning <code>true</code> if a match
* is found, <code>false</code> if the iteration ends. A match is
* defined as <code>(value == null ? v == null : value.equals(v))</code>
* Subclasses are unlikely to implement this more efficiently.
* defined as a value, v, where <code>(value == null ? v == null :
* value.equals(v))</code>. Subclasses are unlikely to implement
* this more efficiently.
*
* @param value the value to search for
* @return true if the map contains the value
@ -170,21 +186,6 @@ public abstract class AbstractMap implements Map
return false;
}
/**
* Returns a set view of the mappings in this Map. Each element in the
* set must be an implementation of Map.Entry. The set is backed by
* the map, so that changes in one show up in the other. Modifications
* made while an iterator is in progress cause undefined behavior. If
* the set supports removal, these methods must be valid:
* <code>Iterator.remove</code>, <code>Set.remove</code>,
* <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
* Element addition is not supported via this set.
*
* @return the entry set
* @see Map.Entry
*/
public abstract Set entrySet();
/**
* Compares the specified object with this map for equality. Returns
* <code>true</code> if the other object is a Map with the same mappings,
@ -277,32 +278,75 @@ public abstract class AbstractMap implements Map
if (keys == null)
keys = new AbstractSet()
{
/**
* Retrieves the number of keys in the backing map.
*
* @return The number of keys.
*/
public int size()
{
return AbstractMap.this.size();
}
/**
* Returns true if the backing map contains the
* supplied key.
*
* @param key The key to search for.
* @return True if the key was found, false otherwise.
*/
public boolean contains(Object key)
{
return containsKey(key);
}
/**
* Returns an iterator which iterates over the keys
* in the backing map, using a wrapper around the
* iterator returned by <code>entrySet()</code>.
*
* @return An iterator over the keys.
*/
public Iterator iterator()
{
return new Iterator()
{
/**
* The iterator returned by <code>entrySet()</code>.
*/
private final Iterator map_iterator = entrySet().iterator();
/**
* Returns true if a call to <code>next()</code> will
* return another key.
*
* @return True if the iterator has not yet reached
* the last key.
*/
public boolean hasNext()
{
return map_iterator.hasNext();
}
/**
* Returns the key from the next entry retrieved
* by the underlying <code>entrySet()</code> iterator.
*
* @return The next key.
*/
public Object next()
{
return ((Map.Entry) map_iterator.next()).getKey();
}
/**
* Removes the map entry which has a key equal
* to that returned by the last call to
* <code>next()</code>.
*
* @throws UnsupportedOperationException if the
* map doesn't support removal.
*/
public void remove()
{
map_iterator.remove();
@ -343,11 +387,13 @@ public abstract class AbstractMap implements Map
*
* @param m the mapping to load into this map
* @throws UnsupportedOperationException if the operation is not supported
* @throws ClassCastException if a key or value is of the wrong type
* by this map.
* @throws ClassCastException if a key or value is of the wrong type for
* adding to this map.
* @throws IllegalArgumentException if something about a key or value
* prevents it from existing in this map
* @throws NullPointerException if the map forbids null keys or values, or
* if <code>m</code> is null.
* prevents it from existing in this map.
* @throws NullPointerException if the map forbids null keys or values.
* @throws NullPointerException if <code>m</code> is null.
* @see #put(Object, Object)
*/
public void putAll(Map m)
@ -372,7 +418,9 @@ public abstract class AbstractMap implements Map
* implementations override it for efficiency.
*
* @param key the key to remove
* @return the value the key mapped to, or null if not present
* @return the value the key mapped to, or null if not present.
* Null may also be returned if null values are allowed
* in the map and the value of this mapping is null.
* @throws UnsupportedOperationException if deletion is unsupported
* @see Iterator#remove()
*/
@ -461,32 +509,76 @@ public abstract class AbstractMap implements Map
if (values == null)
values = new AbstractCollection()
{
/**
* Returns the number of values stored in
* the backing map.
*
* @return The number of values.
*/
public int size()
{
return AbstractMap.this.size();
}
/**
* Returns true if the backing map contains
* the supplied value.
*
* @param value The value to search for.
* @return True if the value was found, false otherwise.
*/
public boolean contains(Object value)
{
return containsValue(value);
}
/**
* Returns an iterator which iterates over the
* values in the backing map, by using a wrapper
* around the iterator returned by <code>entrySet()</code>.
*
* @return An iterator over the values.
*/
public Iterator iterator()
{
return new Iterator()
{
/**
* The iterator returned by <code>entrySet()</code>.
*/
private final Iterator map_iterator = entrySet().iterator();
/**
* Returns true if a call to <code>next()</call> will
* return another value.
*
* @return True if the iterator has not yet reached
* the last value.
*/
public boolean hasNext()
{
return map_iterator.hasNext();
}
/**
* Returns the value from the next entry retrieved
* by the underlying <code>entrySet()</code> iterator.
*
* @return The next value.
*/
public Object next()
{
return ((Map.Entry) map_iterator.next()).getValue();
}
/**
* Removes the map entry which has a key equal
* to that returned by the last call to
* <code>next()</code>.
*
* @throws UnsupportedOperationException if the
* map doesn't support removal.
*/
public void remove()
{
map_iterator.remove();
@ -533,6 +625,7 @@ public abstract class AbstractMap implements Map
* @author Eric Blake <ebb9@email.byu.edu>
*/
// XXX - FIXME Use fully qualified implements as gcj 3.1 workaround.
// Bug still exists in 3.4.1
static class BasicMapEntry implements Map.Entry
{
/**
@ -627,7 +720,13 @@ public abstract class AbstractMap implements Map
*
* @param newVal the new value to store
* @return the old value
* @throws NullPointerException if the map forbids null values
* @throws NullPointerException if the map forbids null values.
* @throws UnsupportedOperationException if the map doesn't support
* <code>put()</code>.
* @throws ClassCastException if the value is of a type unsupported
* by the map.
* @throws IllegalArgumentException if something else about this
* value prevents it being stored in the map.
*/
public Object setValue(Object newVal)
{

8
libjava/java/util/AbstractSequentialList.java
View file

@ -105,7 +105,9 @@ public abstract class AbstractSequentialList extends AbstractList
* @throws ClassCastException if o cannot be added to this list due to its
* type
* @throws IllegalArgumentException if o cannot be added to this list for
* some other reason
* some other reason.
* @throws NullPointerException if o is null and the list does not permit
* the addition of null values.
*/
public void add(int index, Object o)
{
@ -137,6 +139,8 @@ public abstract class AbstractSequentialList extends AbstractList
* @throws IllegalArgumentException if some element of c cannot be added
* to this list for some other reason
* @throws NullPointerException if the specified collection is null
* @throws NullPointerException if an object, o, in c is null and the list
* does not permit the addition of null values.
* @see #add(int, Object)
*/
public boolean addAll(int index, Collection c)
@ -214,6 +218,8 @@ public abstract class AbstractSequentialList extends AbstractList
* type
* @throws IllegalArgumentException if o cannot be added to this list for
* some other reason
* @throws NullPointerException if o is null and the list does not allow
* a value to be set to null.
*/
public Object set(int index, Object o)
{

13
libjava/java/util/ArrayList.java
View file

@ -120,7 +120,7 @@ public class ArrayList extends AbstractList
}
/**
* Construct a new ArrayList with the default capcity (16).
* Construct a new ArrayList with the default capacity (16).
*/
public ArrayList()
{
@ -311,7 +311,8 @@ public class ArrayList extends AbstractList
}
/**
* Sets the element at the specified index.
* Sets the element at the specified index. The new element, e,
* can be an object of any type or null.
*
* @param index the index at which the element is being set
* @param e the element to be set
@ -328,6 +329,7 @@ public class ArrayList extends AbstractList
/**
* Appends the supplied element to the end of this list.
* The element, e, can be an object of any type or null.
*
* @param e the element to be appended to this list
* @return true, the add will always succeed
@ -344,6 +346,7 @@ public class ArrayList extends AbstractList
/**
* Adds the supplied element at the specified index, shifting all
* elements currently at that index or higher one to the right.
* The element, e, can be an object of any type or null.
*
* @param index the index at which the element is being added
* @param e the item being added
@ -397,7 +400,8 @@ public class ArrayList extends AbstractList
/**
* Add each element in the supplied Collection to this List. It is undefined
* what happens if you modify the list while this is taking place; for
* example, if the collection contains this list.
* example, if the collection contains this list. c can contain objects
* of any type, as well as null values.
*
* @param c a Collection containing elements to be added to this List
* @return true if the list was modified, in other words c is not empty
@ -410,7 +414,8 @@ public class ArrayList extends AbstractList
/**
* Add all elements in the supplied collection, inserting them beginning
* at the specified index.
* at the specified index. c can contain objects of any type, as well
* as null values.
*
* @param index the index at which the elements will be inserted
* @param c the Collection containing the elements to be inserted

57
libjava/java/util/Arrays.java
View file

@ -2374,16 +2374,35 @@ public class Arrays
this.a = a;
}
/**
* Returns the object at the specified index in
* the array.
*
* @param index The index to retrieve an object from.
* @return The object at the array index specified.
*/
public Object get(int index)
{
return a[index];
}
/**
* Returns the size of the array.
*
* @return The size.
*/
public int size()
{
return a.length;
}
/**
* Replaces the object at the specified index
* with the supplied element.
*
* @param index The index at which to place the new object.
* @return The object replaced by this operation.
*/
public Object set(int index, Object element)
{
Object old = a[index];
@ -2391,11 +2410,25 @@ public class Arrays
return old;
}
/**
* Returns true if the array contains the
* supplied object.
*
* @param o The object to look for.
* @return True if the object was found.
*/
public boolean contains(Object o)
{
return lastIndexOf(o) >= 0;
}
/**
* Returns the first index at which the
* object, o, occurs in the array.
*
* @param o The object to search for.
* @return The first relevant index.
*/
public int indexOf(Object o)
{
int size = a.length;
@ -2405,6 +2438,13 @@ public class Arrays
return -1;
}
/**
* Returns the last index at which the
* object, o, occurs in the array.
*
* @param o The object to search for.
* @return The last relevant index.
*/
public int lastIndexOf(Object o)
{
int i = a.length;
@ -2414,11 +2454,28 @@ public class Arrays
return -1;
}
/**
* Transforms the list into an array of
* objects, by simplying cloning the array
* wrapped by this list.
*
* @return A clone of the internal array.
*/
public Object[] toArray()
{
return (Object[]) a.clone();
}
/**
* Copies the objects from this list into
* the supplied array. The supplied array
* is shrunk or enlarged to the size of the
* internal array, and filled with its objects.
*
* @param The array to fill with the objects in this list.
* @return The array containing the objects in this list,
* which may or may not be == to array.
*/
public Object[] toArray(Object[] array)
{
int size = a.length;

18
libjava/java/util/BitSet.java
View file

@ -133,7 +133,8 @@ public class BitSet implements Cloneable, Serializable
* Performs the logical AND operation on this bit set and the
* complement of the given <code>set</code>. This means it
* selects every element in the first set, that isn't in the
* second set. The result is stored into this bit set.
* second set. The result is stored into this bit set and is
* effectively the set difference of the two.
*
* @param set the second bit set
* @throws NullPointerException if set is null
@ -210,7 +211,8 @@ public class BitSet implements Cloneable, Serializable
*
* @param from the start range (inclusive)
* @param to the end range (exclusive)
* @throws IndexOutOfBoundsException if from &lt; 0 || from &gt; to
* @throws IndexOutOfBoundsException if from &lt; 0 || to &lt; 0 ||
* from &gt; to
* @since 1.4
*/
public void clear(int from, int to)
@ -304,7 +306,8 @@ public class BitSet implements Cloneable, Serializable
*
* @param from the low index (inclusive)
* @param to the high index (exclusive)
* @throws IndexOutOfBoundsException if from &gt; to || from &lt; 0
* @throws IndexOutOfBoundsException if from &gt; to || from &lt; 0 ||
* to &lt; 0
* @since 1.4
*/
public void flip(int from, int to)
@ -352,7 +355,8 @@ public class BitSet implements Cloneable, Serializable
*
* @param from the low index (inclusive)
* @param to the high index (exclusive)
* @throws IndexOutOfBoundsException if from &gt; to || from &lt; 0
* @throws IndexOutOfBoundsException if from &gt; to || from &lt; 0 ||
* to &lt; 0
* @since 1.4
*/
public BitSet get(int from, int to)
@ -618,7 +622,8 @@ public class BitSet implements Cloneable, Serializable
*
* @param from the start range (inclusive)
* @param to the end range (exclusive)
* @throws IndexOutOfBoundsException if from &lt; 0 || from &gt; to
* @throws IndexOutOfBoundsException if from &lt; 0 || from &gt; to ||
* to &lt; 0
* @since 1.4
*/
public void set(int from, int to)
@ -649,7 +654,8 @@ public class BitSet implements Cloneable, Serializable
* @param from the start range (inclusive)
* @param to the end range (exclusive)
* @param value the value to set it to
* @throws IndexOutOfBoundsException if from &lt; 0 || from &gt; to
* @throws IndexOutOfBoundsException if from &lt; 0 || from &gt; to ||
* to &lt; 0
* @since 1.4
*/
public void set(int from, int to, boolean value)

32
libjava/java/util/Calendar.java
View file

@ -585,7 +585,9 @@ public abstract class Calendar implements Serializable, Cloneable
* if they are invalid.
* @param field the time field. One of the time field constants.
* @return the value of the specified field
*
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
* @specnote Not final since JDK 1.4
*/
public int get(int field)
@ -603,6 +605,9 @@ public abstract class Calendar implements Serializable, Cloneable
* @param field the time field. One of the time field constants.
* @return the value of the specified field, undefined if
* <code>areFieldsSet</code> or <code>isSet[field]</code> is false.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
*/
protected final int internalGet(int field)
{
@ -614,7 +619,9 @@ public abstract class Calendar implements Serializable, Cloneable
* the time in milliseconds.
* @param field the time field. One of the time field constants
* @param value the value to be set.
*
* @throws ArrayIndexOutOfBoundsException if field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
* @specnote Not final since JDK 1.4
*/
public void set(int field, int value)
@ -718,6 +725,9 @@ public abstract class Calendar implements Serializable, Cloneable
/**
* Clears the values of the specified time field.
* @param field the time field. One of the time field constants.
* @throws ArrayIndexOutOfBoundsException if field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
*/
public final void clear(int field)
{
@ -730,6 +740,9 @@ public abstract class Calendar implements Serializable, Cloneable
/**
* Determines if the specified field has a valid value.
* @return true if the specified field has a value.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
*/
public final boolean isSet(int field)
{
@ -803,6 +816,9 @@ public abstract class Calendar implements Serializable, Cloneable
* it does what you expect: Jan, 25 + 10 Days is Feb, 4.
* @param field the time field. One of the time field constants.
* @param amount the amount of time.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
*/
public abstract void add(int field, int amount);
@ -817,6 +833,9 @@ public abstract class Calendar implements Serializable, Cloneable
* The date June, 31 is automatically converted to July, 1.
* @param field the time field. One of the time field constants.
* @param up the direction, true for up, false for down.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
*/
public abstract void roll(int field, boolean up);
@ -830,6 +849,9 @@ public abstract class Calendar implements Serializable, Cloneable
* @param field the time field. One of the time field constants.
* @param amount the amount to roll by, positive for rolling up,
* negative for rolling down.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
* @since JDK1.2
*/
public void roll(int field, int amount)
@ -965,6 +987,9 @@ public abstract class Calendar implements Serializable, Cloneable
* This value is dependent on the values of the other fields.
* @param field the time field. One of the time field constants.
* @return the actual minimum value.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
* @since jdk1.2
*/
public int getActualMinimum(int field)
@ -988,6 +1013,9 @@ public abstract class Calendar implements Serializable, Cloneable
* This value is dependent on the values of the other fields.
* @param field the time field. One of the time field constants.
* @return the actual maximum value.
* @throws ArrayIndexOutOfBoundsException if the field is outside
* the valid range. The value of field must be >= 0 and
* <= <code>FIELD_COUNT</code>.
* @since jdk1.2
*/
public int getActualMaximum(int field)

2
libjava/java/util/Collection.java
View file

@ -223,6 +223,7 @@ public interface Collection
* Remove all elements of a given collection from this collection. That is,
* remove every element e such that c.contains(e).
*
* @param c The collection of objects to be removed.
* @return true if this collection was modified as a result of this call.
* @throws UnsupportedOperationException if this collection does not
* support the removeAll operation.
@ -238,6 +239,7 @@ 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).
*
* @param c The collection of objects to be retained.
* @return true if this collection was modified as a result of this call.
* @throws UnsupportedOperationException if this collection does not
* support the retainAll operation.

10
libjava/java/util/ListIterator.java
View file

@ -127,12 +127,12 @@ public interface ListIterator extends Iterator
* by nextIndex() and previousIndex() are incremented.
*
* @param o the object to insert into the list
* @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 ClassCastException if the object is of a type which cannot be added
* to this list.
* @throws IllegalArgumentException if some other aspect of the object stops
* it being added to this list.
* @throws UnsupportedOperationException if this ListIterator does not
* support the add operation
* support the add operation.
*/
void add(Object o);

2
libjava/java/util/Map.java
View file

@ -227,7 +227,7 @@ public interface Map
* null values may also return null if the key was removed.
*
* @param key the key to remove
* @return the value the key mapped to, or null if not present
* @return the value the key mapped to, or null if not present.
* @throws UnsupportedOperationException if deletion is unsupported
* @throws NullPointerException if the key is null and this map doesn't
* support null keys.

8
libjava/java/util/SortedSet.java
View file

@ -50,7 +50,7 @@ package java.util;
* <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,
* set is to obey the general contract of the Set interface. If not,
* the results are well-defined, but probably not what you wanted.
* <p>
*
@ -85,7 +85,7 @@ public interface SortedSet extends Set
Comparator comparator();
/**
* Returns the first (lowest sorted) element in the map.
* Returns the first (lowest sorted) element in the set.
*
* @return the first element
* @throws NoSuchElementException if the set is empty.
@ -110,13 +110,13 @@ public interface SortedSet extends 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
* @throws NullPointerException if toElement is null but the set does not
* allow null elements
*/
SortedSet headSet(Object toElement);
/**
* Returns the last (highest sorted) element in the map.
* Returns the last (highest sorted) element in the set.
*
* @return the last element
* @throws NoSuchElementException if the set is empty.