java.util

Class Vector<T>

Implemented Interfaces:
Cloneable, Collection<E>, Iterable<E>, List<E>, RandomAccess, Serializable
Known Direct Subclasses:
Stack<T>

public class Vector<T>
extends AbstractList<E>
implements List<E>, 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 T[]
elementData
The internal array used to hold members of a Vector.

Fields inherited from class java.util.AbstractList<E>

modCount

Constructor Summary

Vector()
Constructs an empty vector with an initial size of 10, and a capacity increment of 0
Vector(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

S[] toArray(S[] a)
Returns an array containing the contents of this Vector.
boolean
add(T o)
Adds an object to the Vector.
void
add(int index, T element)
Adds an object at the specified index.
boolean
addAll(T> c)
Appends all elements of the given collection to the end of this Vector.
boolean
addAll(int index, 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
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
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.
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<E>

add, add, addAll, clear, equals, get, hashCode, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange, set, subList

Methods inherited from class java.util.AbstractCollection<E>

T[] toArray, add, addAll, clear, contains, containsAll, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toString

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

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.

elementCount

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

elementData

protected T[] 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.

Constructor Details

Vector

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

Vector

public Vector(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)
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

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

Method Details

S[] toArray

public  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.
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

add

public boolean add(T o)
Adds an object to the Vector.
Parameters:
o - the element to add to the Vector
Returns:
true, as specified by List
Since:
1.2

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.
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

addAll

public boolean addAll(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).
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

addAll

public boolean addAll(int index,
                      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).
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
ArrayIndexOutOfBoundsException - index < 0 || index > size()
Since:
1.2

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

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

clear

public void clear()
Clears all elements in the Vector and sets its size to 0.
Specified by:
clear in interface List<E>
clear in interface Collection<E>
Overrides:
clear in interface AbstractList<E>

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 interface Object
Returns:
the clone of this vector

contains

public boolean contains(Object elem)
Returns true when elem is contained in this Vector.
Specified by:
contains in interface List<E>
contains in interface Collection<E>
Overrides:
contains in interface AbstractCollection<E>
Parameters:
elem - the element to check
Returns:
true if the object is contained in this Vector, false otherwise

containsAll

public boolean containsAll(Collection c)
Returns true if this Vector contains all the elements in c.
Specified by:
containsAll in interface List<E>
containsAll in interface Collection<E>
Overrides:
containsAll in interface AbstractCollection<E>
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

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[])

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)

elements

public Enumeration 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:
iterator()

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

equals

public boolean equals(Object o)
Compares this to the given object.
Specified by:
equals in interface List<E>
equals in interface Collection<E>
Overrides:
equals in interface AbstractList<E>
Parameters:
o - the object to compare to
Returns:
true if the two are equal
Since:
1.2

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

get

public T get(int index)
Returns the element at position index.
Specified by:
get in interface List<E>
Overrides:
get in interface AbstractList<E>
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

hashCode

public int hashCode()
Computes the hashcode of this object.
Specified by:
hashCode in interface List<E>
hashCode in interface Collection<E>
Overrides:
hashCode in interface AbstractList<E>
Returns:
the hashcode
Since:
1.2

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<E>
Overrides:
indexOf in interface AbstractList<E>
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

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)

isEmpty

public boolean isEmpty()
Returns true if this Vector is empty, false otherwise
Specified by:
isEmpty in interface List<E>
isEmpty in interface Collection<E>
Overrides:
isEmpty in interface AbstractCollection<E>
Returns:
true if the Vector is empty, false otherwise

lastElement

public T lastElement()
Returns the last element in the Vector.
Returns:
the last Object in the Vector
Throws:
NoSuchElementException - the Vector is empty

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<E>
Overrides:
lastIndexOf in interface AbstractList<E>
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()

remove

public T remove(int index)
Removes the element at the specified index, and returns it.
Specified by:
remove in interface List<E>
Overrides:
remove in interface AbstractList<E>
Parameters:
index - the position from which to remove the element
Returns:
the object removed
Throws:
ArrayIndexOutOfBoundsException - index < 0 || index >= size()
Since:
1.2

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 List<E>
remove in interface Collection<E>
Overrides:
remove in interface AbstractCollection<E>
Parameters:
o - the object to remove from the Vector
Returns:
true if the Object existed in the Vector, false otherwise
Since:
1.2

removeAll

public boolean removeAll(Collection c)
Remove from this vector all elements contained in the given collection.
Specified by:
removeAll in interface List<E>
removeAll in interface Collection<E>
Overrides:
removeAll in interface AbstractCollection<E>
Parameters:
c - the collection to filter out
Returns:
true if this vector changed
Throws:
NullPointerException - if c is null
Since:
1.2

removeAllElements

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

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

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)

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 interface AbstractList<E>
Parameters:
fromIndex - the index to start deleting from (inclusive)
toIndex - the index to delete up to (exclusive)
Throws:
IndexOutOfBoundsException - if fromIndex > toIndex

retainAll

public boolean retainAll(Collection c)
Retain in this vector only the elements contained in the given collection.
Specified by:
retainAll in interface List<E>
retainAll in interface Collection<E>
Overrides:
retainAll in interface AbstractCollection<E>
Parameters:
c - the collection to filter by
Returns:
true if this vector changed
Throws:
NullPointerException - if c is null
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.
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

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)

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

size

public int size()
Returns the number of elements stored in this Vector.
Specified by:
size in interface List<E>
size in interface Collection<E>
Overrides:
size in interface AbstractCollection<E>
Returns:
the number of elements in this Vector

subList

public List 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<E>
Overrides:
subList in interface AbstractList<E>
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

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 List<E>
toArray in interface Collection<E>
Overrides:
toArray in interface AbstractCollection<E>
Returns:
an Object[] containing the contents of this Vector in order
Since:
1.2

toString

public String toString()
Returns a string representation of this Vector in the form "[element0, element1, ... elementN]".
Overrides:
toString in interface AbstractCollection<E>
Returns:
the String representation of this Vector

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.

Vector.java -- Class that provides growable arrays. Copyright (C) 1998, 1999, 2000, 2001, 2004, 2005, 2006, Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath 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 for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.