java.util
Class Vector<T>

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by java.util.AbstractList<T>
          extended by java.util.Vector<T>
All Implemented Interfaces:
Serializable, Cloneable, Iterable<T>, Collection<T>, List<T>, RandomAccess
Direct Known Subclasses:
Stack

public class Vector<T>
extends AbstractList<T>
implements List<T>, RandomAccess, Cloneable, Serializable

The 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 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 IndexOutOfBoundsException, but it is easier to implement by throwing the subclass ArrayIndexOutOfBoundsException. Others directly specify this subclass.

Since:
1.0
See Also:
Collection, List, ArrayList, LinkedList, Serialized Form

Field Summary
protected  int capacityIncrement
          The amount the Vector's internal array should be increased in size when a new element is added that exceeds the current size of the array, or when ensureCapacity(int) is called.
protected  int elementCount
          The number of elements currently in the vector, also returned by size().
protected  Object[] elementData
          The internal array used to hold members of a Vector.
 
Fields inherited from class java.util.AbstractList
modCount
 
Constructor Summary
Vector()
          Constructs an empty vector with an initial size of 10, and a capacity increment of 0
Vector(Collection<? extends T> c)
          Constructs a vector containing the contents of Collection, in the order given by the collection.
Vector(int initialCapacity)
          Constructs a Vector with the initial capacity specified, and a capacity increment of 0 (double in size).
Vector(int initialCapacity, int capacityIncrement)
          Constructs a Vector with the initial capacity and capacity increment specified.
 
Method Summary
 void add(int index, T element)
          Adds an object at the specified index.
 boolean add(T o)
          Adds an object to the Vector.
 boolean addAll(Collection<? extends T> c)
          Appends all elements of the given collection to the end of this Vector.
 boolean addAll(int index, Collection<? extends T> c)
          Inserts all elements of the given collection at the given index of this Vector.
 void addElement(T obj)
          Adds an element to the Vector at the end of the Vector.
 int capacity()
          Returns the size of the internal data array (not the amount of elements contained in the Vector).
 void clear()
          Clears all elements in the Vector and sets its size to 0.
 Object clone()
          Creates a new Vector with the same contents as this one.
 boolean contains(Object elem)
          Returns true when elem is contained in this Vector.
 boolean containsAll(Collection<?> c)
          Returns true if this Vector contains all the elements in c.
 void copyInto(Object[] a)
          Copies the contents of the Vector into the provided array.
 T elementAt(int index)
          Returns the Object stored at index.
 Enumeration<T> elements()
          Returns an Enumeration of the elements of this Vector.
 void ensureCapacity(int minCapacity)
          Ensures that minCapacity elements can fit within this Vector.
 boolean equals(Object o)
          Compares this to the given object.
 T firstElement()
          Returns the first element (index 0) in the Vector.
 T get(int index)
          Returns the element at position index.
 int hashCode()
          Computes the hashcode of this object.
 int indexOf(Object elem)
          Returns the first occurrence of elem in the Vector, or -1 if elem is not found.
 int indexOf(Object e, int index)
          Searches the vector starting at index for object elem and returns the index of the first occurrence of this Object.
 void insertElementAt(T obj, int index)
          Inserts a new element into the Vector at index.
 boolean isEmpty()
          Returns true if this Vector is empty, false otherwise
 T lastElement()
          Returns the last element in the Vector.
 int lastIndexOf(Object elem)
          Returns the last index of elem within this Vector, or -1 if the object is not within the Vector.
 int lastIndexOf(Object e, int index)
          Returns the index of the first occurrence of elem, when searching backwards from index.
 T remove(int index)
          Removes the element at the specified index, and returns it.
 boolean remove(Object o)
          Removes the given Object from the Vector.
 boolean removeAll(Collection<?> c)
          Remove from this vector all elements contained in the given collection.
 void removeAllElements()
          Removes all elements from the Vector.
 boolean removeElement(Object obj)
          Removes the first (the lowest index) occurrence of the given object from the Vector.
 void removeElementAt(int index)
          Removes the element at index, and shifts all elements at positions greater than index to their index - 1.
protected  void removeRange(int fromIndex, int toIndex)
          Removes a range of elements from this list.
 boolean retainAll(Collection<?> c)
          Retain in this vector only the elements contained in the given collection.
 T set(int index, T element)
          Puts element into the Vector at position index and returns the Object that previously occupied that position.
 void setElementAt(T obj, int index)
          Changes the element at index to be obj
 void setSize(int newSize)
          Explicitly sets the size of the vector (but not necessarily the size of the internal data array).
 int size()
          Returns the number of elements stored in this Vector.
 List<T> subList(int fromIndex, int toIndex)
          Obtain a List view of a subsection of this list, from fromIndex (inclusive) to toIndex (exclusive).
 Object[] toArray()
          Returns an Object array with the contents of this Vector, in the order they are stored within this Vector.
<S> S[]
toArray(S[] a)
          Returns an array containing the contents of this Vector.
 String toString()
          Returns a string representation of this Vector in the form "[element0, element1, ... elementN]".
 void trimToSize()
          Trims the Vector down to size.
 
Methods inherited from class java.util.AbstractList
iterator, listIterator, listIterator
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.List
iterator, listIterator, listIterator
 

Field Detail

elementData

protected Object[] elementData
The internal array used to hold members of a Vector. The elements are in positions 0 through elementCount - 1, and all remaining slots are null.


elementCount

protected int elementCount
The number of elements currently in the vector, also returned by size().


capacityIncrement

protected int capacityIncrement
The amount the Vector's internal array should be increased in size when a new element is added that exceeds the current size of the array, or when ensureCapacity(int) is called. If <= 0, the vector just doubles in size.

Constructor Detail

Vector

public Vector()
Constructs an empty vector with an initial size of 10, and a capacity increment of 0


Vector

public Vector(Collection<? extends T> c)
Constructs a vector containing the contents of Collection, in the order given by the collection.

Parameters:
c - collection of elements to add to the new vector
Throws:
NullPointerException - if c is null
Since:
1.2

Vector

public Vector(int initialCapacity,
              int capacityIncrement)
Constructs a Vector with the initial capacity and capacity increment specified.

Parameters:
initialCapacity - the initial size of the Vector's internal array
capacityIncrement - the amount the internal array should be increased by when necessary, 0 to double the size
Throws:
IllegalArgumentException - if initialCapacity < 0

Vector

public Vector(int initialCapacity)
Constructs a Vector with the initial capacity specified, and a capacity increment of 0 (double in size).

Parameters:
initialCapacity - the initial size of the Vector's internal array
Throws:
IllegalArgumentException - if initialCapacity < 0
Method Detail

copyInto

public void copyInto(Object[] a)
Copies the contents of the Vector into the provided array. If the array is too small to fit all the elements in the Vector, an IndexOutOfBoundsException is thrown without modifying the array. Old elements in the array are overwritten by the new elements.

Parameters:
a - target array for the copy
Throws:
IndexOutOfBoundsException - the array is not large enough
NullPointerException - the array is null
See Also:
toArray(Object[])

trimToSize

public void trimToSize()
Trims the Vector down to size. If the internal data array is larger than the number of Objects its holding, a new array is constructed that precisely holds the elements. Otherwise this does nothing.


ensureCapacity

public void ensureCapacity(int minCapacity)
Ensures that 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.

Parameters:
minCapacity - the desired minimum capacity, negative values ignored

setSize

public void setSize(int newSize)
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.

Parameters:
newSize - The new size of the internal array
Throws:
ArrayIndexOutOfBoundsException - if the new size is negative

capacity

public int capacity()
Returns the size of the internal data array (not the amount of elements contained in the Vector).

Returns:
capacity of the internal data array

size

public int size()
Returns the number of elements stored in this Vector.

Specified by:
size in interface Collection<T>
Specified by:
size in interface List<T>
Specified by:
size in class AbstractCollection<T>
Returns:
the number of elements in this Vector

isEmpty

public boolean isEmpty()
Returns true if this Vector is empty, false otherwise

Specified by:
isEmpty in interface Collection<T>
Specified by:
isEmpty in interface List<T>
Overrides:
isEmpty in class AbstractCollection<T>
Returns:
true if the Vector is empty, false otherwise
See Also:
AbstractCollection.size()

elements

public Enumeration<T> elements()
Returns an Enumeration of the elements of this Vector. The enumeration visits the elements in increasing index order, but is NOT thread-safe.

Returns:
an Enumeration
See Also:
AbstractList.iterator()

contains

public boolean contains(Object elem)
Returns true when elem is contained in this Vector.

Specified by:
contains in interface Collection<T>
Specified by:
contains in interface List<T>
Overrides:
contains in class AbstractCollection<T>
Parameters:
elem - the element to check
Returns:
true if the object is contained in this Vector, false otherwise

indexOf

public int indexOf(Object elem)
Returns the first occurrence of elem in the Vector, or -1 if elem is not found.

Specified by:
indexOf in interface List<T>
Overrides:
indexOf in class AbstractList<T>
Parameters:
elem - the object to search for
Returns:
the index of the first occurrence, or -1 if not found

indexOf

public int indexOf(Object e,
                   int index)
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.

Parameters:
e - the Object to search for
index - start searching at this index
Returns:
the index of the next occurrence, or -1 if it is not found
Throws:
IndexOutOfBoundsException - if index < 0

lastIndexOf

public int lastIndexOf(Object elem)
Returns the last index of elem within this Vector, or -1 if the object is not within the Vector.

Specified by:
lastIndexOf in interface List<T>
Overrides:
lastIndexOf in class AbstractList<T>
Parameters:
elem - the object to search for
Returns:
the last index of the object, or -1 if not found

lastIndexOf

public int lastIndexOf(Object e,
                       int index)
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.

Parameters:
e - the object to search for
index - the index to start searching in reverse from
Returns:
the index of the Object if found, -1 otherwise
Throws:
IndexOutOfBoundsException - if index >= size()

elementAt

public T elementAt(int index)
Returns the Object stored at index.

Parameters:
index - the index of the Object to retrieve
Returns:
the object at index
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index >= size()
See Also:
get(int)

firstElement

public T firstElement()
Returns the first element (index 0) in the Vector.

Returns:
the first Object in the Vector
Throws:
NoSuchElementException - the Vector is empty

lastElement

public T lastElement()
Returns the last element in the Vector.

Returns:
the last Object in the Vector
Throws:
NoSuchElementException - the Vector is empty

setElementAt

public void setElementAt(T obj,
                         int index)
Changes the element at index to be obj

Parameters:
obj - the object to store
index - the position in the Vector to store the object
Throws:
ArrayIndexOutOfBoundsException - the index is out of range
See Also:
set(int, Object)

removeElementAt

public void removeElementAt(int index)
Removes the element at index, and shifts all elements at positions greater than index to their index - 1.

Parameters:
index - the index of the element to remove
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index >= size();
See Also:
remove(int)

insertElementAt

public void insertElementAt(T obj,
                            int index)
Inserts a new element into the Vector at index. Any elements at or greater than index are shifted up one position.

Parameters:
obj - the object to insert
index - the index at which the object is inserted
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index > size()
See Also:
add(int, Object)

addElement

public void addElement(T obj)
Adds an element to the Vector at the end of the Vector. The vector is increased by ensureCapacity(size() + 1) if needed.

Parameters:
obj - the object to add to the Vector

removeElement

public boolean removeElement(Object obj)
Removes the first (the lowest index) occurrence 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.

Parameters:
obj - the object to remove from the Vector
Returns:
true if the Object was in the Vector, false otherwise
See Also:
remove(Object)

removeAllElements

public void removeAllElements()
Removes all elements from the Vector. Note that this does not resize the internal data array.

See Also:
clear()

clone

public Object clone()
Creates a new Vector with the same contents as this one. The clone is shallow; elements are not cloned.

Overrides:
clone in class Object
Returns:
the clone of this vector
See Also:
Cloneable

toArray

public Object[] toArray()
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).

Specified by:
toArray in interface Collection<T>
Specified by:
toArray in interface List<T>
Overrides:
toArray in class AbstractCollection<T>
Returns:
an Object[] containing the contents of this Vector in order
Since:
1.2

toArray

public <S> S[] toArray(S[] a)
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.

Specified by:
toArray in interface Collection<T>
Specified by:
toArray in interface List<T>
Overrides:
toArray in class AbstractCollection<T>
Parameters:
a - an array to copy the Vector into if large enough
Returns:
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
NullPointerException - if a is null
Since:
1.2

get

public T get(int index)
Returns the element at position index.

Specified by:
get in interface List<T>
Specified by:
get in class AbstractList<T>
Parameters:
index - the position from which an element will be retrieved
Returns:
the element at that position
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index >= size()
Since:
1.2

set

public T set(int index,
             T element)
Puts element into the Vector at position index and returns the Object that previously occupied that position.

Specified by:
set in interface List<T>
Overrides:
set in class AbstractList<T>
Parameters:
index - the index within the Vector to place the Object
element - the Object to store in the Vector
Returns:
the previous object at the specified index
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index >= size()
Since:
1.2

add

public boolean add(T o)
Adds an object to the Vector.

Specified by:
add in interface Collection<T>
Specified by:
add in interface List<T>
Overrides:
add in class AbstractList<T>
Parameters:
o - the element to add to the Vector
Returns:
true, as specified by List
Since:
1.2
See Also:
AbstractList.add(int, Object)

remove

public boolean remove(Object o)
Removes the given Object from the Vector. If it exists, true is returned, if not, false is returned.

Specified by:
remove in interface Collection<T>
Specified by:
remove in interface List<T>
Overrides:
remove in class AbstractCollection<T>
Parameters:
o - the object to remove from the Vector
Returns:
true if the Object existed in the Vector, false otherwise
Since:
1.2
See Also:
Iterator.remove()

add

public void add(int index,
                T element)
Adds an object at the specified index. Elements at or above index are shifted up one position.

Specified by:
add in interface List<T>
Overrides:
add in class AbstractList<T>
Parameters:
index - the index at which to add the element
element - the element to add to the Vector
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index > size()
Since:
1.2
See Also:
AbstractList.modCount

remove

public T remove(int index)
Removes the element at the specified index, and returns it.

Specified by:
remove in interface List<T>
Overrides:
remove in class AbstractList<T>
Parameters:
index - the position from which to remove the element
Returns:
the object removed
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index >= size()
Since:
1.2
See Also:
AbstractList.modCount

clear

public void clear()
Clears all elements in the Vector and sets its size to 0.

Specified by:
clear in interface Collection<T>
Specified by:
clear in interface List<T>
Overrides:
clear in class AbstractList<T>
See Also:
AbstractList.remove(int), AbstractList.removeRange(int, int)

containsAll

public boolean containsAll(Collection<?> c)
Returns true if this Vector contains all the elements in c.

Specified by:
containsAll in interface Collection<T>
Specified by:
containsAll in interface List<T>
Overrides:
containsAll in class AbstractCollection<T>
Parameters:
c - the collection to compare to
Returns:
true if this vector contains all elements of c
Throws:
NullPointerException - if c is null
Since:
1.2
See Also:
AbstractCollection.contains(Object)

addAll

public boolean addAll(Collection<? extends T> 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).

Specified by:
addAll in interface Collection<T>
Specified by:
addAll in interface List<T>
Overrides:
addAll in class AbstractCollection<T>
Parameters:
c - the collection to append
Returns:
true if this vector changed, in other words c was not empty
Throws:
NullPointerException - if c is null
Since:
1.2
See Also:
AbstractCollection.add(Object)

removeAll

public boolean removeAll(Collection<?> c)
Remove from this vector all elements contained in the given collection.

Specified by:
removeAll in interface Collection<T>
Specified by:
removeAll in interface List<T>
Overrides:
removeAll in class AbstractCollection<T>
Parameters:
c - the collection to filter out
Returns:
true if this vector changed
Throws:
NullPointerException - if c is null
Since:
1.2
See Also:
Iterator.remove()

retainAll

public boolean retainAll(Collection<?> c)
Retain in this vector only the elements contained in the given collection.

Specified by:
retainAll in interface Collection<T>
Specified by:
retainAll in interface List<T>
Overrides:
retainAll in class AbstractCollection<T>
Parameters:
c - the collection to filter by
Returns:
true if this vector changed
Throws:
NullPointerException - if c is null
Since:
1.2
See Also:
Iterator.remove()

addAll

public boolean addAll(int index,
                      Collection<? extends T> c)
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).

Specified by:
addAll in interface List<T>
Overrides:
addAll in class AbstractList<T>
Parameters:
c - the collection to append
index - the location to insert the collection
Returns:
true if this vector changed, in other words c was not empty
Throws:
NullPointerException - if c is null
ArrayIndexOutOfBoundsException - index < 0 || index > size()
Since:
1.2
See Also:
AbstractList.add(int, Object)

equals

public boolean equals(Object o)
Compares this to the given object.

Specified by:
equals in interface Collection<T>
Specified by:
equals in interface List<T>
Overrides:
equals in class AbstractList<T>
Parameters:
o - the object to compare to
Returns:
true if the two are equal
Since:
1.2
See Also:
Object.equals(Object), AbstractList.hashCode()

hashCode

public int hashCode()
Computes the hashcode of this object.

Specified by:
hashCode in interface Collection<T>
Specified by:
hashCode in interface List<T>
Overrides:
hashCode in class AbstractList<T>
Returns:
the hashcode
Since:
1.2
See Also:
Object.hashCode(), AbstractList.equals(Object)

toString

public String toString()
Returns a string representation of this Vector in the form "[element0, element1, ... elementN]".

Overrides:
toString in class AbstractCollection<T>
Returns:
the String representation of this Vector
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

subList

public List<T> subList(int fromIndex,
                       int toIndex)
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.

Specified by:
subList in interface List<T>
Overrides:
subList in class AbstractList<T>
Parameters:
fromIndex - the index that the returned list should start from (inclusive)
toIndex - the index that the returned list should go to (exclusive)
Returns:
a List backed by a subsection of this vector
Throws:
IndexOutOfBoundsException - if fromIndex < 0 || toIndex > size()
IllegalArgumentException - if fromIndex > toIndex
Since:
1.2
See Also:
ConcurrentModificationException

removeRange

protected void removeRange(int fromIndex,
                           int toIndex)
Removes a range of elements from this list. Does nothing when toIndex is equal to fromIndex.

Overrides:
removeRange in class AbstractList<T>
Parameters:
fromIndex - the index to start deleting from (inclusive)
toIndex - the index to delete up to (exclusive)
Throws:
IndexOutOfBoundsException - if fromIndex > toIndex