Vector classes implements growable arrays of Objects.
- * You can access elements in a Vector with an index, just as you
- * can in a built in array, but Vectors can grow and shrink to accommodate
- * more or fewer objects.
- *
- * Vectors try to mantain efficiency in growing by having a
- * capacityIncrement that can be specified at instantiation.
- * When a Vector can no longer hold a new Object, it grows by the amount
- * in capacityIncrement. If this value is 0, the vector doubles in
- * size.
- * - * Vector implements the JDK 1.2 List interface, and is therefore a fully - * compliant Collection object. The iterators are fail-fast - if external - * code structurally modifies the vector, any operation on the iterator will - * then throw a {@link ConcurrentModificationException}. The Vector class is - * fully synchronized, but the iterators are not. So, when iterating over a - * vector, be sure to synchronize on the vector itself. If you don't want the - * expense of synchronization, use ArrayList instead. On the other hand, the - * Enumeration of elements() is not thread-safe, nor is it fail-fast; so it - * can lead to undefined behavior even in a single thread if you modify the - * vector during iteration.
- *
- * Note: Some methods, especially those specified by List, specify throwing
- * {@link IndexOutOfBoundsException}, but it is easier to implement by
- * throwing the subclass {@link ArrayIndexOutOfBoundsException}. Others
- * directly specify this subclass.
- *
- * @author Scott G. Miller
- * @author Bryce McKinlay
- * @author Eric Blake
- *
- * @param fromIndex the index that the returned list should start from
- * (inclusive)
- * @param toIndex the index that the returned list should go to (exclusive)
- * @return a List backed by a subsection of this vector
- * @throws IndexOutOfBoundsException if fromIndex < 0
- * || toIndex > size()
- * @throws IllegalArgumentException if fromIndex > toIndex
- * @see ConcurrentModificationException
- * @since 1.2
- */
- public synchronized List subList(int fromIndex, int toIndex)
- {
- List sub = super.subList(fromIndex, toIndex);
- // We must specify the correct object to synchronize upon, hence the
- // use of a non-public API
- return new Collections.SynchronizedList(this, sub);
- }
-
- /**
- * Removes a range of elements from this list.
- * Does nothing when toIndex is equal to fromIndex.
- *
- * @param fromIndex the index to start deleting from (inclusive)
- * @param toIndex the index to delete up to (exclusive)
- * @throws IndexOutOfBoundsException if fromIndex > toIndex
- */
- // This does not need to be synchronized, because it is only called through
- // clear() of a sublist, and clear() had already synchronized.
- protected void removeRange(int fromIndex, int toIndex)
- {
- int change = toIndex - fromIndex;
- if (change > 0)
- {
- modCount++;
- System.arraycopy(elementData, toIndex, elementData, fromIndex,
- elementCount - toIndex);
- int save = elementCount;
- elementCount -= change;
- Arrays.fill(elementData, elementCount, save, null);
- }
- else if (change < 0)
- throw new IndexOutOfBoundsException();
- }
-
- /**
- * Checks that the index is in the range of possible elements (inclusive).
- *
- * @param index the index to check
- * @throws ArrayIndexOutOfBoundsException if index > size
- */
- private void checkBoundInclusive(int index)
- {
- // Implementation note: we do not check for negative ranges here, since
- // use of a negative index will cause an ArrayIndexOutOfBoundsException
- // with no effort on our part.
- if (index > elementCount)
- throw new ArrayIndexOutOfBoundsException(index + " > " + elementCount);
- }
-
- /**
- * Checks that the index is in the range of existing elements (exclusive).
- *
- * @param index the index to check
- * @throws ArrayIndexOutOfBoundsException if index >= size
- */
- private void checkBoundExclusive(int index)
- {
- // Implementation note: we do not check for negative ranges here, since
- // use of a negative index will cause an ArrayIndexOutOfBoundsException
- // with no effort on our part.
- if (index >= elementCount)
- throw new ArrayIndexOutOfBoundsException(index + " >= " + elementCount);
- }
-}
minCapacity elements can fit within this Vector.
- * If elementData is too small, it is expanded as follows:
- * If the elementCount + capacityIncrement is adequate, that
- * is the new size. If capacityIncrement is non-zero, the
- * candidate size is double the current. If that is not enough, the new
- * size is minCapacity.
- *
- * @param minCapacity the desired minimum capacity, negative values ignored
- */
- public synchronized void ensureCapacity(int minCapacity)
- {
- if (elementData.length >= minCapacity)
- return;
-
- int newCapacity;
- if (capacityIncrement <= 0)
- newCapacity = elementData.length * 2;
- else
- newCapacity = elementData.length + capacityIncrement;
-
- Object[] newArray = new Object[Math.max(newCapacity, minCapacity)];
-
- System.arraycopy(elementData, 0, newArray, 0, elementCount);
- elementData = newArray;
- }
-
- /**
- * Explicitly sets the size of the vector (but not necessarily the size of
- * the internal data array). If the new size is smaller than the old one,
- * old values that don't fit are lost. If the new size is larger than the
- * old one, the vector is padded with null entries.
- *
- * @param newSize The new size of the internal array
- * @throws ArrayIndexOutOfBoundsException if the new size is negative
- */
- public synchronized void setSize(int newSize)
- {
- // Don't bother checking for the case where size() == the capacity of the
- // vector since that is a much less likely case; it's more efficient to
- // not do the check and lose a bit of performance in that infrequent case
- modCount++;
- ensureCapacity(newSize);
- if (newSize < elementCount)
- Arrays.fill(elementData, newSize, elementCount, null);
- elementCount = newSize;
- }
-
- /**
- * Returns the size of the internal data array (not the amount of elements
- * contained in the Vector).
- *
- * @return capacity of the internal data array
- */
- public synchronized int capacity()
- {
- return elementData.length;
- }
-
- /**
- * Returns the number of elements stored in this Vector.
- *
- * @return the number of elements in this Vector
- */
- public synchronized int size()
- {
- return elementCount;
- }
-
- /**
- * Returns true if this Vector is empty, false otherwise
- *
- * @return true if the Vector is empty, false otherwise
- */
- public synchronized boolean isEmpty()
- {
- return elementCount == 0;
- }
-
- /**
- * Returns an Enumeration of the elements of this Vector. The enumeration
- * visits the elements in increasing index order, but is NOT thread-safe.
- *
- * @return an Enumeration
- * @see #iterator()
- */
- // No need to synchronize as the Enumeration is not thread-safe!
- public Enumeration elements()
- {
- return new Enumeration()
- {
- private int i = 0;
-
- public boolean hasMoreElements()
- {
- return i < elementCount;
- }
-
- public Object nextElement()
- {
- if (i >= elementCount)
- throw new NoSuchElementException();
- return elementData[i++];
- }
- };
- }
-
- /**
- * Returns true when elem is contained in this Vector.
- *
- * @param elem the element to check
- * @return true if the object is contained in this Vector, false otherwise
- */
- public boolean contains(Object elem)
- {
- return indexOf(elem, 0) >= 0;
- }
-
- /**
- * Returns the first occurrence of elem in the Vector, or -1 if
- * elem is not found.
- *
- * @param elem the object to search for
- * @return the index of the first occurrence, or -1 if not found
- */
- public int indexOf(Object elem)
- {
- return indexOf(elem, 0);
- }
-
- /**
- * Searches the vector starting at index for object
- * elem and returns the index of the first occurrence of this
- * Object. If the object is not found, or index is larger than the size
- * of the vector, -1 is returned.
- *
- * @param e the Object to search for
- * @param index start searching at this index
- * @return the index of the next occurrence, or -1 if it is not found
- * @throws IndexOutOfBoundsException if index < 0
- */
- public synchronized int indexOf(Object e, int index)
- {
- for (int i = index; i < elementCount; i++)
- if (equals(e, elementData[i]))
- return i;
- return -1;
- }
-
- /**
- * Returns the last index of elem within this Vector, or -1
- * if the object is not within the Vector.
- *
- * @param elem the object to search for
- * @return the last index of the object, or -1 if not found
- */
- public int lastIndexOf(Object elem)
- {
- return lastIndexOf(elem, elementCount - 1);
- }
-
- /**
- * Returns the index of the first occurrence of elem, when
- * searching backwards from index. If the object does not
- * occur in this Vector, or index is less than 0, -1 is returned.
- *
- * @param e the object to search for
- * @param index the index to start searching in reverse from
- * @return the index of the Object if found, -1 otherwise
- * @throws IndexOutOfBoundsException if index >= size()
- */
- public synchronized int lastIndexOf(Object e, int index)
- {
- checkBoundExclusive(index);
- for (int i = index; i >= 0; i--)
- if (equals(e, elementData[i]))
- return i;
- return -1;
- }
-
- /**
- * Returns the Object stored at index.
- *
- * @param index the index of the Object to retrieve
- * @return the object at index
- * @throws ArrayIndexOutOfBoundsException index < 0 || index >= size()
- * @see #get(int)
- */
- public synchronized Object elementAt(int index)
- {
- checkBoundExclusive(index);
- return elementData[index];
- }
-
- /**
- * Returns the first element (index 0) in the Vector.
- *
- * @return the first Object in the Vector
- * @throws NoSuchElementException the Vector is empty
- */
- public synchronized Object firstElement()
- {
- if (elementCount == 0)
- throw new NoSuchElementException();
-
- return elementData[0];
- }
-
- /**
- * Returns the last element in the Vector.
- *
- * @return the last Object in the Vector
- * @throws NoSuchElementException the Vector is empty
- */
- public synchronized Object lastElement()
- {
- if (elementCount == 0)
- throw new NoSuchElementException();
-
- return elementData[elementCount - 1];
- }
-
- /**
- * Changes the element at index to be obj
- *
- * @param obj the object to store
- * @param index the position in the Vector to store the object
- * @throws ArrayIndexOutOfBoundsException the index is out of range
- * @see #set(int, Object)
- */
- public void setElementAt(Object obj, int index)
- {
- set(index, obj);
- }
-
- /**
- * Removes the element at index, and shifts all elements at
- * positions greater than index to their index - 1.
- *
- * @param index the index of the element to remove
- * @throws ArrayIndexOutOfBoundsException index < 0 || index >= size();
- * @see #remove(int)
- */
- public void removeElementAt(int index)
- {
- remove(index);
- }
-
- /**
- * Inserts a new element into the Vector at index. Any elements
- * at or greater than index are shifted up one position.
- *
- * @param obj the object to insert
- * @param index the index at which the object is inserted
- * @throws ArrayIndexOutOfBoundsException index < 0 || index > size()
- * @see #add(int, Object)
- */
- public synchronized void insertElementAt(Object obj, int index)
- {
- checkBoundInclusive(index);
- if (elementCount == elementData.length)
- ensureCapacity(elementCount + 1);
- modCount++;
- System.arraycopy(elementData, index, elementData, index + 1,
- elementCount - index);
- elementCount++;
- elementData[index] = obj;
- }
-
- /**
- * Adds an element to the Vector at the end of the Vector. The vector
- * is increased by ensureCapacity(size() + 1) if needed.
- *
- * @param obj the object to add to the Vector
- */
- public synchronized void addElement(Object obj)
- {
- if (elementCount == elementData.length)
- ensureCapacity(elementCount + 1);
- modCount++;
- elementData[elementCount++] = obj;
- }
-
- /**
- * Removes the first (the lowestindex) occurance of the given object from
- * the Vector. If such a remove was performed (the object was found), true
- * is returned. If there was no such object, false is returned.
- *
- * @param obj the object to remove from the Vector
- * @return true if the Object was in the Vector, false otherwise
- * @see #remove(Object)
- */
- public synchronized boolean removeElement(Object obj)
- {
- int idx = indexOf(obj, 0);
- if (idx >= 0)
- {
- remove(idx);
- return true;
- }
- return false;
- }
-
- /**
- * Removes all elements from the Vector. Note that this does not
- * resize the internal data array.
- *
- * @see #clear()
- */
- public synchronized void removeAllElements()
- {
- if (elementCount == 0)
- return;
-
- modCount++;
- Arrays.fill(elementData, 0, elementCount, null);
- elementCount = 0;
- }
-
- /**
- * Creates a new Vector with the same contents as this one. The clone is
- * shallow; elements are not cloned.
- *
- * @return the clone of this vector
- */
- public synchronized Object clone()
- {
- try
- {
- Vector clone = (Vector) super.clone();
- clone.elementData = (Object[]) elementData.clone();
- return clone;
- }
- catch (CloneNotSupportedException ex)
- {
- // Impossible to get here.
- throw new InternalError(ex.toString());
- }
- }
-
- /**
- * Returns an Object array with the contents of this Vector, in the order
- * they are stored within this Vector. Note that the Object array returned
- * is not the internal data array, and that it holds only the elements
- * within the Vector. This is similar to creating a new Object[] with the
- * size of this Vector, then calling Vector.copyInto(yourArray).
- *
- * @return an Object[] containing the contents of this Vector in order
- * @since 1.2
- */
- public synchronized Object[] toArray()
- {
- Object[] newArray = new Object[elementCount];
- copyInto(newArray);
- return newArray;
- }
-
- /**
- * Returns an array containing the contents of this Vector.
- * If the provided array is large enough, the contents are copied
- * into that array, and a null is placed in the position size().
- * In this manner, you can obtain the size of a Vector by the position
- * of the null element, if you know the vector does not itself contain
- * null entries. If the array is not large enough, reflection is used
- * to create a bigger one of the same runtime type.
- *
- * @param a an array to copy the Vector into if large enough
- * @return an array with the contents of this Vector in order
- * @throws ArrayStoreException the runtime type of the provided array
- * cannot hold the elements of the Vector
- * @throws NullPointerException if a is null
- * @since 1.2
- */
- public synchronized Object[] toArray(Object[] a)
- {
- if (a.length < elementCount)
- a = (Object[]) Array.newInstance(a.getClass().getComponentType(),
- elementCount);
- else if (a.length > elementCount)
- a[elementCount] = null;
- System.arraycopy(elementData, 0, a, 0, elementCount);
- return a;
- }
-
- /**
- * Returns the element at position index.
- *
- * @param index the position from which an element will be retrieved
- * @return the element at that position
- * @throws ArrayIndexOutOfBoundsException index < 0 || index >= size()
- * @since 1.2
- */
- public Object get(int index)
- {
- return elementAt(index);
- }
-
- /**
- * Puts element into the Vector at position index
- * and returns the Object that previously occupied that position.
- *
- * @param index the index within the Vector to place the Object
- * @param element the Object to store in the Vector
- * @return the previous object at the specified index
- * @throws ArrayIndexOutOfBoundsException index < 0 || index >= size()
- * @since 1.2
- */
- public synchronized Object set(int index, Object element)
- {
- checkBoundExclusive(index);
- Object temp = elementData[index];
- elementData[index] = element;
- return temp;
- }
-
- /**
- * Adds an object to the Vector.
- *
- * @param o the element to add to the Vector
- * @return true, as specified by List
- * @since 1.2
- */
- public boolean add(Object o)
- {
- addElement(o);
- return true;
- }
-
- /**
- * Removes the given Object from the Vector. If it exists, true
- * is returned, if not, false is returned.
- *
- * @param o the object to remove from the Vector
- * @return true if the Object existed in the Vector, false otherwise
- * @since 1.2
- */
- public boolean remove(Object o)
- {
- return removeElement(o);
- }
-
- /**
- * Adds an object at the specified index. Elements at or above
- * index are shifted up one position.
- *
- * @param index the index at which to add the element
- * @param element the element to add to the Vector
- * @throws ArrayIndexOutOfBoundsException index < 0 || index > size()
- * @since 1.2
- */
- public void add(int index, Object element)
- {
- insertElementAt(element, index);
- }
-
- /**
- * Removes the element at the specified index, and returns it.
- *
- * @param index the position from which to remove the element
- * @return the object removed
- * @throws ArrayIndexOutOfBoundsException index < 0 || index >= size()
- * @since 1.2
- */
- public synchronized Object remove(int index)
- {
- checkBoundExclusive(index);
- Object temp = elementData[index];
- modCount++;
- elementCount--;
- if (index < elementCount)
- System.arraycopy(elementData, index + 1, elementData, index,
- elementCount - index);
- elementData[elementCount] = null;
- return temp;
- }
-
- /**
- * Clears all elements in the Vector and sets its size to 0.
- */
- public void clear()
- {
- removeAllElements();
- }
-
- /**
- * Returns true if this Vector contains all the elements in c.
- *
- * @param c the collection to compare to
- * @return true if this vector contains all elements of c
- * @throws NullPointerException if c is null
- * @since 1.2
- */
- public synchronized boolean containsAll(Collection c)
- {
- // Here just for the sychronization.
- return super.containsAll(c);
- }
-
- /**
- * Appends all elements of the given collection to the end of this Vector.
- * Behavior is undefined if the collection is modified during this operation
- * (for example, if this == c).
- *
- * @param c the collection to append
- * @return true if this vector changed, in other words c was not empty
- * @throws NullPointerException if c is null
- * @since 1.2
- */
- public synchronized boolean addAll(Collection c)
- {
- return addAll(elementCount, c);
- }
-
- /**
- * Remove from this vector all elements contained in the given collection.
- *
- * @param c the collection to filter out
- * @return true if this vector changed
- * @throws NullPointerException if c is null
- * @since 1.2
- */
- public synchronized boolean removeAll(Collection c)
- {
- if (c == null)
- throw new NullPointerException();
-
- int i;
- int j;
- for (i = 0; i < elementCount; i++)
- if (c.contains(elementData[i]))
- break;
- if (i == elementCount)
- return false;
-
- modCount++;
- for (j = i++; i < elementCount; i++)
- if (! c.contains(elementData[i]))
- elementData[j++] = elementData[i];
- elementCount -= i - j;
- return true;
- }
-
- /**
- * Retain in this vector only the elements contained in the given collection.
- *
- * @param c the collection to filter by
- * @return true if this vector changed
- * @throws NullPointerException if c is null
- * @since 1.2
- */
- public synchronized boolean retainAll(Collection c)
- {
- if (c == null)
- throw new NullPointerException();
-
- int i;
- int j;
- for (i = 0; i < elementCount; i++)
- if (! c.contains(elementData[i]))
- break;
- if (i == elementCount)
- return false;
-
- modCount++;
- for (j = i++; i < elementCount; i++)
- if (c.contains(elementData[i]))
- elementData[j++] = elementData[i];
- elementCount -= i - j;
- return true;
- }
-
- /**
- * Inserts all elements of the given collection at the given index of
- * this Vector. Behavior is undefined if the collection is modified during
- * this operation (for example, if this == c).
- *
- * @param c the collection to append
- * @return true if this vector changed, in other words c was not empty
- * @throws NullPointerException if c is null
- * @throws ArrayIndexOutOfBoundsException index < 0 || index > size()
- * @since 1.2
- */
- public synchronized boolean addAll(int index, Collection c)
- {
- checkBoundInclusive(index);
- Iterator itr = c.iterator();
- int csize = c.size();
-
- modCount++;
- ensureCapacity(elementCount + csize);
- int end = index + csize;
- if (elementCount > 0 && index != elementCount)
- System.arraycopy(elementData, index,
- elementData, end, elementCount - index);
- elementCount += csize;
- for ( ; index < end; index++)
- elementData[index] = itr.next();
- return (csize > 0);
- }
-
- /**
- * Compares this to the given object.
- *
- * @param o the object to compare to
- * @return true if the two are equal
- * @since 1.2
- */
- public synchronized boolean equals(Object o)
- {
- // Here just for the sychronization.
- return super.equals(o);
- }
-
- /**
- * Computes the hashcode of this object.
- *
- * @return the hashcode
- * @since 1.2
- */
- public synchronized int hashCode()
- {
- // Here just for the sychronization.
- return super.hashCode();
- }
-
- /**
- * Returns a string representation of this Vector in the form
- * "[element0, element1, ... elementN]".
- *
- * @return the String representation of this Vector
- */
- public synchronized String toString()
- {
- // Here just for the sychronization.
- return super.toString();
- }
-
- /**
- * Obtain a List view of a subsection of this list, from fromIndex
- * (inclusive) to toIndex (exclusive). If the two indices are equal, the
- * sublist is empty. The returned list is modifiable, and changes in one
- * reflect in the other. If this list is structurally modified in
- * any way other than through the returned list, the result of any subsequent
- * operations on the returned list is undefined.
- *