net.rim.device.api.util
Class SimpleSortingIntVector

java.lang.Object
  net.rim.device.api.util.IntVector
      net.rim.device.api.util.SimpleSortingIntVector

All Implemented Interfaces:

Persistable

public class SimpleSortingIntVector
extends IntVector

Simple sorting vector of integers.

Since:

BlackBerry API 4.2.1

Field Summary
static short	SORT_TYPE_COMPARISON sort using a comparator
static short	SORT_TYPE_NONE not sorted
static short	SORT_TYPE_NUMERIC sort numerically

Fields inherited from class net.rim.device.api.util.IntVector

capacityIncrement, elementCount, elementData

Constructor Summary

SimpleSortingIntVector()
Constructs a new SimpleSortingIntVector instance.

SimpleSortingIntVector(int initialCapacity)
Constructs an empty vector with the specified initial capacity.

SimpleSortingIntVector(int initialCapacity, int capacityIncrement)
Constructs an empty vector with the specified initial capacity and capacity increment.

Method Summary
void	addElement(int obj) Adds provided object to this vector.
int	bestGuessBinarySearch(int object) A bi-directional search that uses a binary search to guess the general vicinity of the required object, then branches out in either direction to find the exact object.
int	binarySearch(int obj, short sortType) Performs a binary search find the Object.
short	getSortState() Retrieves this Vector's current sort state.
int	linearSearch(int obj) Performs a linear search to find the Object.
void	reSort(short sortType) Sorts this vector using the supplied comparator
boolean	removeElement(int obj) Optimized removeElement() method.
boolean	setSortAsAdded(short sortType) Set the option to sort this vector as elements are added
void	setSortComparator(IntComparator newComparator, boolean sortNow, boolean uniqueValueComparator) Sets a new comparator for use with this sorting vector.

Methods inherited from class net.rim.device.api.util.IntVector

capacity, contains, copyInto, elementAt, ensureCapacity, firstElement, getArray, indexOf, indexOf, insertElementAt, isEmpty, lastElement, lastIndexOf, lastIndexOf, removeAllElements, removeElementAt, setElementAt, setSize, size, toArray, trimToSize

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SORT_TYPE_NUMERIC

public static final short SORT_TYPE_NUMERIC

sort numerically

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

SORT_TYPE_COMPARISON

public static final short SORT_TYPE_COMPARISON

sort using a comparator

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

SORT_TYPE_NONE

public static final short SORT_TYPE_NONE

not sorted

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

Constructor Detail

SimpleSortingIntVector

public SimpleSortingIntVector()

Constructs a new SimpleSortingIntVector instance.

Since:

BlackBerry API 4.2.1

SimpleSortingIntVector

public SimpleSortingIntVector(int initialCapacity)

Constructs an empty vector with the specified initial capacity.

Parameters:

initialCapacity - the initial capacity of the vector.

Since:

BlackBerry API 6.0.0

SimpleSortingIntVector

public SimpleSortingIntVector(int initialCapacity,
                              int capacityIncrement)

Constructs an empty vector with the specified initial capacity and capacity increment.

Parameters:

initialCapacity - - the initial capacity of the vector.

capacityIncrement - - the amount by which the capacity is increased when the vector overflows.

Since:

BlackBerry API 6.0.0

Method Detail

getSortState

public short getSortState()

Retrieves this Vector's current sort state. The sort state is set by SimpleSortingIntVector.setSortAsAdded(short).

Returns:

the current sort state of this Vector; will be equal to one of the SORT_TYPE_ constants defined in this class; the return value is undefined in this vector is empty or if no elements have been added since the last invocation of setSortAsAdded().

Since:

BlackBerry API 4.2.1

setSortComparator

public void setSortComparator(IntComparator newComparator,
                              boolean sortNow,
                              boolean uniqueValueComparator)

Sets a new comparator for use with this sorting vector.

If this vector is currently set to be sorted as elements are added, then this method also sorts the vector.

Parameters:

newComparator - New comparator to use when sorting this vector.

sortNow - True to sort array immediately using this comparator

uniqueValueComparator - True if the comparison is done on a unique value, if true this will optimize element operations

Throws:

NullPointerException - If the newComparator parameter is null.

Since:

BlackBerry API 4.2.1

setSortAsAdded

public boolean setSortAsAdded(short sortType)

Set the option to sort this vector as elements are added

Parameters:

sortType - Sort Type that should happen as elements are added, default: SORT_TYPE_NONE (not sorted)

Returns:

true if the operation was successful, false otherwise

Since:

BlackBerry API 4.2.1

reSort

public void reSort(short sortType)

Sorts this vector using the supplied comparator

Parameters:

sortType - How to sort this vector, one of SORT_TYPE_*

Since:

BlackBerry API 4.2.1

addElement

public void addElement(int obj)

Adds provided object to this vector.

If this vector was set to sort dynamically, then this vector sorts itself after the addition.

Overrides:

addElement in class IntVector

Parameters:

obj - Object to add.

Since:

BlackBerry API 4.2.1

removeElement

public boolean removeElement(int obj)

Optimized removeElement() method. Removes an element from the vector. If the vector is sorted either numerically or by a unique value comparator, the index of the object to delete is returned via a binary search to optimize the operation. If the vector is either unsorted or sorted using a non unique value comparator, a linear search is performed to find the index of the object to delete. If the vector is sorted by a non unique value comparator, you may consider using the bestGuessSearch to return an index then pass it to removeElementAt(index).

Overrides:

removeElement in class IntVector

Parameters:

obj - Object to be delete

Returns:

True if the operation was successful, false otherwise

Since:

BlackBerry API 4.2.1

binarySearch

public int binarySearch(int obj,
                        short sortType)

Performs a binary search find the Object. Note: This function will sort the array as specified if not already sorted.

Parameters:

obj - Object to find

Returns:

Index of the object if contained in the vector that invokes this method. If the object is not contained in the vector, the method returns (-(insertPoint + 1)), where the insert point is the position the object would occupy in the section of the vector that was searched. If the vector contains two or more of the search object, this method may return the index of any one of the matching objects; there is no guarantee which one it will return.

Throws:

IllegalStateException - if the sort type is SORT_TYPE_NONE.

Since:

BlackBerry API 4.2.1

bestGuessBinarySearch

public int bestGuessBinarySearch(int object)

A bi-directional search that uses a binary search to guess the general vicinity of the required object, then branches out in either direction to find the exact object. This method assume that every element in the vector is unique. This search can only be used when the SORT_TYPE is set to SORT_TYPE_COMPARISON. This search should only be used when the majority of the array is unequal according to the supplied comparator and the comparator does not use a unique value for comparison If the majority of the array is equal according to comparator this search will become less efficient than a linear search.

Returns:

An index representing the initial search position of the search object. If the object is not in the vector, the method returns -1. If the vector contains two or more of the search object, this method may return the index of any one of the matching objects; there is no guarantee which one it will return.

Throws:

IllegalStateException - if sortType is not SORT_TYPE_COMPARISON.

Since:

BlackBerry API 4.2.1

linearSearch

public int linearSearch(int obj)

Performs a linear search to find the Object. If the object does not exist, this method returns -1. If the vector contains more than one object that is equal to the search object, the method currently returns the index of the first object that matches the search object. Note: this will preserve existing ordering.

Parameters:

obj - Object To Find

Returns:

index of the object

Since:

BlackBerry API 4.2.1