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 Detail

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

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

      • 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().