net.automatalib.commons.smartcollections

Interface SmartCollection<E>

Type Parameters:

E - element class

All Superinterfaces:

Collection<E>, Iterable<E>

All Known Subinterfaces:

SmartDeque<E>, SmartDynamicPriorityQueue<E>, SmartGeneralPriorityQueue<E,K>, SmartPriorityQueue<E>, SmartSequence<E>

All Known Implementing Classes:

AbstractLinkedList, AbstractSmartCollection, BackedGeneralPriorityQueue, BinaryHeap, DefaultLinkedList, IntrusiveLinkedList, UnorderedCollection

@ParametersAreNonnullByDefault
public interface SmartCollection<E>
extends Collection<E>

An extended collection interface. This interface overcomes various shortcomings of the Collection interface from the Java Collections Framework, and also introduces other features not present in other libraries (such as the Apache Commons Collections Library). Efficiently operating on collections data structures is often hampered by the insufficient interface provided by the standard Java collections. For example, linked lists allow constant time removal if the element to be removed is known. However, using List.remove(int) requires linear time in the provided parameter (and thus, in the worst case, linear time in the size of the list). Removal in constant time is possible when iterating manually using the Iterator.remove() method, but this is not only inconvenient, but also does not work if one wants to remove the elements later, because Iterators can't be cloned, and additionally are invalidated by other modifications of the underlying collection during their existence. This collection interface introduces a reference concept: References (represented by the marker interface ElementReference) to the elements allow efficient (in terms of what the data structure itself supports) operations on the elements, if the reference to the respective element is known. References can be acquired right at the point when an element is added to the collection (using referencedAdd(Object)), by explicitly searching for an element (using find(Object)) or during iteration (using the referenceIterator() resp. references() method). The validity of references is retained through all operations on the collection, except for those that cause removal of the respective elements.

Author:

Malte Isberner

Method Summary

Methods

Modifier and Type	Method and Description
void	addAll(Iterable<? extends E> iterable) Adds all elements from a given iterable.
<T extends E> void	addAll(T[] array) Adds all elements from the specified array.
E	choose() Retrieves an arbitrary element from the collection.
ElementReference	chooseRef() Retrieves the reference to an arbitrary element from the collection.
void	deepClear() Thoroughly clears the collection, fixing all issues that may have been caused by a call of the above quickClear().
ElementReference	find(Object element) Retrieves the reference for a given element.
E	get(ElementReference ref) Retrieves an element by its reference.
void	quickClear() Quickly clears this collection.
ElementReference	referencedAdd(E elem) Adds an element to the collection, returning a reference to the newly added element.
Iterator<ElementReference>	referenceIterator() Retrieves an iterator for iterating over the references of elements in this collection.
Iterable<ElementReference>	references() This is a method provided for convenience, which allows iterating over the element references using a foreach-style for-loop.
void	remove(ElementReference elem) Removes an element (by its reference) from the collection.
boolean	remove(Object element) Deprecated.
void	replace(ElementReference ref, E newElement) Replaces the element referenced by the given reference with the specified element.

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, removeAll, retainAll, size, toArray, toArray

Method Detail

get

@Nullable
E get(ElementReference ref)

Retrieves an element by its reference. If the reference belongs to another collection, the behavior is undefined.

Parameters:

ref - the element's reference.

Returns:

the element.

referencedAdd

@Nonnull
ElementReference referencedAdd(@Nullable
                                     E elem)

Adds an element to the collection, returning a reference to the newly added element. If the collection does not support containing the same element multiple times, a reference to the previously existing element is returned.

Parameters:

elem - the element to be added.

Returns:

a reference to this element in the collection.

remove

void remove(ElementReference elem)

Removes an element (by its reference) from the collection. If the reference does not belong to this collection, the behavior is undefined.

Parameters:

elem - the reference to the element to be removed.

choose

@Nullable
E choose()
         throws NoSuchElementException

Retrieves an arbitrary element from the collection. If the collection is empty, a NoSuchElementException is thrown

Returns:

an arbitrary element from the collection

Throws:

NoSuchElementException

chooseRef

@Nonnull
ElementReference chooseRef()

Retrieves the reference to an arbitrary element from the collection. If the collection is empty, a NoSuchElementException is thrown.

Returns:

the reference to an arbitrary element in the collection

remove

@Deprecated
boolean remove(@Nullable
                        Object element)

Deprecated.

This function is deprecated and should not be used, in favor of the removal by reference remove(ElementReference).

Specified by:

remove in interface Collection<E>

See Also:

Collection.remove(Object)

referenceIterator

@Nonnull
Iterator<ElementReference> referenceIterator()

Retrieves an iterator for iterating over the references of elements in this collection.

Returns:

the reference iterator.

references

@Nonnull
Iterable<ElementReference> references()

This is a method provided for convenience, which allows iterating over the element references using a foreach-style for-loop.

Returns:

an Iterable with the above referenceIterator() as its iterator.

addAll

void addAll(Iterable<? extends E> iterable)

Adds all elements from a given iterable. Note that this may be inefficient, compared to adding a Collection, because the number of elements to be added is not known a priori.

Parameters:

iterable - the iterable of elements to add.

addAll

<T extends E> void addAll(T[] array)

Adds all elements from the specified array.

Type Parameters:

T - array element class, may be a subclass of E.

Parameters:

array - the array of elements to be added.

replace

void replace(ElementReference ref,
           @Nullable
           E newElement)

Replaces the element referenced by the given reference with the specified element.

Parameters:

ref - the reference of the element to be replaced.

newElement - the replacement.

find

ElementReference find(@Nullable
                    Object element)

Retrieves the reference for a given element. If the element is not contained in the collection, null is returned.

Parameters:

element - the element to search for.

Returns:

the reference to this element, or null.

quickClear

void quickClear()

Quickly clears this collection. This method is supposed to perform the minimum amount of effort such that this collection is emptied, disregarding all other side-effects such as referencing or garbage collection issues. Depending on the implementation, this may be just the same as Collection.clear(). However, this could also have side-effects like hampering the garbage collection or such. After calling this method, even a call of the normal Collection.clear() is not guaranteed to fix all these issues. This can only be achieved by the method deepClear() below.

deepClear

void deepClear()

Thoroughly clears the collection, fixing all issues that may have been caused by a call of the above quickClear().