net.rim.device.api.util
Class SimpleSortingIntVector

java.lang.Object
  extended by net.rim.device.api.util.IntVector
      extended by 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





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.