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

java.lang.Object
  net.rim.device.api.collection.util.BigLongVector

All Implemented Interfaces:

Persistable

public class BigLongVector
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

BigLongVector()
Constructs a new empty vector.

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

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

Method Summary
void	addElement(long obj) Adds a new element to the end of this vector.
void	addElements(long[] array) Adds a number of elements to the end of this vector.
int	binarySearch(long value) Performs a binary search to locate a value.
int	copyInto(int offset, int len, long[] array, int dstPosition) Fills an array with elements from the vector.
long	elementAt(int index) Retrieves element by index.
int	firstIndexOf(long value) Finds first instance of value in list.
long[]	getContiguousArray() Returns a contiguous array representation of this vector.
void	insertElementAt(long obj, int index) Inserts element at index.
void	insertElementsAt(long[] 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(long 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

BigLongVector

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

BigLongVector

public BigLongVector(int initialCapacity)

Constructs a new empty vector with the specified initial capacity and chunk size.

Parameters:

initialCapacity - Initial capacity of the vector.

BigLongVector

public BigLongVector()

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 long[] 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 long 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(long 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(long 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(long 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(long[] 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(long 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(long[] 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,
                    long[] 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(long 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.