--- jsr166/src/main/java/util/Vector.java 2006/05/28 23:36:29 1.13
+++ jsr166/src/main/java/util/Vector.java 2006/06/25 19:58:14 1.15
@@ -8,18 +8,18 @@
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.
*
@@ -36,7 +36,7 @@ package java.util;
*
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.
@@ -63,18 +63,18 @@ public class Vector
/**
* The array buffer into which the components of the vector are
* stored. The capacity of the vector is the length of this array buffer,
- * and is at least large enough to contain all the vector's elements.
+ * 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 +100,8 @@ public class Vector
* @param initialCapacity the initial capacity of the vector
* @param capacityIncrement the amount by which the capacity is
* increased when the vector overflows
- * @exception IllegalArgumentException if the specified initial capacity
- * is negative
+ * @throws IllegalArgumentException if the specified initial capacity
+ * is negative
*/
public Vector(int initialCapacity, int capacityIncrement) {
super();
@@ -117,8 +117,8 @@ public class Vector
* with its capacity increment equal to zero.
*
* @param initialCapacity the initial capacity of the vector
- * @exception IllegalArgumentException if the specified initial capacity
- * is negative
+ * @throws IllegalArgumentException if the specified initial capacity
+ * is negative
*/
public Vector(int initialCapacity) {
this(initialCapacity, 0);
@@ -126,7 +126,7 @@ public class Vector
/**
* Constructs an empty vector so that its internal data array
- * has size 10 and its standard capacity increment is
+ * has size {@code 10} and its standard capacity increment is
* zero.
*/
public Vector() {
@@ -153,8 +153,8 @@ public class Vector
/**
* Copies the components of this vector into the specified array.
- * The item at index k in this vector is copied into
- * component k of anArray.
+ * The item at index {@code k} in this vector is copied into
+ * component {@code k} of {@code anArray}.
*
* @param anArray the array into which the components get copied
* @throws NullPointerException if the given array is null
@@ -172,7 +172,7 @@ public class Vector
* Trims the capacity of this vector to be the vector's current
* size. If the capacity of this vector is larger than its current
* size, then the capacity is changed to equal the size by replacing
- * its internal data array, kept in the field elementData,
+ * its internal data array, kept in the field {@code elementData},
* with a smaller one. An application can use this operation to
* minimize the storage of a vector.
*/
@@ -190,14 +190,14 @@ public class Vector
* the minimum capacity argument.
*
* 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 +212,7 @@ public class Vector
* method for ensuring capacity without incurring the cost of an
* extra synchronization.
*
- * @see java.util.Vector#ensureCapacity(int)
+ * @see #ensureCapacity(int)
*/
private void ensureCapacityHelper(int minCapacity) {
int oldCapacity = elementData.length;
@@ -229,9 +229,9 @@ public class Vector
/**
* Sets the size of this vector. If the new size is greater than the
- * current size, new null
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
@@ -252,7 +252,7 @@ public class Vector
* Returns the current capacity of this vector.
*
* @return the current capacity (the length of its internal
- * data array, kept in the field elementData
+ * data array, kept in the field {@code elementData}
* of this vector)
*/
public synchronized int capacity() {
@@ -271,9 +271,9 @@ public class Vector
/**
* Tests if this vector has no components.
*
- * @return true
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 +281,11 @@ public class Vector
/**
* Returns an enumeration of the components of this vector. The
- * returned Enumeration object will generate all items in
- * this vector. The first item generated is the item at index 0,
- * then the item at index 1, and so on.
+ * returned {@code Enumeration} object will generate all items in
+ * this vector. The first item generated is the item at index {@code 0},
+ * then the item at index {@code 1}, and so on.
*
* @return an enumeration of the components of this vector
- * @see Enumeration
* @see Iterator
*/
public Enumeration elements() {
@@ -309,13 +308,13 @@ public class Vector
}
/**
- * Returns true if this vector contains the specified element.
- * More formally, returns true if and only if this vector
- * contains at least one element e such that
+ * Returns {@code true} if this vector contains the specified element.
+ * More formally, returns {@code true} if and only if this vector
+ * contains at least one element {@code e} such that
* (o==null ? e==null : o.equals(e)).
*
* @param o element whose presence in this vector is to be tested
- * @return true if this vector contains the specified element
+ * @return {@code true} if this vector contains the specified element
*/
public boolean contains(Object o) {
return indexOf(o, 0) >= 0;
@@ -324,7 +323,7 @@ public class Vector
/**
* Returns the index of the first occurrence of the specified element
* in this vector, or -1 if this vector does not contain the element.
- * More formally, returns the lowest index i such that
+ * More formally, returns the lowest index {@code i} such that
* (o==null ? get(i)==null : o.equals(get(i))),
* or -1 if there is no such index.
*
@@ -338,17 +337,17 @@ public class Vector
/**
* Returns the index of the first occurrence of the specified element in
- * this vector, searching forwards from index, or returns -1 if
+ * this vector, searching forwards from {@code index}, or returns -1 if
* the element is not found.
- * More formally, returns the lowest index i such that
+ * More formally, returns the lowest index {@code i} such that
* (i >= index && (o==null ? get(i)==null : o.equals(get(i)))),
* or -1 if there is no such index.
*
* @param o element to search for
* @param index index to start searching from
* @return the index of the first occurrence of the element in
- * this vector at position index or later in the vector;
- * -1 if the element is not found.
+ * this vector at position {@code index} or later in the vector;
+ * {@code -1} if the element is not found.
* @throws IndexOutOfBoundsException if the specified index is negative
* @see Object#equals(Object)
*/
@@ -368,7 +367,7 @@ public class Vector
/**
* Returns the index of the last occurrence of the specified element
* in this vector, or -1 if this vector does not contain the element.
- * More formally, returns the highest index i such that
+ * More formally, returns the highest index {@code i} such that
* (o==null ? get(i)==null : o.equals(get(i))),
* or -1 if there is no such index.
*
@@ -382,16 +381,16 @@ public class Vector
/**
* Returns the index of the last occurrence of the specified element in
- * this vector, searching backwards from index, or returns -1 if
+ * this vector, searching backwards from {@code index}, or returns -1 if
* the element is not found.
- * More formally, returns the highest index i such that
+ * More formally, returns the highest index {@code i} such that
* (i <= index && (o==null ? get(i)==null : o.equals(get(i)))),
* or -1 if there is no such index.
*
* @param o element to search for
* @param index index to start searching backwards from
* @return the index of the last occurrence of the element at position
- * less than or equal to index in this vector;
+ * less than or equal to {@code index} in this vector;
* -1 if the element is not found.
* @throws IndexOutOfBoundsException if the specified index is greater
* than or equal to the current size of this vector
@@ -413,18 +412,15 @@ public class Vector
}
/**
- * Returns the component at the specified index.
+ * 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) {
@@ -435,11 +431,11 @@ public class Vector
}
/**
- * 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) {
@@ -453,7 +449,7 @@ public class Vector
*
* @return the last component of the vector, i.e., the component at index
* size() - 1
.
- * @exception NoSuchElementException if this vector is empty
+ * @throws NoSuchElementException if this vector is empty
*/
public synchronized E lastElement() {
if (elementCount == 0) {
@@ -463,11 +459,11 @@ public class Vector
}
/**
- * 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.
*
- * The index must be a value greater than or equal to 0
+ * 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
@@ -478,7 +474,7 @@ public class Vector
*
* @param obj what the component is to be set to
* @param index the specified index
- * @exception ArrayIndexOutOfBoundsException if the index was invalid
+ * @throws ArrayIndexOutOfBoundsException if the index was invalid
* @see #size()
* @see List
* @see #set(int, java.lang.Object)
@@ -494,14 +490,14 @@ public class Vector
/**
* Deletes the component at the specified index. Each component in
* this vector with an index greater or equal to the specified
- * 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.
+ * is decreased by {@code 1}.
*
- * The index must be a value greater than or equal to 0
- * and less than the current size of the vector.
+ *
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
+ *
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.
*
@@ -530,17 +526,17 @@ public class Vector
/**
* Inserts the specified object as a component in this vector at the
- * specified 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.
+ * previously.
*
- * The index must be a value greater than or equal to 0
+ *
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
+ *
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.
*
@@ -592,8 +588,8 @@ public class Vector
* method (which is part of the List interface).
*
* @param obj the component to be removed
- * @return true
if the argument was a component of this
- * vector; false
otherwise.
+ * @return {@code true} if the argument was a component of this
+ * vector; {@code false} otherwise.
* @see List#remove(Object)
* @see List
*/
@@ -628,7 +624,7 @@ public class Vector
/**
* Returns a clone of this vector. The copy will contain a
* reference to a clone of the internal data array, not a reference
- * to the original internal data array of this Vector object.
+ * to the original internal data array of this {@code Vector} object.
*
* @return a clone of this vector
*/
@@ -731,7 +727,7 @@ public class Vector
* Appends the specified element to the end of this Vector.
*
* @param e element to be appended to this Vector
- * @return true (as specified by {@link Collection#add})
+ * @return {@code true} (as specified by {@link Collection#add})
* @since 1.2
*/
public synchronized boolean add(E e) {
@@ -745,7 +741,7 @@ public class Vector
* Removes the first occurrence of the specified element in this Vector
* If the Vector does not contain the element, it is unchanged. More
* formally, removes the element with the lowest index i such that
- * (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
@@ -832,7 +828,7 @@ public class Vector
* specified Collection is this Vector, and this Vector is nonempty.)
*
* @param c elements to be inserted into this Vector
- * @return true if this Vector changed as a result of the call
+ * @return {@code true} if this Vector changed as a result of the call
* @throws NullPointerException if the specified collection is null
* @since 1.2
*/
@@ -895,7 +891,7 @@ public class Vector
* @param index index at which to insert the first element from the
* specified collection
* @param c elements to be inserted into this Vector
- * @return true if this Vector changed as a result of the call
+ * @return {@code true} if this Vector changed as a result of the call
* @exception ArrayIndexOutOfBoundsException index out of range (index
* < 0 || index > size())
* @throws NullPointerException if the specified collection is null
@@ -924,9 +920,9 @@ public class Vector
* Compares the specified Object with this Vector for equality. Returns
* true if and only if the specified Object is also a List, both Lists
* have the same size, and all corresponding pairs of elements in the two
- * Lists are equal. (Two elements e1
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
@@ -974,7 +970,7 @@ public class Vector
}
/**
- * Save the state of the Vector instance to a stream (that
+ * Save the state of the {@code Vector} instance to a stream (that
* is, serialize it). This method is present merely for synchronization.
* It just calls the default writeObject method.
*/