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

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

public class BigIntVector
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
BigIntVector()
          Constructs a new empty vector.
BigIntVector(int initialCapacity)
          Constructs a new empty vector with the specified initial capacity and chunk size.
BigIntVector(int initialCapacity, int chunkSize)
          Constructs a new empty vector with the specified initial capacity and chunk size.
 
Method Summary
 void addElement(int obj)
          Adds a new element to the end of this vector.
 void addElements(int[] array)
          Adds a number of elements to the end of this vector.
 int binarySearch(int value)
          Performs a binary search to locate a value.
 int copyInto(int offset, int len, int[] array, int dstPosition)
          Fills an array with elements from the vector.
 int elementAt(int index)
          Retrieves element by index.
 int firstIndexOf(int value)
          Finds first instance of value in list.
 int[] getContiguousArray()
          Returns a contiguous array representation of this vector.
 void insertElementAt(int obj, int index)
          Inserts element at index.
 void insertElementsAt(int[] 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.
 void removeElementAt(int index)
          Deletes element by index.
 void setElementAt(int value, int index)
          Sets value of element by index.
 int size()
          Returns the number of elements in this vector.
 void sort()
          Sorts this vector in ascending integer order.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

BigIntVector

public BigIntVector(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.

BigIntVector

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

Parameters:
initialCapacity - Initial capacity of the vector.

BigIntVector

public BigIntVector()
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 int[] 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.0.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 int 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(int 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(int 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(int 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(int[] 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(int 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(int[] 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,
                    int[] 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(int value)
Performs a binary search to locate a value.

This method fails if this vector is not sorted in ascending integer order.

Parameters:
value - Value to search 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()
Sorts this vector in ascending integer order.






Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.