java.util
Class Vector

java.lang.Object
  java.util.AbstractCollection
      java.util.AbstractList
          java.util.Vector

All Implemented Interfaces:

Collection, List

public class Vector
extends AbstractList
implements List

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

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 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, Object element) Adds an object at the specified index.
boolean	add(Object o) Adds an object to the Vector.
boolean	addAll(Collection c) Appends all elements of the given collection to the end of this Vector.
boolean	addAll(int index, Collection c) Inserts all elements of the given collection at the given index of this Vector.
void	addElement(Object 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.
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.
Object	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.
Object	firstElement() Returns the first element (index 0) in the Vector.
Object	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(Object obj, int index) Inserts a new element into the Vector at index.
boolean	isEmpty() Returns true if this Vector is empty, false otherwise
Object	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.
Object	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 lowestindex) occurance 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.
Object	set(int index, Object element) Puts element into the Vector at position index and returns the Object that previously occupied that position.
void	setElementAt(Object 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.
Object[]	toArray(Object[] a) Returns an array containing the contents of this Vector.
String	toString() Returns a string representation of this Vector in the form "[element0, element1, ...
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

clone, 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 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

Specified by:

size in interface List

Specified by:

size in class AbstractCollection

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

Specified by:

isEmpty in interface List

Overrides:

isEmpty in class AbstractCollection

Returns:

true if the Vector is empty, false otherwise

See Also:

AbstractCollection.size()

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:

AbstractList.iterator()

contains

public boolean contains(Object elem)

Returns true when elem is contained in this Vector.

Specified by:

contains in interface Collection

Specified by:

contains in interface List

Overrides:

contains in class AbstractCollection

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

Overrides:

indexOf in class AbstractList

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

Overrides:

lastIndexOf in class AbstractList

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

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

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

Specified by:

toArray in interface List

Overrides:

toArray in class AbstractCollection

Returns:

an Object[] containing the contents of this Vector in order

Since:

1.2

toArray

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

Specified by:

toArray in interface List

Overrides:

toArray in class AbstractCollection

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 Object get(int index)

Returns the element at position index.

Specified by:

get in interface List

Specified by:

get in class AbstractList

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 Object set(int index,
                  Object element)

Puts element into the Vector at position index and returns the Object that previously occupied that position.

Specified by:

set in interface List

Overrides:

set in class AbstractList

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(Object o)

Adds an object to the Vector.

Specified by:

add in interface Collection

Specified by:

add in interface List

Overrides:

add in class AbstractList

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

Specified by:

remove in interface List

Overrides:

remove in class AbstractCollection

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,
                Object element)

Adds an object at the specified index. Elements at or above index are shifted up one position.

Specified by:

add in interface List

Overrides:

add in class AbstractList

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 Object remove(int index)

Removes the element at the specified index, and returns it.

Specified by:

remove in interface List

Overrides:

remove in class AbstractList

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

Specified by:

clear in interface List

Overrides:

clear in class AbstractList

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

Specified by:

containsAll in interface List

Overrides:

containsAll in class AbstractCollection

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

Specified by:

addAll in interface List

Overrides:

addAll in class AbstractCollection

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

Specified by:

removeAll in interface List

Overrides:

removeAll in class AbstractCollection

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

Specified by:

retainAll in interface List

Overrides:

retainAll in class AbstractCollection

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

Overrides:

addAll in class AbstractList

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

Specified by:

equals in interface List

Overrides:

equals in class AbstractList

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

Specified by:

hashCode in interface List

Overrides:

hashCode in class AbstractList

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

Returns:

the String representation of this Vector

See Also:

Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)

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

Overrides:

subList in class AbstractList

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

Parameters:

fromIndex - the index to start deleting from (inclusive)

toIndex - the index to delete up to (exclusive)

Throws:

IndexOutOfBoundsException - if fromIndex > toIndex