Module net.automatalib.common.smartcollection
Package net.automatalib.common.smartcollection

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
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.

  • Method Details

    • get

      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

      ElementReference referencedAdd(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.

    • remove

      @Deprecated boolean remove(@Nullable Object element)
      Deprecated.
      use remove(ElementReference) instead
      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>

    • choose

      E choose()
      Retrieves an arbitrary element from the collection.
      Returns:
      an arbitrary element from the collection
      Throws:
      NoSuchElementException - if the collection is empty

    • chooseRef

      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

    • referenceIterator

      Iterator<ElementReference> referenceIterator()
      Retrieves an iterator for iterating over the references of elements in this collection.
      Returns:
      the reference iterator.

    • references

      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, 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

      @Nullable 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().