--- jsr166/src/main/java/util/Vector.java 2006/03/19 17:59:39 1.9
+++ jsr166/src/main/java/util/Vector.java 2007/09/11 15:38:19 1.22
@@ -1,49 +1,70 @@
/*
- * %W% %E%
+ * Copyright 1994-2007 Sun Microsystems, Inc. All Rights Reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
- * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
- * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Sun designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Sun in the LICENSE file that accompanied this code.
+ *
+ * This code 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
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ * CA 95054 USA or visit www.sun.com if you need additional information or
+ * have any questions.
*/
package java.util;
/**
- * The Vector
class implements a growable array of
+ * The {@code Vector} class implements a growable array of
* objects. Like an array, it contains components that can be
* accessed using an integer index. However, the size of a
- * Vector
can grow or shrink as needed to accommodate
- * adding and removing items after the Vector
has been created.
+ * {@code Vector} can grow or shrink as needed to accommodate
+ * adding and removing items after the {@code Vector} has been created.
*
*
Each vector tries to optimize storage management by maintaining a
- * capacity
and a capacityIncrement
. The
- * capacity
is always at least as large as the vector
+ * {@code capacity} and a {@code capacityIncrement}. The
+ * {@code capacity} is always at least as large as the vector
* size; it is usually larger because as components are added to the
* vector, the vector's storage increases in chunks the size of
- * capacityIncrement
. An application can increase the
+ * {@code capacityIncrement}. An application can increase the
* capacity of a vector before inserting a large number of
* components; this reduces the amount of incremental reallocation.
*
- *
The Iterators returned by Vector's iterator and listIterator - * methods are fail-fast: if the Vector is structurally modified - * at any time after the Iterator is created, in any way except through the - * Iterator's own remove or add methods, the Iterator will throw a - * ConcurrentModificationException. Thus, in the face of concurrent - * modification, the Iterator fails quickly and cleanly, rather than risking - * arbitrary, non-deterministic behavior at an undetermined time in the future. - * The Enumerations returned by Vector's elements method are not - * fail-fast. + *
+ * The iterators returned by this class's {@link #iterator() iterator} and + * {@link #listIterator(int) listIterator} methods are fail-fast: + * if the vector is structurally modified at any time after the iterator is + * created, in any way except through the iterator's own + * {@link ListIterator#remove() remove} or + * {@link ListIterator#add(Object) add} methods, the iterator will throw a + * {@link ConcurrentModificationException}. Thus, in the face of + * concurrent modification, the iterator fails quickly and cleanly, rather + * than risking arbitrary, non-deterministic behavior at an undetermined + * time in the future. The {@link Enumeration Enumerations} returned by + * the {@link #elements() elements} method are not fail-fast. * *
Note that the fail-fast behavior of an iterator cannot be guaranteed * as it is, generally speaking, impossible to make any hard guarantees in the * presence of unsynchronized concurrent modification. Fail-fast iterators - * throw ConcurrentModificationException on a best-effort basis. + * throw {@code ConcurrentModificationException} on a best-effort basis. * Therefore, it would be wrong to write a program that depended on this * exception for its correctness: the fail-fast behavior of iterators * should be used only to detect bugs. * *
As of the Java 2 platform v1.2, this class was retrofitted to
* implement the {@link List} interface, making it a member of the
- * Java
+ * Java
* Collections Framework. Unlike the new collection
* implementations, {@code Vector} is synchronized.
*
@@ -63,18 +84,18 @@ public class Vector
+ * and is at least large enough to contain all the vector's elements.
*
- * Any array elements following the last element in the Vector are null.
+ * Any array elements following the last element in the Vector are null.
*
* @serial
*/
protected Object[] elementData;
/**
- * The number of valid components in this Vector object.
- * Components elementData[0] through
- * elementData[elementCount-1] are the actual items.
+ * The number of valid components in this {@code Vector} object.
+ * Components {@code elementData[0]} through
+ * {@code elementData[elementCount-1]} are the actual items.
*
* @serial
*/
@@ -100,8 +121,8 @@ public class Vector If the current capacity of this vector is less than
- * minCapacity, then its capacity is increased by replacing its
- * internal data array, kept in the field elementData, with a
+ * {@code minCapacity}, then its capacity is increased by replacing its
+ * internal data array, kept in the field {@code elementData}, with a
* larger one. The size of the new data array will be the old size plus
- * capacityIncrement, unless the value of
- * capacityIncrement is less than or equal to zero, in which case
+ * {@code capacityIncrement}, unless the value of
+ * {@code capacityIncrement} is less than or equal to zero, in which case
* the new capacity will be twice the old capacity; but if this new size
- * is still smaller than minCapacity, then the new capacity will
- * be minCapacity.
+ * is still smaller than {@code minCapacity}, then the new capacity will
+ * be {@code minCapacity}.
*
* @param minCapacity the desired minimum capacity
*/
@@ -212,7 +233,7 @@ public class Vector
+ * Returns the component at the specified index.
*
- * This method is identical in functionality to the get method
- * (which is part of the List interface).
+ * This method is identical in functionality to the {@link #get(int)}
+ * method (which is part of the {@link List} interface).
*
* @param index an index into this vector
* @return the component at the specified index
- * @exception ArrayIndexOutOfBoundsException if the index
- * is negative or not less than the current size of this
- * Vector object.
- * @see #get(int)
- * @see List
+ * @throws ArrayIndexOutOfBoundsException if the index is out of range
+ * ({@code index < 0 || index >= size()})
*/
public synchronized E elementAt(int index) {
if (index >= elementCount) {
throw new ArrayIndexOutOfBoundsException(index + " >= " + elementCount);
}
- return (E)elementData[index];
+ return elementData(index);
}
/**
- * Returns the first component (the item at index 0) of
+ * Returns the first component (the item at index {@code 0}) of
* this vector.
*
* @return the first component of this vector
- * @exception NoSuchElementException if this vector has no components
+ * @throws NoSuchElementException if this vector has no components
*/
public synchronized E firstElement() {
if (elementCount == 0) {
throw new NoSuchElementException();
}
- return (E)elementData[0];
+ return elementData(0);
}
/**
@@ -453,35 +470,34 @@ public class Vector
+ * position is discarded.
*
- * The index must be a value greater than or equal to
+ * The index must be a value greater than or equal to {@code 0}
+ * and less than the current size of the vector.
*
- * This method is identical in functionality to the set method
- * (which is part of the List interface). Note that the set method reverses
- * the order of the parameters, to more closely match array usage. Note
- * also that the set method returns the old value that was stored at the
- * specified position.
+ * This method is identical in functionality to the
+ * {@link #set(int, Object) set(int, E)}
+ * method (which is part of the {@link List} interface). Note that the
+ * {@code set} method reverses the order of the parameters, to more closely
+ * match array usage. Note also that the {@code set} method returns the
+ * old value that was stored at the specified position.
*
* @param obj what the component is to be set to
* @param index the specified index
- * @exception ArrayIndexOutOfBoundsException if the index was invalid
- * @see #size()
- * @see List
- * @see #set(int, java.lang.Object)
+ * @throws ArrayIndexOutOfBoundsException if the index is out of range
+ * ({@code index < 0 || index >= size()})
*/
public synchronized void setElementAt(E obj, int index) {
if (index >= elementCount) {
@@ -494,22 +510,21 @@ public class Vector
+ * is decreased by {@code 1}.
*
- * The index must be a value greater than or equal to
+ * The index must be a value greater than or equal to {@code 0}
+ * and less than the current size of the vector.
*
- * This method is identical in functionality to the remove method
- * (which is part of the List interface). Note that the remove method
- * returns the old value that was stored at the specified position.
+ * This method is identical in functionality to the {@link #remove(int)}
+ * method (which is part of the {@link List} interface). Note that the
+ * {@code remove} method returns the old value that was stored at the
+ * specified position.
*
* @param index the index of the object to remove
- * @exception ArrayIndexOutOfBoundsException if the index was invalid
- * @see #size()
- * @see #remove(int)
- * @see List
+ * @throws ArrayIndexOutOfBoundsException if the index is out of range
+ * ({@code index < 0 || index >= size()})
*/
public synchronized void removeElementAt(int index) {
modCount++;
@@ -530,26 +545,26 @@ public class Vector
+ * previously.
*
- * The index must be a value greater than or equal to The index must be a value greater than or equal to {@code 0}
* and less than or equal to the current size of the vector. (If the
* index is equal to the current size of the vector, the new element
- * is appended to the Vector.)
+ * is appended to the Vector.)
*
- * This method is identical in functionality to the add(Object, int) method
- * (which is part of the List interface). Note that the add method reverses
- * the order of the parameters, to more closely match array usage.
+ * This method is identical in functionality to the
+ * {@link #add(int, Object) add(int, E)}
+ * method (which is part of the {@link List} interface). Note that the
+ * {@code add} method reverses the order of the parameters, to more closely
+ * match array usage.
*
* @param obj the component to insert
* @param index where to insert the new component
- * @exception ArrayIndexOutOfBoundsException if the index was invalid
- * @see #size()
- * @see #add(int, Object)
- * @see List
+ * @throws ArrayIndexOutOfBoundsException if the index is out of range
+ * ({@code index < 0 || index > size()})
*/
public synchronized void insertElementAt(E obj, int index) {
modCount++;
@@ -566,14 +581,13 @@ public class Vector
+ * increased if its size becomes greater than its capacity.
*
- * This method is identical in functionality to the add(Object) method
- * (which is part of the List interface).
+ * This method is identical in functionality to the
+ * {@link #add(Object) add(E)}
+ * method (which is part of the {@link List} interface).
*
* @param obj the component to be added
- * @see #add(Object)
- * @see List
*/
public synchronized void addElement(E obj) {
modCount++;
@@ -586,16 +600,15 @@ public class Vector
+ * than the value it had previously.
*
- * This method is identical in functionality to the remove(Object)
- * method (which is part of the List interface).
+ * This method is identical in functionality to the
+ * {@link #remove(Object)} method (which is part of the
+ * {@link List} interface).
*
* @param obj the component to be removed
- * @return
- *
- * This method is identical in functionality to the clear method
- * (which is part of the List interface).
+ * Removes all components from this vector and sets its size to zero.
*
- * @see #clear
- * @see List
+ * This method is identical in functionality to the {@link #clear}
+ * method (which is part of the {@link List} interface).
*/
public synchronized void removeAllElements() {
modCount++;
@@ -628,13 +638,14 @@ public class Vector
+ * type of the specified array and the size of this Vector.
*
- * If the Vector fits in the specified array with room to spare
+ * If the Vector fits in the specified array with room to spare
* (i.e., the array has more elements than the Vector),
* the element in the array immediately following the end of the
* Vector is set to null. (This is useful in determining the length
@@ -672,11 +683,12 @@ public class Vector
+ * operations supported by this List.
*
- * This method eliminates the need for explicit range operations (of
- * the sort that commonly exist for arrays). Any operation that expects
+ * This method eliminates the need for explicit range operations (of
+ * the sort that commonly exist for arrays). Any operation that expects
* a List can be used as a range operation by operating on a subList view
* instead of a whole List. For example, the following idiom
* removes a range of elements from a List:
@@ -969,9 +986,9 @@ public class Vector
+ * a subList.
*
- * The semantics of the List returned by this method become undefined if
+ * The semantics of the List returned by this method become undefined if
* the backing list (i.e., this List) is structurally modified in
* any way other than via the returned List. (Structural modifications are
* those that change the size of the List, or otherwise perturb it in such
@@ -980,10 +997,10 @@ public class Vector
+ * The specified index indicates the first element that would be
+ * returned by an initial call to {@link ListIterator#next next}.
+ * An initial call to {@link ListIterator#previous previous} would
+ * return the element with the specified index minus one.
+ *
+ * The returned list iterator is fail-fast.
*
- * The list-iterator is fail-fast: if the list is structurally
- * modified at any time after the Iterator is created, in any way except
- * through the list-iterator's own remove or add
- * methods, the list-iterator will throw a
- * ConcurrentModificationException. Thus, in the face of
- * concurrent modification, the iterator fails quickly and cleanly, rather
- * than risking arbitrary, non-deterministic behavior at an undetermined
- * time in the future.
- *
- * @param index index of the first element to be returned from the
- * list-iterator (by a call to next)
- * @return a ListIterator of the elements in this list (in proper
- * sequence), starting at the specified position in the list
* @throws IndexOutOfBoundsException {@inheritDoc}
- * @see List#listIterator(int)
*/
public synchronized ListIterator The returned list iterator is fail-fast.
+ *
+ * @see #listIterator(int)
*/
public synchronized ListIterator The returned iterator is fail-fast.
+ *
* @return an iterator over the elements in this list in proper sequence
*/
public synchronized Iteratornull
items are added to the end of
+ * current size, new {@code null} items are added to the end of
* the vector. If the new size is less than the current size, all
- * components at index newSize
and greater are discarded.
+ * components at index {@code newSize} and greater are discarded.
*
- * @param newSize the new size of this vector
- * @throws ArrayIndexOutOfBoundsException if new size is negative
+ * @param newSize the new size of this vector
+ * @throws ArrayIndexOutOfBoundsException if the new size is negative
*/
public synchronized void setSize(int newSize) {
modCount++;
@@ -252,7 +273,7 @@ public class Vectortrue
if and only if this vector has
+ * @return {@code true} if and only if this vector has
* no components, that is, its size is zero;
- * false
otherwise.
+ * {@code false} otherwise.
*/
public synchronized boolean isEmpty() {
return elementCount == 0;
@@ -281,12 +302,11 @@ public class Vectorsize() - 1
.
- * @exception NoSuchElementException if this vector is empty
+ * @throws NoSuchElementException if this vector is empty
*/
public synchronized E lastElement() {
if (elementCount == 0) {
throw new NoSuchElementException();
}
- return (E)elementData[elementCount - 1];
+ return elementData(elementCount - 1);
}
/**
- * Sets the component at the specified index
of this
+ * Sets the component at the specified {@code index} of this
* vector to be the specified object. The previous component at that
- * position is discarded.0
- * and less than the current size of the vector. index
is shifted downward to have an index one
+ * {@code index} is shifted downward to have an index one
* smaller than the value it had previously. The size of this vector
- * is decreased by 1.0
- * and less than the current size of the vector. index
. Each component in this vector with
- * an index greater or equal to the specified index
is
+ * specified {@code index}. Each component in this vector with
+ * an index greater or equal to the specified {@code index} is
* shifted upward to have an index one greater than the value it had
- * previously. 0
+ * true
if the argument was a component of this
- * vector; false
otherwise.
- * @see List#remove(Object)
- * @see List
+ * @return {@code true} if the argument was a component of this
+ * vector; {@code false} otherwise.
*/
public synchronized boolean removeElement(Object obj) {
modCount++;
@@ -608,13 +621,10 @@ public class Vector(o==null ? get(i)==null : o.equals(get(i)))
(if such
+ * {@code (o==null ? get(i)==null : o.equals(get(i)))} (if such
* an element exists).
*
* @param o element to be removed from this Vector, if present
@@ -763,8 +780,8 @@ public class Vectore1
and
- * e2
are equal if (e1==null ? e2==null :
- * e1.equals(e2))
.) In other words, two Lists are defined to be
+ * Lists are equal. (Two elements {@code e1} and
+ * {@code e2} are equal if {@code (e1==null ? e2==null :
+ * e1.equals(e2))}.) In other words, two Lists are defined to be
* equal if they contain the same elements in the same order.
*
* @param o the Object to be compared for equality with this Vector
@@ -957,10 +974,10 @@ public class Vector(fromIndex < 0 || toIndex > size)
- * @throws IllegalArgumentException endpoint indices out of order
- * (fromIndex > toIndex)
+ * @throws IndexOutOfBoundsException if an endpoint index value is out of range
+ * {@code (fromIndex < 0 || toIndex > size)}
+ * @throws IllegalArgumentException if the endpoint indices are out of order
+ * {@code (fromIndex > toIndex)}
*/
public synchronized List