goldman.collection
Interface Collection<E>

All Superinterfaces:
Iterable<E>
All Known Subinterfaces:
DigitizedOrderedCollection<E>, OrderedCollection<E>, PositionalCollection<E>, PriorityQueue<E>, Set<E>, SpatialCollection<E>, Tracked<E>
All Known Implementing Classes:
AbstractCollection, AbstractPositionalCollection, AbstractSearchTree, Array, BalancedBinarySearchTree, BinaryHeap, BinarySearchTree, BPlusTree, BTree, CircularArray, CompactTrie, CompressedTrie, DirectAddressing, DoublyLinkedList, DynamicArray, DynamicCircularArray, FibonacciHeap, KDTree, LeftistHeap, OpenAddressing, PairingHeap, PatriciaTrie, QuadTree, RedBlackTree, SeparateChaining, SinglyLinkedList, SkipList, SortedArray, SplayTree, TernarySearchTrie, TopDownBTree, TrackedArray, Trie

public interface Collection<E>
extends Iterable<E>

The Collection interface contains the operations that must be supported by all data structures that maintain a collection of elements. Checks, for the purposes of checking correctness, that the correctness properties are preserved.


Method Summary
 void accept(Visitor<? super E> v)
          Traverses each element of this collection, in the iteration order, on behalf of the visitor.
 void add(E value)
          Inserts value into the collection in an arbitrary location.
 void addAll(Collection<? extends E> c)
          Adds all elements in c to this collection.
 void checkRep()
           
 void clear()
          Removes all elements from this collection.
 boolean contains(E target)
          Returns true if an element equivalent to target exists in this collection.
 void ensureCapacity(int capacity)
          Increases the capacity of this collection, if necessary, to ensure that it can hold at least capacity elements.
 int getCapacity()
          Returns the current capacity of this collection.
 Comparator<? super E> getComparator()
          Returns the comparator for elements in this collection.
 E getEquivalentElement(E target)
          Returns an element in the collection that is equivalent to target.
 Locator<E> getLocator(E target)
          Returns a locator that has been initialized to an element equivalent to target.
 int getSize()
          Returns the number of elements, size, in this collection.
 boolean isEmpty()
          Returns true if this collection contains no elements, and otherwise returns false.
 Locator<E> iterator()
          Returns a locator that has been initialized to FORE.
 boolean remove(E target)
          Removes from this collection an arbitrary element equivalent to target, if such an element exists in the collection.
 void retainAll(Collection<E> c)
          Removes from this collection all elements for which there is no equivalent element in c.
 Object[] toArray()
          Returns a Java primitive array of length n that holds the elements in this collection in the iteration order.
 E[] toArray(E[] a)
          Fills a Java array with the elements in this collection in the iteration order, and returns the array that was filled.
 String toString()
          Returns a string that includes each element in this collection (as produced by the toString method for that element), in the iteration order.
 void trimToSize()
          Trims the capacity of an oversized collection to exactly hold its current elements.
 

Method Detail

checkRep

void checkRep()

accept

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


add

void add(E value)
Inserts value into the collection in an arbitrary location. If a tracker is to be returned then the method addTracked which is part of the Tracked interface should be called instead. An AtCapacityException (an unchecked exception) is thrown when a bounded collection is already at capacity.


addAll

void addAll(Collection<? extends E> c)
Adds all elements in c to this collection.


clear

void clear()
Removes all elements from this collection.


contains

boolean contains(E target)
Returns true if an element equivalent to target exists in this collection. Otherwise false is returned.


ensureCapacity

void ensureCapacity(int capacity)
Increases the capacity of this collection, if necessary, to ensure that it can hold at least capacity elements. For elastic implementations, this method does nothing.


getCapacity

int getCapacity()
Returns the current capacity of this collection. For elastic implementations Integer.MAX_VALUE is returned.


getComparator

Comparator<? super E> getComparator()
Returns the comparator for elements in this collection.


getEquivalentElement

E getEquivalentElement(E target)
Returns an element in the collection that is equivalent to target. It throws a NoSuchElementException when there is no equivalent element. The contains method should be used to determine if an element is in the collection.


getLocator

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


getSize

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


isEmpty

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


iterator

Locator<E> iterator()
Returns a locator that has been initialized to FORE. The locator returned can be used to navigate within the collection and to remove the element currently associated with the locator. In general, no assumption is made about the iteration order, the order in which the iterator advances through the collection. However, some collection ADTs specify a particular iteration order.

Specified by:
iterator in interface Iterable<E>

remove

boolean remove(E target)
Removes from this collection an arbitrary element equivalent to target, if such an element exists in the collection. It returns true if an element was removed, and false otherwise.


retainAll

void retainAll(Collection<E> c)
Removes from this collection all elements for which there is no equivalent element in c. Thus, the elements that remain are those in the intersection of c and this collection.


toArray

Object[] toArray()
Returns a Java primitive array of length n that holds the elements in this collection in the iteration order.


toArray

E[] toArray(E[] a)
Fills a Java array with the elements in this collection in the iteration order, and returns the array that was filled. If the array provided as a parameter is not large enough to hold all the elements of the collection, a new array of the same type is created with length n and is returned instead of the provided one.


toString

String toString()
Returns a string that includes each element in this collection (as produced by the toString method for that element), in the iteration order.

Overrides:
toString in class Object

trimToSize

void trimToSize()
Trims the capacity of an oversized collection to exactly hold its current elements. An application can use this operation to minimize the space usage. For elastic implementations, this method does nothing.