FileDocCategorySizeDatePackage
Vector.javaAPI DocJ2ME CLDC 1.118554Wed Feb 05 15:56:00 GMT 2003java.util

Vector

public class Vector extends Object
The Vector class implements a growable array of objects. Like an array, it contains components that can be accessed using an integer index. However, the size of a Vector can grow or shrink as needed to accommodate adding and removing items after the Vector has been created.

Each vector tries to optimize storage management by maintaining a capacity and a capacityIncrement. The capacity is always at least as large as the vector size; it is usually larger because as components are added to the vector, the vector's storage increases in chunks the size of capacityIncrement. An application can increase the capacity of a vector before inserting a large number of components; this reduces the amount of incremental reallocation.

author
Lee Boynton
author
Jonathan Payne
version
12/17/01 (CLDC 1.1)
since
JDK1.0, CLDC 1.0

Fields Summary
protected Object[]
elementData
The array buffer into which the components of the vector are stored. The capacity of the vector is the length of this array buffer.
protected int
elementCount
The number of valid components in the vector.
protected int
capacityIncrement
The amount by which the capacity of the vector is automatically incremented when its size becomes greater than its capacity. If the capacity increment is 0, the capacity of the vector is doubled each time it needs to grow.
Constructors Summary
public Vector(int initialCapacity, int capacityIncrement)
Constructs an empty vector with the specified initial capacity and capacity increment.

param
initialCapacity the initial capacity of the vector.
param
capacityIncrement the amount by which the capacity is increased when the vector overflows.
exception
IllegalArgumentException if the specified initial capacity is negative

        super();
        if (initialCapacity < 0)
            throw new IllegalArgumentException("Illegal Capacity: "+
                                               initialCapacity);
        this.elementData = new Object[initialCapacity];
        this.capacityIncrement = capacityIncrement;
    
public Vector(int initialCapacity)
Constructs an empty vector with the specified initial capacity.

param
initialCapacity the initial capacity of the vector.
since
JDK1.0

        this(initialCapacity, 0);
    
public Vector()
Constructs an empty vector.

since
JDK1.0

        this(10);
    
Methods Summary
public synchronized voidaddElement(java.lang.Object obj)
Adds the specified component to the end of this vector, increasing its size by one. The capacity of this vector is increased if its size becomes greater than its capacity.

param
obj the component to be added.
since
JDK1.0

        int newcount = elementCount + 1;
        if (newcount > elementData.length) {
            ensureCapacityHelper(newcount);
        }
        elementData[elementCount++] = obj;
    
public intcapacity()
Returns the current capacity of this vector.

return
the current capacity of this vector.
since
JDK1.0

        return elementData.length;
    
public booleancontains(java.lang.Object elem)
Tests if the specified object is a component in this vector.

param
elem an object.
return
true if the specified object is a component in this vector; false otherwise.
since
JDK1.0

        return indexOf(elem, 0) >= 0;
    
public synchronized voidcopyInto(java.lang.Object[] anArray)
Copies the components of this vector into the specified array. The array must be big enough to hold all the objects in this vector.

param
anArray the array into which the components get copied.
since
JDK1.0

        int i = elementCount;
        while (i-- > 0) {
            anArray[i] = elementData[i];
        }
    
public synchronized java.lang.ObjectelementAt(int index)
Returns the component at the specified index.

param
index an index into this vector.
return
the component at the specified index.
exception
ArrayIndexOutOfBoundsException if an invalid index was given.
since
JDK1.0

        if (index >= elementCount) {
            throw new ArrayIndexOutOfBoundsException(index + " >= " + elementCount);
        }
        /* Since try/catch is free, except when the exception is thrown,
           put in this extra try/catch to catch negative indexes and
           display a more informative error message.  This might not
           be appropriate, especially if we have a decent debugging
           environment - JP. */
        try {
            return elementData[index];
        } catch (ArrayIndexOutOfBoundsException e) {
            throw new ArrayIndexOutOfBoundsException(index + " < 0");
        }
    
public synchronized java.util.Enumerationelements()
Returns an enumeration of the components of this vector.

return
an enumeration of the components of this vector.
see
java.util.Enumeration
since
JDK1.0

        return new VectorEnumerator(this);
    
public synchronized voidensureCapacity(int minCapacity)
Increases the capacity of this vector, if necessary, to ensure that it can hold at least the number of components specified by the minimum capacity argument.

param
minCapacity the desired minimum capacity.
since
JDK1.0

        if (minCapacity > elementData.length) {
            ensureCapacityHelper(minCapacity);
        }
    
private voidensureCapacityHelper(int minCapacity)
This implements the unsynchronized semantics of ensureCapacity. Synchronized methods in this class can internally call this method for ensuring capacity without incurring the cost of an extra synchronization.

see
java.util.Vector#ensureCapacity(int)

        int oldCapacity = elementData.length;
        Object oldData[] = elementData;
        int newCapacity = (capacityIncrement > 0) ?
            (oldCapacity + capacityIncrement) : (oldCapacity * 2);
        if (newCapacity < minCapacity) {
            newCapacity = minCapacity;
        }
        elementData = new Object[newCapacity];
        System.arraycopy(oldData, 0, elementData, 0, elementCount);
    
public synchronized java.lang.ObjectfirstElement()
Returns the first component of this vector.

return
the first component of this vector.
exception
NoSuchElementException if this vector has no components.
since
JDK1.0

        if (elementCount == 0) {
            throw new NoSuchElementException();
        }
        return elementData[0];
    
public intindexOf(java.lang.Object elem)
Searches for the first occurence of the given argument, testing for equality using the equals method.

param
elem an object.
return
the index of the first occurrence of the argument in this vector; returns -1 if the object is not found.
see
java.lang.Object#equals(java.lang.Object)
since
JDK1.0

        return indexOf(elem, 0);
    
public synchronized intindexOf(java.lang.Object elem, int index)
Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.

param
elem an object.
param
index the index to start searching from.
return
the index of the first occurrence of the object argument in this vector at position index or later in the vector; returns -1 if the object is not found.
see
java.lang.Object#equals(java.lang.Object)
since
JDK1.0

        if (elem == null) {
            for (int i = index ; i < elementCount ; i++)
                if (elementData[i]==null)
                    return i;
        } else {
            for (int i = index ; i < elementCount ; i++)
                if (elem.equals(elementData[i]))
                    return i;
        }
        return -1;
    
public synchronized voidinsertElementAt(java.lang.Object obj, int index)
Inserts the specified object as a component in this vector at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

The index must be a value greater than or equal to 0 and less than or equal to the current size of the vector.

param
obj the component to insert.
param
index where to insert the new component.
exception
ArrayIndexOutOfBoundsException if the index was invalid.
see
java.util.Vector#size()
since
JDK1.0

        int newcount = elementCount + 1;
        if (index >= newcount) {
            throw new ArrayIndexOutOfBoundsException(index
                                                     + " > " + elementCount);
        }
        if (newcount > elementData.length) {
            ensureCapacityHelper(newcount);
        }
        System.arraycopy(elementData, index, elementData, index + 1, elementCount - index);
        elementData[index] = obj;
        elementCount++;
    
public booleanisEmpty()
Tests if this vector has no components.

return
true if this vector has no components; false otherwise.
since
JDK1.0

        return elementCount == 0;
    
public synchronized java.lang.ObjectlastElement()
Returns the last component of the vector.

return
the last component of the vector, i.e., the component at index size() - 1.
exception
NoSuchElementException if this vector is empty.
since
JDK1.0

        if (elementCount == 0) {
            throw new NoSuchElementException();
        }
        return elementData[elementCount - 1];
    
public intlastIndexOf(java.lang.Object elem)
Returns the index of the last occurrence of the specified object in this vector.

param
elem the desired component.
return
the index of the last occurrence of the specified object in this vector; returns -1 if the object is not found.
since
JDK1.0

        return lastIndexOf(elem, elementCount-1);
    
public synchronized intlastIndexOf(java.lang.Object elem, int index)
Searches backwards for the specified object, starting from the specified index, and returns an index to it.

param
elem the desired component.
param
index the index to start searching from.
return
the index of the last occurrence of the specified object in this vector at position less than index in the vector; -1 if the object is not found.
exception
IndexOutOfBoundsException if index is greater than or equal to the current size of this vector.
since
JDK1.0

        if (index >= elementCount) {
            throw new IndexOutOfBoundsException(index + " >= " + elementCount);
        }

        if (elem == null) {
            for (int i = index; i >= 0; i--)
                if (elementData[i]==null)
                    return i;
        } else {
            for (int i = index; i >= 0; i--)
                if (elem.equals(elementData[i]))
                    return i;
        }
        return -1;
    
public synchronized voidremoveAllElements()
Removes all components from this vector and sets its size to zero.

since
JDK1.0

        for (int i = 0; i < elementCount; i++) {
            elementData[i] = null;
        }
        elementCount = 0;
    
public synchronized booleanremoveElement(java.lang.Object obj)
Removes the first occurrence of the argument from this vector. If the object is found in this vector, each component in the vector with an index greater or equal to the object's index is shifted downward to have an index one smaller than the value it had previously.

param
obj the component to be removed.
return
true if the argument was a component of this vector; false otherwise.
since
JDK1.0

        int i = indexOf(obj);
        if (i >= 0) {
            removeElementAt(i);
            return true;
        }
        return false;
    
public synchronized voidremoveElementAt(int index)
Deletes the component at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously.

The index must be a value greater than or equal to 0 and less than the current size of the vector.

param
index the index of the object to remove.
exception
ArrayIndexOutOfBoundsException if the index was invalid.
see
java.util.Vector#size()
since
JDK1.0

        if (index >= elementCount) {
            throw new ArrayIndexOutOfBoundsException(index + " >= " +
                                                     elementCount);
        }
        else if (index < 0) {
            throw new ArrayIndexOutOfBoundsException(index);
        }
        int j = elementCount - index - 1;
        if (j > 0) {
            System.arraycopy(elementData, index + 1, elementData, index, j);
        }
        elementCount--;
        elementData[elementCount] = null; /* to let gc do its work */
    
public synchronized voidsetElementAt(java.lang.Object obj, int index)
Sets the component at the specified index of this vector to be the specified object. The previous component at that position is discarded.

The index must be a value greater than or equal to 0 and less than the current size of the vector.

param
obj what the component is to be set to.
param
index the specified index.
exception
ArrayIndexOutOfBoundsException if the index was invalid.
see
java.util.Vector#size()
since
JDK1.0

        if (index >= elementCount) {
            throw new ArrayIndexOutOfBoundsException(index + " >= " +
                                                     elementCount);
        }
        elementData[index] = obj;
    
public synchronized voidsetSize(int newSize)
Sets the size of this vector. If the new size is greater than the current size, new null items are added to the end of the vector. If the new size is less than the current size, all components at index newSize and greater are discarded.

param
newSize the new size of this vector.
throws
ArrayIndexOutOfBoundsException if new size is negative.
since
JDK1.0

        if ((newSize > elementCount) && (newSize > elementData.length)) {
            ensureCapacityHelper(newSize);
        } else {
            for (int i = newSize ; i < elementCount ; i++) {
                elementData[i] = null;
            }
        }
        elementCount = newSize;
    
public intsize()
Returns the number of components in this vector.

return
the number of components in this vector.
since
JDK1.0

        return elementCount;
    
public synchronized java.lang.StringtoString()
Returns a string representation of this vector.

return
a string representation of this vector.
since
JDK1.0

        int max = size() - 1;
        StringBuffer buf = new StringBuffer();
        Enumeration e = elements();
        buf.append("[");

        for (int i = 0 ; i <= max ; i++) {
            buf.append(e.nextElement());
            if (i < max) {
                buf.append(", ");
            }
        }
        buf.append("]");
        return buf.toString();
    
public synchronized voidtrimToSize()
Trims the capacity of this vector to be the vector's current size. An application can use this operation to minimize the storage of a vector.

since
JDK1.0

        int oldCapacity = elementData.length;
        if (elementCount < oldCapacity) {
            Object oldData[] = elementData;
            elementData = new Object[elementCount];
            System.arraycopy(oldData, 0, elementData, 0, elementCount);
        }