java.util
Class Vector
java.lang.Object
|
+--java.util.AbstractCollection
|
+--java.util.AbstractList
|
+--java.util.Vector
All Implemented Interfaces:
List, RandomAccess, Cloneable, Serializable, List, Collection
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:Authors:- Scott G. Miller
- Bryce McKinlay
- Eric Blake <ebb9@email.byu.edu>
See Also:
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 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.
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:
Throws:
Vector
public Vector(int initialCapacity, int capacityIncrement)
Constructs a Vector with the initial capacity and capacity
increment specified.
Parameters:
Throws:
Vector
public Vector(java.util.Collection c)
Constructs a vector containing the contents of Collection, in the
order given by the collection.
Since:Parameters:
Throws:
add
public void add(int index, java.lang.Object element)
Adds an object at the specified index. Elements at or above
index are shifted up one position.
Since:Parameters:
Throws:
add
public boolean add(java.lang.Object o)
Adds an object to the Vector.
Since:Parameters:
Returns:
- true, as specified by List
addAll
public synchronized boolean addAll(int index, java.util.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).
Since:Parameters:
Returns:
- true if this vector changed, in other words c was not empty
Throws:
addAll
public synchronized boolean addAll(java.util.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).
Since:Parameters:
Returns:
- true if this vector changed, in other words c was not empty
Throws:
addElement
public synchronized void addElement(java.lang.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:
capacity
public synchronized 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.
clone
public synchronized Object clone()
Creates a new Vector with the same contents as this one. The clone is
shallow; elements are not cloned.
Returns:
contains
public boolean contains(java.lang.Object elem)
Returns true when elem
is contained in this Vector.
Parameters:
Returns:
- true if the object is contained in this Vector, false otherwise
containsAll
public synchronized boolean containsAll(java.util.Collection c)
Returns true if this Vector contains all the elements in c.
Since:Parameters:
Returns:
- true if this vector contains all elements of c
Throws:
copyInto
public synchronized void copyInto(java.lang.Object[] a)
Copies the contents of a provided array into the Vector. If the
array is too large to fit in the Vector, an IndexOutOfBoundsException
is thrown without modifying the array. Old elements in the Vector are
overwritten by the new elements.
Parameters:
Throws:
See Also:
elementAt
public synchronized Object elementAt(int index)
Returns the Object stored at index
.
Parameters:
Returns:
Throws:
See Also:
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:
See Also:
ensureCapacity
public synchronized 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:
equals
public synchronized boolean equals(java.lang.Object o)
Compares this to the given object.
Since:Parameters:
Returns:
- true if the two are equal
firstElement
public synchronized Object firstElement()
Returns the first element (index 0) in the Vector.
Returns:
- the first Object in the Vector
Throws:
get
public Object get(int index)
Returns the element at position index
.
Since:Parameters:
Returns:
- the element at that position
Throws:
hashCode
public synchronized int hashCode()
Computes the hashcode of this object.
Since:Returns:
indexOf
public int indexOf(java.lang.Object elem)
Returns the first occurrence of elem
in the Vector, or -1 if
elem
is not found.
Parameters:
Returns:
- the index of the first occurrence, or -1 if not found
indexOf
public synchronized int indexOf(java.lang.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:
Returns:
- the index of the next occurrence, or -1 if it is not found
Throws:
insertElementAt
public synchronized void insertElementAt(java.lang.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:
Throws:
See Also:
isEmpty
public synchronized boolean isEmpty()
Returns true if this Vector is empty, false otherwise
Returns:
- true if the Vector is empty, false otherwise
lastElement
public synchronized Object lastElement()
Returns the last element in the Vector.
Returns:
- the last Object in the Vector
Throws:
lastIndexOf
public int lastIndexOf(java.lang.Object elem)
Returns the last index of elem
within this Vector, or -1
if the object is not within the Vector.
Parameters:
Returns:
- the last index of the object, or -1 if not found
lastIndexOf
public synchronized int lastIndexOf(java.lang.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:
Returns:
- the index of the Object if found, -1 otherwise
Throws:
remove
public synchronized Object remove(int index)
Removes the element at the specified index, and returns it.
Since:Parameters:
Returns:
Throws:
remove
public boolean remove(java.lang.Object o)
Removes the given Object from the Vector. If it exists, true
is returned, if not, false is returned.
Since:Parameters:
Returns:
- true if the Object existed in the Vector, false otherwise
removeAll
public synchronized boolean removeAll(java.util.Collection c)
Remove from this vector all elements contained in the given collection.
Since:Parameters:
Returns:
- true if this vector changed
Throws:
removeAllElements
public synchronized void removeAllElements()
Removes all elements from the Vector. Note that this does not
resize the internal data array.
See Also:
removeElement
public synchronized boolean removeElement(java.lang.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:
Returns:
- true if the Object was in the Vector, false otherwise
See Also:
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:
Throws:
See Also:
removeRange
protected void removeRange(int fromIndex, int toIndex)
Removes a range of elements from this list.
Does nothing when toIndex is equal to fromIndex.
Parameters:
Throws:
retainAll
public synchronized boolean retainAll(java.util.Collection c)
Retain in this vector only the elements contained in the given collection.
Since:Parameters:
Returns:
- true if this vector changed
Throws:
set
public synchronized Object set(int index, java.lang.Object element)
Puts element
into the Vector at position index
and returns the Object that previously occupied that position.
Since:Parameters:
Returns:
- the previous object at the specified index
Throws:
setElementAt
public void setElementAt(java.lang.Object obj, int index)
Changes the element at index
to be obj
Parameters:
Throws:
See Also:
setSize
public synchronized 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:
Throws:
size
public synchronized int size()
Returns the number of elements stored in this Vector.
Returns:
- the number of elements in this Vector
subList
public synchronized 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.
Since:Parameters:
Returns:
- a List backed by a subsection of this vector
Throws:
See Also:
toArray
public synchronized 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).
Since:Returns:
- an Object[] containing the contents of this Vector in order
toArray
public synchronized Object[] toArray(java.lang.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.
Since:Parameters:
Returns:
- an array with the contents of this Vector in order
Throws:
toString
public synchronized String toString()
Returns a string representation of this Vector in the form
"[element0, element1, ... elementN]".
Returns:
- the String representation of this Vector
trimToSize
public synchronized 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
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 incapacityIncrement
. 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.