goldman.collection.tagged
Interface TaggedCollection<T,E>

All Superinterfaces:
Iterable<TaggedElement<T,E>>
All Known Subinterfaces:
Mapping<K,E>, TaggedDigitizedOrderedCollection<T,E>, TaggedOrderedCollection<T,E>, TaggedPriorityQueue<T,E>, TaggedSpatialCollection<T,E>, TrackedTagged<T,E>
All Known Implementing Classes:
DirectAddressingMapping, InTree, OpenAddressingMapping, SeparateChainingMapping, ShortestPathMatrix, TaggedBinaryHeap, TaggedBinarySearchTree, TaggedBPlusTree, TaggedBTree, TaggedCollectionWrapper, TaggedCompactTrie, TaggedCompressedTrie, TaggedDigitizedOrderedCollectionWrapper, TaggedFibonacciHeap, TaggedKDTree, TaggedLeftistHeap, TaggedOrderedCollectionWrapper, TaggedPairingHeap, TaggedPatriciaTrie, TaggedPriorityQueueWrapper, TaggedQuadTree, TaggedRedBlackTree, TaggedSkipList, TaggedSortedArray, TaggedSpatialCollectionWrapper, TaggedSplayTree, TaggedTernarySearchTrie, TaggedTrie

public interface TaggedCollection<T,E>
extends Iterable<TaggedElement<T,E>>

A tagged collection is a variation of an algorithmically positioned collections (e.g., ordered collection, priority queue, spatial collection) that uses a tag associated with each element to determine their proper placement within the data structure. In other words, the application provides, for each element, an external tag that is to be associated with that element in the collection. Most tagged collections permit duplicate tags. However, some tagged collections enforce the restriction that tags are unique. Each tag in such a collection is called a key, because it can be presented to the collection in order to find its associated element. However, even when the tags are unique, multiple keys may map to the same element.


Method Summary
 void accept(Visitor<? super TaggedElement<T,E>> v)
          Traverses each tagged element of this collection, in the iteration order, on behalf of the visitor.
 void clear()
          Removes all tagged elements from this collection.
 boolean contains(T tag)
          Returns true if a tagged element with an equivalent tag exists in this collection.
 Iterator<E> elements()
          Returns an iterator over the elements that has been initialized to just before the first element in the iteration order.
 void ensureCapacity(int capacity)
          Increases the capacity of this tagged collection, if necessary, to ensure that it can hold at least capacity tagged elements.
 E get(T tag)
          Returns an element with the given tag.
 int getCapacity()
          Returns the current capacity of this tagged collection.
 Locator<TaggedElement<T,E>> getLocator(T tag)
          Returns a locator that has been initialized to a tagged element with an equivalent tag.
 int getSize()
          Returns the number of tagged elements, size, in this collection.
 boolean isEmpty()
          Returns true if this collection contains no elements, and otherwise returns false.
 Iterator<TaggedElement<T,E>> iterator()
          Returns an iterator that has been initialized to FORE.
 void put(T tag, E element)
          This method creates a new tagged element with the given values and inserts this tagged element into this collection.
 void putAll(TaggedCollection<T,E> tc)
          Adds all tagged elements in tc to this tagged collection.
 E remove(T tag)
          Removes, from this tagged collection, a tagged element with the given tag.
 Iterator<T> tags()
          Returns an iterator over the tags that has been initialized to just before the first tag in the iteration order.
 String toString()
          Returns a string that describes each tagged element in the collection, in the iteration order.
 void trimToSize()
          Trims the capacity of this tagged collection to be its current size.
 Collection<E> values()
          Returns a collection of all the elements held in this tagged collection.
 

Method Detail

accept

void accept(Visitor<? super TaggedElement<T,E>> v)
Traverses each tagged element of this collection, in the iteration order, on behalf of the visitor.


clear

void clear()
Removes all tagged elements from this collection.


contains

boolean contains(T tag)
Returns true if a tagged element with an equivalent tag exists in this collection. Otherwise false is returned.


elements

Iterator<E> elements()
Returns an iterator over the elements that has been initialized to just before the first element in the iteration order. The iteration order of the elements is defined based on the iteration order of the associated tags.


ensureCapacity

void ensureCapacity(int capacity)
Increases the capacity of this tagged collection, if necessary, to ensure that it can hold at least capacity tagged elements.


get

E get(T tag)
Returns an element with the given tag. This method requires that tag be in use. It throws a NoSuchElementException otherwise


getCapacity

int getCapacity()
Returns the current capacity of this tagged collection.


getLocator

Locator<TaggedElement<T,E>> getLocator(T tag)
Returns a locator that has been initialized to a tagged element with an equivalent tag. Like the iterator method, this method enables navigation, but from a specified starting point. This method throws a NoSuchElementException if there is no tagged element with an equivalent tag in the collection.


getSize

int getSize()
Returns the number of tagged elements, size, in this collection.


isEmpty

boolean isEmpty()
Returns true if this collection contains no elements, and otherwise returns false.


iterator

Iterator<TaggedElement<T,E>> iterator()
Returns an iterator that has been initialized to FORE. The returned iterator can be used to navigate within the collection and to remove the element currently associated with the iterator. In general, no assumption is made about the iteration order, the order in which the iterator advances through the collection. However, some tagged collections specify a particular iteration order based on the values of the tags.

Specified by:
iterator in interface Iterable<TaggedElement<T,E>>

put

void put(T tag,
         E element)
This method creates a new tagged element with the given values and inserts this tagged element into this collection. An AtCapacityException, an unchecked exception, is thrown if the collection is already at capacity.


putAll

void putAll(TaggedCollection<T,E> tc)
Adds all tagged elements in tc to this tagged collection.


remove

E remove(T tag)
Removes, from this tagged collection, a tagged element with the given tag. Returns the element that was removed, and throws a NoSuchElementException when there is no element with an equivalent tag.


tags

Iterator<T> tags()
Returns an iterator over the tags that has been initialized to just before the first tag in the iteration order.


toString

String toString()
Returns a string that describes each tagged element in the collection, in the iteration order.

Overrides:
toString in class Object

trimToSize

void trimToSize()
Trims the capacity of this tagged collection to be its current size. An application can use this operation to minimize the space usage when future insertions are unlikely.


values

Collection<E> values()
Returns a collection of all the elements held in this tagged collection. Adding (or removing) elements to (or from) the returned collection does not change the tagged collection.