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

java.lang.Object
  extended by 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





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.