E
- element classpublic interface SmartCollection<E> extends Collection<E>
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 Iterator
s 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.Modifier and Type | Method and Description |
---|---|
void |
addAll(Iterable<? extends E> iterable)
Adds all elements from a given iterable.
|
<T extends E> |
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.
|
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray
E get(ElementReference ref)
ref
- the element's reference.ElementReference referencedAdd(E elem)
elem
- the element to be added.void remove(ElementReference elem)
elem
- the reference to the element to be removed.E choose()
null
is returned. Note, however, that a
null
return value doesn't necessary mean that the
collection is empty, since it may contain null
elements.null
.ElementReference chooseRef()
null
is returned. In contrast
to the above choose()
, this method returns null
if and only if the collection is empty.null
.@Deprecated boolean remove(Object element)
remove(ElementReference)
.remove
in interface Collection<E>
Collection.remove(Object)
Iterator<ElementReference> referenceIterator()
Iterable<ElementReference> references()
for
-loop.Iterable
with the above referenceIterator()
as its iterator.void addAll(Iterable<? extends E> iterable)
Collection
, because the
number of elements to be added is not known a priori.iterable
- the iterable of elements to add.<T extends E> void addAll(T[] array)
T
- array element class, may be a subclass of E
.array
- the array of elements to be added.void replace(ElementReference ref, E newElement)
ref
- the reference of the element to be replaced.newElement
- the replacement.ElementReference find(Object element)
null
is returned.element
- the element to search for.null
.void quickClear()
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.void deepClear()
quickClear()
.Copyright © 2015. All Rights Reserved.