java.util

Class Vector

Implemented Interfaces:
Cloneable, Collection, Iterable, List, RandomAccess, Serializable
Known Direct Subclasses:
Stack

public class Vector
extends AbstractList
implements List, 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(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.
Vector(Collection c)
Constructs a vector containing the contents of Collection, in the order given by the collection.

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(int index, Collection c)
Inserts all elements of the given collection at the given index of this Vector.
boolean
addAll(Collection c)
Appends all elements of the given collection to the end 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.
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.
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 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.
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, ... elementN]".
void
trimToSize()
Trims the Vector down to size.

Methods inherited from class java.util.AbstractList

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

Methods inherited from class java.util.AbstractCollection

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, 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 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.

Constructor Details

Vector

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

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

Method Details

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

add

public boolean add(Object o)
Adds an object to the Vector.
Specified by:
add in interface List
add in interface Collection
Overrides:
add in interface AbstractList
Parameters:
o - the element to add to the Vector
Returns:
true, as specified by List
Since:
1.2

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

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 List
addAll in interface Collection
Overrides:
addAll in interface 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

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

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
clear in interface Collection
Overrides:
clear in interface AbstractList

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
contains in interface Collection
Overrides:
contains in interface AbstractCollection
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
containsAll in interface Collection
Overrides:
containsAll in interface 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

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

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)

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
equals in interface Collection
Overrides:
equals in interface AbstractList
Parameters:
o - the object to compare to
Returns:
true if the two are equal
Since:
1.2

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

get

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

hashCode

public int hashCode()
Computes the hashcode of this object.
Specified by:
hashCode in interface List
hashCode in interface Collection
Overrides:
hashCode in interface AbstractList
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
Overrides:
indexOf in interface 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

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

isEmpty

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

lastElement

public Object 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
Overrides:
lastIndexOf in interface 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()

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 interface AbstractList
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
remove in interface Collection
Overrides:
remove in interface AbstractCollection
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
removeAll in interface Collection
Overrides:
removeAll in interface AbstractCollection
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
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
retainAll in interface Collection
Overrides:
retainAll in interface AbstractCollection
Parameters:
c - the collection to filter by
Returns:
true if this vector changed
Throws:
NullPointerException - if c is null
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 interface 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

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

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
size in interface Collection
Overrides:
size in interface AbstractCollection
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
Overrides:
subList in interface 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

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
toArray in interface Collection
Overrides:
toArray in interface 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 List
toArray in interface Collection
Overrides:
toArray in interface 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

toString

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