Class next.util.MutableVector

CLASS DESCRIPTION

Extends:
next.util.ImmutableVector

The MutableVector class declares the programmatic interface to objects that manage a modifiable array of objects. This class adds insertion and deletion operations to the basic array-handling behavior inherited from ImmutableVector. MutableVector methods are conceptually based on these primitive methods:

The other methods in its interface provide convenient ways of inserting an object into a specific slot in the array and removing an object based on its identity or position in the array.

A Note for Those Creating Subclasses of MutableVector

Although conceptually the MutableVector class has three primitive methods, two others also access the array's data directly. These methods are: These methods could be implemented using the primitives listed above but doing so would incur unnecessary overhead. For instance, objects would receive retain and release messages as they were shifted to accommodate the insertion or deletion of an element.

CONSTRUCTORS

MutableVector

public MutableVector()
public MutableVector(java.lang.Object[] objects)
public MutableVector(java.util.Vector aVector)

Initializes a newly allocated vector. After an immutable vector has been initialized, it can't be modified.

If objects are supplied, the vector is initialized by placing in it the objects contained in objects.

If aVector is supplied, the vector is initialized by placing in it the objects contained in the Java vector specified by aVector.


METHODS

addElement

public void addElement(java.lang.Object anObject)

Inserts anObject at the end of the receiver. If anObject is nil, an exception is raised.


addElements

public void addElements(next.util.ImmutableVector anImmutableVector)

Adds the objects contained in anImmutableVector to the end of the receiver's array of objects.


ensureCapacity

public void ensureCapacity(int count)

Ensures that the receiver is large enough to contain the number of elements specified by count.


insertElementAt

public void insertElementAt(java.lang.Object anObject, int index)

Inserts anObject into the receiver at index. If index is already occupied, the objects at index and beyond are shifted down one slot to make room. index cannot be greater than the number of elements in the vector. This method raises an exception if anObject is nil and raises an exception if index is greater than the number of elements in the vector.

Note that MutableVectors are not like C arrays. That is, even though you do an "ensureCapacity," the specified capacity is regarded as a "hint"; the actual size of the vector is still 0. Because of this, you can only insert new objects in ascending order-with no gaps. Once you add two objects, the vector's size is 2, so you can add objects at indexes 0, 1, or 2. Index 3 is illegal and out of bounds; if you try to add an object at index 3 (when the size of the vector is 2), MutableVector raises an exception.


removeAllElements

public void removeAllElements()

Empties the receiver of all its elements.


removeElement

public boolean removeElement(java.lang.Object anObject)

Removes the first occurrence of anObject in the vector. This method uses indexOf to locate a match, and then removes it by using removeElementAt.


removeElementAt

public void removeElementAt(int index)

Removes the object at index and moves all elements beyond index up one slot to fill the gap. This method raises an exception if index is beyond the end of the vector.


removeElements

public void removeElements(next.util.ImmutableVector anImmutableVector)

This method is similar to removeElement, but allows you to efficiently remove large sets of objects with a single operation.


replaceRange

protected void replaceRange(int start, int length, java.lang.Object anObject)

Removes length objects from the receiver (beginning with the object at index start) and inserts a single copy of anObject in their place.


setSize

public void setSize(int size)

If size is less than the number of elements in the receiver, a sufficient number of objects is removed from the end of the vector so that the size of the vector is equal to size. This method does nothing if the vector already has fewer elements than are specified by size.


sortUsingMethod

public void sortUsingMethod(java.lang.String comparator)

Sorts the receiver's elements in ascending order, as determined by the comparison method named by comparator. The comparator message is sent to each object in the vector, and has as its single argument another object in the vector. The comparator method is used to compare two elements at a time and should return -1 if the receiver is smaller than the argument, 1 if the receiver is larger than the argument, and 0 if they are equal.


trimToSize

public void trimToSize()

Sends a "hint" to the receiver that it should reduce adjust it's capacity to match the actual contents of the receiving vector.