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

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

All Implemented Interfaces:

Collection, ReadableIntMap, WritableList, Persistable

public class SparseList
extends Object
implements Persistable, WritableList, ReadableIntMap

Maintains a list where existing elements are guaranteed to keep their assigned index until they're removed from the list.

The index of any element is always guaranteed to be less than the number of elements contained in the collection (that is, when you remove an element from the list, its index gets reused by other new elements).

Also, if you remove an element from this list, its index is immediately placed in the list of free indices available for reallocation at any time. This collection is not guaranteed to reallocate indices in any particular order.

Note: It is more efficient to use SparseList.addAndGetIndex(java.lang.Object) to add an element to the collection and retrieve the index of the element in a single step rather than using SparseList.add(java.lang.Object) and then SparseList.getKey(java.lang.Object).

The collection is persistable as long as the elements in the list are persistable.

Constructor Summary

SparseList()
Constructs a new SparseList instance.

SparseList(int n)
Constructs a new SparseList instance with an initial number of indices.

Method Summary
void	add(Object element) Adds an element to this list.
int	addAndGetIndex(Object element) Adds an element to this list and return its index.
boolean	contains(int index) Determines if an index already has an associated element.
Enumeration	elements() Return an enumeration of all elements in the list.
Object	get(int index) Retrieves element by index.
int	getKey(Object element) Retrieves index by element.
void	insertAt(int index, Object element) Replaces element by index.
void	remove(Object element) Removes element.
void	removeAll() Flush this collection.
void	removeAt(int index) Removes element by index.
int	size() Retrieves the number of elements in this collection.

Methods inherited from class java.lang.Object

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

Constructor Detail

SparseList

public SparseList(int n)

Constructs a new SparseList instance with an initial number of indices.

Parameters:

n - Initial number of indices for elements to allocate.

SparseList

public SparseList()

Constructs a new SparseList instance.

This method creates a new SparseList instance with no indices pre-allocated for elements. If you know how many indices you require from the start, it may be more efficient to invoke SparseList.SparseList(int).

Method Detail

add

public void add(Object element)

Adds an element to this list.

Note: this method simply invokes SparseList.addAndGetIndex(java.lang.Object). If you want to keep the a local record of the index of elements as you add them, then you should invoke SparseList.addAndGetIndex(java.lang.Object) directly as it returns the index of the added element.

Specified by:

add in interface WritableList

Parameters:

element - Element to add (must not be null).

addAndGetIndex

public int addAndGetIndex(Object element)

Adds an element to this list and return its index.

Parameters:

element - Element to add (must not be null).

Returns:

Index of added element.

insertAt

public void insertAt(int index,
                     Object element)

Replaces element by index.

Specified by:

insertAt in interface WritableList

Parameters:

index - Index of the element to replace; this index must currently be used by an element.

element - New element to replace the old one; must not be null.

removeAt

public void removeAt(int index)

Removes element by index.

Specified by:

removeAt in interface WritableList

Parameters:

index - Index of the element to remove.

remove

public void remove(Object element)

Removes element.

Note: This operation is linear with respect to the number of elements in this list.

Specified by:

remove in interface WritableList

Parameters:

element - Element to remove.

removeAll

public void removeAll()

Flush this collection.

Specified by:

removeAll in interface WritableList

size

public int size()

Retrieves the number of elements in this collection.

Specified by:

size in interface ReadableIntMap

Returns:

Number of elements in this collection.

get

public Object get(int index)

Retrieves element by index.

Specified by:

get in interface ReadableIntMap

Parameters:

index - Index of element you wish to retrieve.

Returns:

Element with specified index, or null if your index has no associated element.

getKey

public int getKey(Object element)

Retrieves index by element.

Note: This operation is linear with respect to the number of elements in the list.

Specified by:

getKey in interface ReadableIntMap

Parameters:

element - Element for which you want the index.

Returns:

Index of specified element, or -1 if this collection does not contain your element.

contains

public boolean contains(int index)

Determines if an index already has an associated element.

Specified by:

contains in interface ReadableIntMap

Parameters:

index - Index in question.

Returns:

True if this list already has an element at your index; otherwise, false.

elements

public Enumeration elements()

Return an enumeration of all elements in the list.

Returns:

All elements in the list as an enumeration.

Since:

BlackBerry API 4.1.0