net.rim.device.api.collection.util
Class BigVector

java.lang.Object
  extended by net.rim.device.api.collection.util.BigVector
All Implemented Interfaces:
Persistable

public class BigVector
extends Object
implements Persistable

Vector optimized to support insert/delete operations without shuffling the entire array.

The insert/delete operations are accomplished by sorting the elements in variable sized sub-arrays, or "chunks". Additionally, the underlying vector can be made contiguous for intensive operations, like sorting.


Constructor Summary
BigVector()
          Constructs a new empty vector.
BigVector(int initialCapacity)
          Constructs a new empty vector with the specified initial capacity and chunk size.
BigVector(int initialCapacity, int chunkSize)
          Constructs a new empty vector with the specified initial capacity and chunk size.
 
Method Summary
 void addElement(Object obj)
          Adds a new element to the end of this vector.
 void addElements(Object[] array)
          Adds a number of elements to the end of this vector.
 int binarySearch(Comparator cmp, Object value)
          Performs a binary search to locate a value.
 int copyInto(int offset, int len, Object[] array, int dstPosition)
          Fills an array with elements from the vector.
 Object elementAt(int index)
          Retrieves element by index.
 int firstIndexOf(Object value)
          Finds first instance of value in list.
 Object[] getContiguousArray()
          Returns a contiguous array representation of this vector.
 int getIndex(Comparator cmp, Object o)
          Retrieves index by element.
 void insertElement(Comparator cmp, Object e)
          Inserts element into vector.
 void insertElementAt(Object obj, int index)
          Inserts element at index.
 void insertElementsAt(Object[] array, int index)
          Inserts a number of elements at index.
 boolean isEmpty()
          Determines if this vector has no elements.
 void optimize()
          Optimize this vector for fast element access by turning the underlying representation into a contiguous array.
 void removeAll()
          Removes all this vector's elements.
 boolean removeElement(Comparator cmp, Object e)
          Removes element from vector.
 void removeElementAt(int index)
          Deletes element by index.
 void setElementAt(Object value, int index)
          Sets value of element by index.
 int size()
          Returns the number of elements in this vector.
 void sort(Comparator cmp)
          Sorts this vector with a comparator.
 boolean updateElement(Comparator cmp, Object o, Object n)
          Replaces element in this vector with a new one.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

BigVector

public BigVector(int initialCapacity,
                 int chunkSize)
Constructs a new empty vector with the specified initial capacity and chunk size.

Parameters:
initialCapacity - Initial capacity of the vector.
chunkSize - Size of each chunk.

BigVector

public BigVector(int initialCapacity)
Constructs a new empty vector with the specified initial capacity and chunk size.

Parameters:
initialCapacity - Initial capacity of the vector.

BigVector

public BigVector()
Constructs a new empty vector.



Method Detail

size

public int size()
Returns the number of elements in this vector.

Returns:
Size of this vector.

getContiguousArray

public Object[] getContiguousArray()
Returns a contiguous array representation of this vector.

The underlying storage of the container can be a series of variable-sized sub-arrays, this method consolidates all of the storage into one array. The returned array should be treated as read-only, any modification of the array could disrupt the behaviour of the container.

Returns:
Contiguous array representation of this vector. The array may be bigger than the vector size.
Since:
BlackBerry API 4.2.0

optimize

public void optimize()
Optimize this vector for fast element access by turning the underlying representation into a contiguous array.

To improve this vector's performance, invoke this method after doing many insertions and/or deletions.


isEmpty

public boolean isEmpty()
Determines if this vector has no elements.

Returns:
True if this vector is empty; otherwise, false.

elementAt

public Object elementAt(int index)
Retrieves element by index.

Parameters:
index - Position of element to retrieve.
Returns:
Element at specified index.
Throws:
ArrayIndexOutOfBoundsException - If invalid index.

firstIndexOf

public int firstIndexOf(Object value)
Finds first instance of value in list.

Note: this method does not use Object.equals(java.lang.Object) for comparison, since that would be too expensive. This method is still expensive, though, and you should use it carefully and sparingly.

Parameters:
value - Value to search for.
Returns:
Index of first instance of your value, or -1 if the value does not exist in this vector.

setElementAt

public void setElementAt(Object value,
                         int index)
Sets value of element by index.

This method replaces the existing value of the element with your new value.

Parameters:
value - New value for element at index.
index - Index of element to change; must be at least 0 and less than the size of this vector..
Throws:
ArrayIndexOutOfBoundsException - If invalid index.

removeElementAt

public void removeElementAt(int index)
Deletes element by index.

This method removes the specified element from the vector, and shifts all elements beyond it back one slot.

Parameters:
index - Index of element to remove; must be at least 0 and less than the size of this vector.
Throws:
ArrayIndexOutOfBoundsException - If invalid index.

removeAll

public void removeAll()
Removes all this vector's elements.


insertElementAt

public void insertElementAt(Object obj,
                            int index)
Inserts element at index.

This method adds a new element at your specified index. The existing element at that position, and all elements beyond it, get shifted up one slot.

Parameters:
obj - Element to insert.
index - Position new element should occupy; must be at least 0 and less than the size of this vector.
Throws:
ArrayIndexOutOfBoundsException - If invalid index.

insertElementsAt

public void insertElementsAt(Object[] array,
                             int index)
Inserts a number of elements at index.

This method adds a number of elements, the first at your specified index. The existing element at that position, and all the elements beyond it, are shifted up a number of slots equal to the size of the array inserted.

Parameters:
array - Elements to insert.
index - Position new element should occupy; must be at least 0 and less than the size of this vector.
Throws:
ArrayIndexOutOfBoundsException - if the index was invalid

addElement

public void addElement(Object obj)
Adds a new element to the end of this vector.

If needed, this vector's size increases by one.

Parameters:
obj - Element to add.

addElements

public void addElements(Object[] array)
Adds a number of elements to the end of this vector.

This vector's size increases as needed to include all the new elements.

Parameters:
array - Elements to add.

copyInto

public int copyInto(int offset,
                    int len,
                    Object[] array,
                    int dstPosition)
Fills an array with elements from the vector. The destination array must be large enough to hold all of the copied elements, starting at position dstPosition.

Parameters:
offset - The offset into the vector of the first element to be copied.
len - The number of elements to read from the vector.
array - The array to fill with the copied elements.
dstPosition - The position in the destination array at which to begin storing the copied elements.
Returns:
The number of elements read from the vector.

binarySearch

public int binarySearch(Comparator cmp,
                        Object value)
Performs a binary search to locate a value.

Parameters:
cmp - Comparator used for the search; if this vector is not sorted in a way this comparator understands, this method fails.
value - Value to look for.
Returns:
The index of the found value, if contained in the vector. If the value is not contained in the vector, then this method returns ( -( insertPoint + 1 ) ); the insert point is the position the value would occupy in the vector.

sort

public void sort(Comparator cmp)
Sorts this vector with a comparator.

Parameters:
cmp - Comparator to assist in the sort.

removeElement

public boolean removeElement(Comparator cmp,
                             Object e)
Removes element from vector.

Parameters:
cmp - Comparator to assist in the removal.
e - Object to locate and remove.
Returns:
True if the object was found and removed; otherwise, false.

insertElement

public void insertElement(Comparator cmp,
                          Object e)
Inserts element into vector.

Parameters:
cmp - Commparator to determine where object should be inserted.
e - Object to insert.

updateElement

public boolean updateElement(Comparator cmp,
                             Object o,
                             Object n)
Replaces element in this vector with a new one.

Parameters:
cmp - Comparator to assist in the update.
o - Old object to replace.
n - New object to replace the old object.
Returns:
True if the old object was found and replaced; otherwise, false.

getIndex

public int getIndex(Comparator cmp,
                    Object o)
Retrieves index by element.

Parameters:
cmp - Comparator to assist in the search.
o - Object to find.
Returns:
Position of the element within this vector, or -1 if this vector does not contain your object.





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal