org.openmdx.base.collection
Interface SparseArray

All Superinterfaces:

Collection, Iterable

All Known Implementing Classes:

AbstractSparseArray, MarshallingSparseArray, TreeSparseArray

public interface SparseArray
extends Collection

Sparsely Populated Array interface

Method Summary

boolean	add(Object o) Appends the specified element to the end of this sparse array (optional operation).
List	asList() A list backed up by the sparse array.
int	end() Return the index where add() would insert an element.
Object	get(int index) Returns the element at the specified position in this sparse array.
int	indexOf(Object o) Returns the index in this sparse array of the first occurrence of the specified element, or -1 if this sparse array does not contain this element.
Iterator	iterator() Returns an iterator over the elements in this sparse array (in proper sequence).
PopulationIterator	populationIterator() Returns an iterator for the populated elements in this sparse array (in proper sequence).
PopulationIterator	populationIterator(int fromIndex) Returns an iterator for the populated elements in this sparse array (in proper sequence).
SortedMap	populationMap() Returns a map view of this sparse array's populated elements.
Object	remove(int index) Removes the element at the specified position in this sparse array (optional operation).
Object	set(int index, Object element) Replaces the element at the specified position in this sparse array with the specified element (optional operation).
void	setAll(SparseArray t) Copies all of the entries from the specified sparse array to this sparse array (optional operation).
int	size() Returns the number of (non-null) elements in this sparse array.
int	start() Return the index of the first populated element in the sparse array or -1 if the sparse array is empty.
SparseArray	subArray(int fromIndex, int toIndex) Returns a view of the portion of this sparse array between the specified fromIndex, inclusive, and toIndex, exclusive.

Methods inherited from interface java.util.Collection

addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, toArray, toArray

Method Detail

size

int size()

Returns the number of (non-null) elements in this sparse array. If this sparse array contains more than Integer.MAX_VALUE elements or if its size can't be determined yet it returns Integer.MAX_VALUE.

Specified by:

size in interface Collection

Returns:

the number of elements in this sparse array.

iterator

Iterator iterator()

Returns an iterator over the elements in this sparse array (in proper sequence).

Specified by:

iterator in interface Collection

Specified by:

iterator in interface Iterable

Returns:

an iterator over the elements in this sparse array (in proper sequence).

asList

List asList()

A list backed up by the sparse array. Its size() is the sparse array's lastIndex() + 1 and the sparse array's un-populated positions are represented as null values.

Returns:

a list representing the sparse array

start

int start()

Return the index of the first populated element in the sparse array or -1 if the sparse array is empty.

Returns:

the index of the first populated element in the sparse array.

end

int end()

Return the index where add() would insert an element.

Returns:

the index of the last populated element in the sparse array incremented by one unless the sparse array is empty; if it is empty fromIndex is returned for subarrays, 0 otherwise.

get

Object get(int index)

Returns the element at the specified position in this sparse array.

Parameters:

index - index of element to return.

Returns:

the element at the specified position in this sparse array.

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0).

set

Object set(int index,
           Object element)

Replaces the element at the specified position in this sparse array with the specified element (optional operation).

set(i,null) is equivalent to remove(i).

Parameters:

index - index of element to replace.

element - element to be stored at the specified position.

Returns:

the element previously at the specified position.

Throws:

UnsupportedOperationException - if the set method is not supported by this sparse array.

ClassCastException - - if the class of the specified element prevents it from being added to this sparse array.

IllegalArgumentException - if some aspect of the specified element prevents it from being added to this sparse array.

IndexOutOfBoundsException - if the index is out of range (index < 0).

setAll

void setAll(SparseArray t)

Copies all of the entries from the specified sparse array to this sparse array (optional operation). These settings will replace any setings that this sparse array had for any of the indices currently in the specified sparse array.

Parameters:

t - Entries to be stored in this sparse array.

Throws:

UnsupportedOperationException - if the setAll method is not supported by this sparse array.

ClassCastException - if the class of a value in the specified sparse array prevents it from being stored in this sparse array.

IllegalArgumentException - some aspect of a value in the specified sparse array prevents it from being stored in this sparse array.

add

boolean add(Object o)

Appends the specified element to the end of this sparse array (optional operation).

Adding a null value to a sparse array does nothing.

Sparse arrays that support this operation may place limitations on what elements may be added to this sparse array. In particular, some sparse arrays will impose restrictions on the type of elements that may be added. Sparse array classes should clearly specify in their documentation any restrictions on what elements may be added.

Specified by:

add in interface Collection

Parameters:

o - element to be appended to this sparse array.

Returns:

true if o != null; false otherwise.

Throws:

UnsupportedOperationException - if the add method is not supported by this sparse array.

ClassCastException - if the class of the specified element prevents it from being added to this sparse array.

IllegalArgumentException - if some aspect of this element prevents it from being added to this collection.

remove

Object remove(int index)

Removes the element at the specified position in this sparse array (optional operation). Returns the element that was removed from the sparse array.

remove(i) is equivalent to set(i,null).

Parameters:

index - the index of the element to removed.

Returns:

the element previously at the specified position; or null the specified position was not occupied before.

Throws:

UnsupportedOperationException - if the remove method is not supported by this sparse array.

IndexOutOfBoundsException - if the index is out of range (index < 0).

indexOf

int indexOf(Object o)

Returns the index in this sparse array of the first occurrence of the specified element, or -1 if this sparse array does not contain this element. More formally, returns the lowest index i such that (o==null ? get(i)==null : o.equals(get(i))), or -1 if there is no such index.

Parameters:

o - element to search for.

Returns:

the index in this sparse array of the first occurrence of the specified element, or -1 if this sparse array does not contain this element.

populationIterator

PopulationIterator populationIterator()

Returns an iterator for the populated elements in this sparse array (in proper sequence). The first index is start() and the last end() - 1 respectively. The indices are not contiguous.

Returns:

an iterator over the populated elements in the sparse array

See Also:

populationIterator(int), start(), end()

populationIterator

PopulationIterator populationIterator(int fromIndex)

Returns an iterator for the populated elements in this sparse array (in proper sequence). The first index is greater or equal fromIndex and the last end() - 1 respectively. The indices are not contiguous.

Returns:

an iterator over the populated elements in the sparse array

See Also:

populationIterator(), end()

populationMap

SortedMap populationMap()

Returns a map view of this sparse array's populated elements. The map's iterator will return the entries in ascending order. The map is backed by the sparse array, so changes to the sparse array are reflected in the map, and vice-versa. If the sparse array is modified while an iteration over the map is in progress, the results of the iteration are undefined. The map supports element removal, which removes the corresponding entry from the sparse array, via the Iterator.remove, Map.remove, removeAll retainAll, and clear operations. It does not support the add or addAll operations.

Returns:

a map view of this sparse array's populated elements

subArray

SparseArray subArray(int fromIndex,
                     int toIndex)

Returns a view of the portion of this sparse array between the specified fromIndex, inclusive, and toIndex, exclusive. (If fromIndex and toIndex are equal, the returned sparse array is empty.) The returned sparse array is backed by this sparse array, so changes in the returned sparse array are reflected in this sparse array, and vice-versa. The returned sparse array supports all of the optional sparse array operations supported by this sparse array.

This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a sparse array can be used as a range operation by passing a subArray view instead of a whole sparse array. For example, the following idiom removes a range of elements from a sparse array:

list.subArray(from, to).clear();

Similar idioms may be constructed for indexOf and lastIndexOf, and all of the algorithms in the Collections class can be applied to a subArray.

The semantics of the sparse array returned by this method become undefined if the backing sparse array (i.e., this sparse array) is structurally modified in any way other than via the returned sparse array. (Structural modifications are those that change the size of this sparse array, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.)

Parameters:

fromIndex - low endpoint (inclusive) of the subArray.

toIndex - high endpoint (exclusive) of the subArray.

Returns:

a view of the specified range within this sparse array.

Throws:

IndexOutOfBoundsException - for an illegal endpoint index value (fromIndex < 0 || fromIndex > toIndex).